Keysat
843ff0e5d7
Glue files not covered by subproject repos: top-level docs, logo, keysat-design-system, and crosscheck tests. Subproject folders are gitignored (each has its own Gitea remote).
173 lines
11 KiB
Markdown
173 lines
11 KiB
Markdown
# 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.
|