# Keysat Design System

> *Bitcoin-paid software licensing, self-hosted on Start9.*

Keysat is a **self-hosted licensing server** that indie software creators run on their own [Start9](https://start9.com) server. Buyers pay in Bitcoin via the creator's own [BTCPay Server](https://btcpayserver.org); Keysat issues an Ed25519-signed license key; the creator's software verifies that key offline against an embedded public key. **No SaaS, no middleman, no platform risk** — the creator owns the signing key, the customer list, and the payment rails.

The brand sits at the intersection of **classical trust signaling** (a notarized certificate, a vault key, a printed share certificate) and **modern indie-software practicality** — friendly, accessible, sovereign. The visual identity is anchored by the logo: a **deep navy key** crossing a **Bitcoin "B" bow**, set on **cream paper** with a **gold inner border**. That paper-and-ink character — restrained, classical, slightly archival — runs through the whole system.

---

## Source Materials

- `assets/keysat-logo-thumbnail.png` — the original 1024×1024 logo on cream paper texture, with the wordmark "KEYSAT" and tagline "Software Licensing for Bitcoin Creators."
- `assets/keysat-draft-site.html` — the draft single-page marketing site shipped with the project. Useful for **product context, copy, and feature scope** (see the value-prop grid, the "How it works" 5-step flow, the install instructions). The visual style is intentionally being replaced by this design system — do not pattern-match on its dark-mode + amber palette.

---

## Products

This system covers three surfaces:

1. **Marketing website** (`ui_kits/marketing/`) — public-facing single-page site. Hero, value props, how-it-works, integration code samples, install instructions, sovereign-by-default panel.
2. **Creator admin dashboard** (`ui_kits/dashboard/`) — authenticated. Where creators manage products, policies, license keys, discount codes, customers, audit log. Runs on the creator's own Start9.
3. **Docs site** (`ui_kits/docs/`) — developer-facing reference for the licensing wire format, SDKs (Rust / TypeScript / Python), and integration steps.

Note: there is **no "payouts" surface** — BTCPay Server handles all money. Keysat only deals with licenses, products, and customers.

---

## Index of Files

```
.
├── README.md                  ← this file
├── SKILL.md                   ← skill manifest (Agent Skills compatible)
├── colors_and_type.css        ← all CSS variables + base type styles
├── assets/                    ← logos, marks, the source draft site
├── preview/                   ← design-system review cards (auto-rendered)
└── ui_kits/
    ├── marketing/             ← landing page (single-page redesign)
    ├── dashboard/             ← admin: products, licenses, customers, audit
    └── docs/                  ← API reference, SDK guides
```

---

## Content Fundamentals

Keysat speaks to **indie creators selling software** — solo developers, small studios, makers of paid CLI tools, plugins, fonts, audio plugins, design tools — who care about **owning their stack**. They're technical and politically opinionated about platforms. They want plain answers, not crypto-bro hype.

**Voice & Tone**

- **Direct, plainspoken.** "Get paid in Bitcoin. Keep your signing key." not "Unlock the future of decentralized monetization."
- **Friendly but quietly serious.** This is money + cryptography software. We don't joke about losses, signing keys, or platform risk. We are warm but precise.
- **Sovereignty-first framing.** Copy reliably points at *what you own*: the key, the customer list, the payment rails. This is the brand's center of gravity.
- **"You" speaks to the creator** in marketing and dashboard copy. "We" speaks for Keysat sparingly.
- **No jargon walls.** When we have to use a term ("Ed25519", "BTCPay webhook", "sideload .s9pk"), we link to a one-sentence definition or example. We never assume the reader is already a Start9 user.
- **No hype words.** Avoid: *revolutionary, seamless, unlock, supercharge, leverage, ecosystem, journey, paradigm, game-changing.*
- **No emoji** in product UI. The brand has a quiet, archival quality. (The draft site uses ⚡🔐📡🎫🏷️🛠️ in the value grid — these will be replaced with Lucide icons.)

**Casing**

- **Sentence case** for buttons, menu items, headings: "Create a license", "Connect BTCPay".
- **ALL CAPS with wide tracking** for eyebrow labels above section headings ("FOR CREATORS", "HOW IT WORKS"). Sparingly.
- Product / proper nouns capitalized: **Keysat, Start9, StartOS, BTCPay, Bitcoin, Lightning, Ed25519**.

**Numbers, money, identifiers**

- Bitcoin amounts: `0.00214 BTC` or `214,000 sats`. Default to **sats** in the dashboard for amounts under 0.01 BTC.
- Fiat alongside crypto: `0.00214 BTC ≈ $128.40`.
- License keys are monospace, hyphen-grouped: `KS-9F2A-7C41-XK22-6D8E`.
- Public keys / hashes: monospace, ellipsized middle: `mz7q8…h3k2p`.
- File extensions / commands: inline mono, no decoration: `.s9pk`, `cargo add`, `npm install`.

**Examples (good ↔ bad)**

| Good | Bad |
|---|---|
| Bitcoin-paid software licensing, self-hosted on Start9. | Unlock the future of crypto-native software monetization ⚡️ |
| You own the signing key, the customer list, and the payment rails. | Revolutionary, seamless, decentralized rights management. |
| Five lines of integration code. Verifies real signatures. | Game-changing developer experience. |
| Connect BTCPay → Define products → Issue keys. | A frictionless creator journey. |
| Payout received: 214,000 sats | 🎉 Cha-ching! New sale! |

---

## Visual Foundations

The brand is **navy ink on cream paper, with a gold accent that whispers**. Think: a certificate of authenticity, a vault deed, a hand-numbered print. Modern in interaction, classical in composition.

### Palette

- **Navy** is the primary brand color. `--navy-800` (`#1E3A5F`) is the wordmark color and dominant ink. Used for primary buttons, headings, key UI chrome.
- **Cream** is the page background. `--cream-100` (`#F5F1E8`) is the default; `--cream-50` for elevated paper. Pure white is reserved for forms, tables, and code blocks where contrast matters.
- **Gold** (`--gold-500`, `#BFA068`) is the **accent color, used sparingly** — eyebrow labels, dividers, the inner stroke of premium cards, the highlight on a verified badge. **Never as a primary button color.**
- **Ink** scale (`--ink-900` → `--ink-300`) handles all body text, secondary copy, and disabled states.
- **No bluish-purple gradients. No Bitcoin orange in the UI** (per user direction — the navy/cream identity stands alone).

### Typography

- **Archivo** (display) — geometric sans, heavy at 800–900, mirrors the wordmark. Used for h1–h4, large numerals.
- **Inter** (body) — neutral humanist sans for paragraph text, UI labels, form fields. Stylistic sets `ss01` + `cv11`.
- **JetBrains Mono** (mono) — license keys, code samples, API responses, transaction IDs.

**Substitution flag**: Archivo is loaded from Google Fonts. The thumbnail wordmark looks closest to a custom geometric sans; Archivo is my best Google Fonts match. If Keysat has a licensed display face, swap `--font-display` and remove the Google import.

### Spacing & Layout

- 4px base grid. Tokens `--sp-1` (4) through `--sp-12` (128).
- Marketing pages breathe: sections often `--sp-11` (96px) apart. Dashboard density is moderate: table rows ~52px, card padding `--sp-6` (24px).
- Max content width on marketing: 1200px. Reading width for prose / docs: 680px.

### Backgrounds

- Default page background: **cream with a subtle grain** (`paper-texture` utility — two overlaid radial-dot grids at 2.5% opacity). Never pure flat color.
- Section bands alternate cream → cream-200 → cream-50 → navy-950 (for dark CTAs / footers). **No blue gradients, no glassmorphism, no purple.**
- Imagery, when present, is photographic with a warm/natural cast — printed paper, hardware (Coldcard, Start9 server), workshop scenes — not stock-photo people pointing at laptops. Black-and-white or duotone (navy/cream) for editorial feel.

### Borders, Radii & Cards

- **Radii are restrained.** Buttons: `--r-md` (8px). Cards: `--r-lg` (12px). Pills only for tags/badges. **No 24px+ rounding** — it makes the brand look like a fintech consumer app, which we are not.
- **Cards** sit on cream with a hairline border (`--border-1`, navy at 12% opacity) and a quiet shadow (`--shadow-sm`). Premium / featured cards get a 1px gold inner stroke (`--gold-500`) and `--shadow-md`.
- Section dividers can use a thin gold line (`--gold-500`) at 1px — sparingly, as a typographic flourish.

### Shadows

A **paper-shadow** system, not a glassy one:

- `--shadow-xs`, `--shadow-sm` for resting cards.
- `--shadow-md` for elevated cards, premium cards.
- `--shadow-lg` for popovers, menus.
- `--shadow-xl` for full modals, command palettes.
- `--shadow-inset` adds a top-light/bottom-shade to give buttons subtle paper relief.

### Motion

**Quiet, fast, no bouncing.** `--ease-standard` for most things, `--ease-out` for entrances. Default duration `--dur-base` (200ms). Hover transitions `--dur-fast` (120ms). **No spring physics, no scale-up on hover.** Cards move at most 1px on hover. Buttons darken; they don't grow.

### Hover & Press States

- **Buttons (primary navy):** hover → `--navy-900`; press → `--navy-950` + 1px translate-down. No scale.
- **Buttons (secondary):** hover → background `--cream-200`; press → `--cream-300`.
- **Buttons (ghost):** hover → background `rgba(14,31,51,0.05)`.
- **Links:** hover → darker shade + thicker underline (`text-decoration-thickness: 2px`).
- **Cards (interactive):** hover → border darkens to `--border-2`, shadow steps from `sm` → `md`.
- **List rows:** hover → `--cream-50` background.

### Transparency & Blur

Used **rarely**. Acceptable: sticky marketing header (`backdrop-filter: blur(12px)` over `rgba(245,241,232,0.85)`); modal scrim (`rgba(14,31,51,0.55)`). Otherwise prefer solid surfaces. The brand reads as **printed**, not liquid.

### Focus States

Every focusable element gets a 3px navy halo (`--ring-focus`) at 25% opacity, offset 2px. Never remove focus rings.

---

## Iconography

- **Lucide** — primary icon system, loaded from CDN. Stroke 1.75px. Modern, restrained, line-based — matches the engineering-but-classical brand. 16px (inline), 20px (UI default), 24px (section headers).
- **Custom marks for Bitcoin** — the Bitcoin "B" glyph is part of the logo and is also used as a standalone unit symbol. Currency in UI uses `₿` (U+20BF) inline.
- **The Keysat logo mark** at `assets/keysat-mark.svg` — never recolored, always navy or, on dark surfaces, cream.
- **No emoji** in product UI. The draft site's emoji icons (⚡🔐📡🎫🏷️🛠️) are replaced 1:1 by Lucide: `zap`, `key-round`, `wifi-off`, `ticket`, `tag`, `wrench`.
- **No PNG icons** in the UI. Only the rasterized logo thumbnail is PNG; everything else is SVG.

---

## Open Questions / Caveats

- The display typeface is a **Google Fonts substitution** (Archivo). If Keysat has a licensed display face, please supply it.
- Only a 1024×1024 PNG logo was provided. **No vector logo, horizontal lockup, monochrome version, or favicon were available.** I generated a clean SVG mark + wordmark; please review against the source.
- The draft HTML site was used for **content + product scope only** — its dark-mode + amber visual style was explicitly replaced.
