keysat-root/keysat-design-system/README.md

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 server. Buyers pay in Bitcoin via the creator's own BTCPay Server; 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.