Keysat
532229d488
Establish keysat's durable, vendor-neutral design contract (the standards /design backfill, document-as-is): - design/DESIGN.md — nine-section brand brief distilled from the prior Claude Design system (navy-on-cream-paper identity, sovereignty-first voice, component + motion rules, do's/don'ts). Manrope is canonical display (the README's "Archivo" was a stale placeholder). - design/tokens.tokens.json — W3C DTCG tokens from colors_and_type.css. - design/brand/ — canonical palette.css + logo/mark assets. - design/_imports/2026-06-16-claude-design-system/ — the original system, relocated as dated provenance (nothing imported it). - AGENTS.md — add the Design line (read the contract before UI work); repoint the layout entry. - ROADMAP.md — design-checker cleanup backlog (gold-as-fill + pill-radius blockers, the inline-token-copy consolidation, token gaps).
143 lines
8.0 KiB
Markdown
143 lines
8.0 KiB
Markdown
---
|
||
project: keysat
|
||
tagline: Software licensing for Bitcoin creators
|
||
source: design/_imports/2026-06-16-claude-design-system/ (Claude Design output, May 2025)
|
||
tokens: design/tokens.tokens.json
|
||
canonical_css: design/brand/palette.css
|
||
last_distilled: 2026-06-16
|
||
---
|
||
|
||
# Keysat — design contract
|
||
|
||
> The durable, vendor-neutral brand brief. Any agent building or changing a user-facing
|
||
> surface (the marketing landing, the docs site, the creator admin SPA) reads this and
|
||
> `design/tokens.tokens.json` first and conforms to them. Token *values* live in the tokens
|
||
> file; this document is the *intent* and the rules. Distilled from a prior Claude Design
|
||
> system (now in `design/_imports/`).
|
||
|
||
## 1. Visual theme
|
||
|
||
Navy ink on cream paper, with a gold accent that whispers. The reference objects are a
|
||
**certificate of authenticity, a vault deed, a hand-numbered print** — classical trust
|
||
signaling crossed with modern indie-software practicality. Restrained, archival, precise;
|
||
**modern in interaction, classical in composition.** The identity is anchored by the logo: a
|
||
deep-navy key crossing a Bitcoin "B" bow, on cream paper with a gold inner border. The brand
|
||
reads as **printed, not liquid** — solid surfaces over glass and gradients.
|
||
|
||
## 2. Color palette
|
||
|
||
Values in `tokens.tokens.json`. Roles:
|
||
|
||
- **Navy is the primary brand color.** `navy-800` (`#1E3A5F`) is the wordmark color and
|
||
dominant ink — primary buttons, headings, key chrome. Full scale `navy-950 → navy-50`.
|
||
- **Cream is the page background.** `cream-100` (`#F5F1E8`) default; `cream-50` (`#FBF9F2`)
|
||
for elevated paper. **Pure white (`#FFFFFF`)** is reserved for forms, tables, and code
|
||
blocks where contrast matters.
|
||
- **Gold (`gold-500`, `#BFA068`) is the accent, used sparingly** — eyebrow labels, dividers,
|
||
the inner stroke of premium cards, a verified-badge highlight. **Never a primary button
|
||
color.**
|
||
- **Ink scale (`ink-900 → ink-300`)** handles body text, secondary copy, disabled states.
|
||
- **Semantic:** success `#2D7A5F`, warning `#B8861F`, danger `#B23A3A`, info = `navy-700`,
|
||
each with a tinted `-bg`.
|
||
- Borders are **alpha navy**, not solid lines: `border-1` 12%, `border-2` 20%, `border-3` 35%.
|
||
|
||
## 3. Typography
|
||
|
||
- **Display — Manrope** (`font-display`): geometric sans, mirrors the wordmark. h1–h4, large
|
||
numerals, the wordmark. Weights 400–700 (500 for h1/h2, 600 for h3/h4). *Note: the original
|
||
design-system README named "Archivo" as a placeholder substitution, but the shipped CSS and
|
||
every live surface use Manrope — Manrope is canonical. If a licensed display face is ever
|
||
supplied, swap `font.display` in the tokens and remove the Google Fonts import.*
|
||
- **Body — Inter** (`font-body`): humanist sans for prose, UI labels, form fields. Stylistic
|
||
sets `ss01` + `cv11`.
|
||
- **Mono — JetBrains Mono** (`font-mono`): license keys, code samples, API responses, tx IDs.
|
||
- **Type scale** is the `fs-*` tokens (`display-xl` clamp 56–88px down to `meta` 12px).
|
||
Headings track tight (`-0.02em`); eyebrows track wide (`0.18em`), uppercase.
|
||
- **Casing:** sentence case for buttons/menus/headings ("Create a license"); ALL CAPS + wide
|
||
tracking only for eyebrow labels above sections, sparingly. Proper nouns capitalized
|
||
(Keysat, Start9, StartOS, BTCPay, Bitcoin, Lightning, Ed25519).
|
||
- **Identifiers:** license keys monospace, hyphen-grouped (`KS-9F2A-7C41-XK22-6D8E`); keys/
|
||
hashes ellipsized middle (`mz7q8…h3k2p`); amounts default to **sats** under 0.01 BTC.
|
||
|
||
## 4. Component styling
|
||
|
||
- **Buttons** — radius `r-md` (8px). Primary: `navy-800` bg, `cream-50` text; hover `navy-900`,
|
||
press `navy-950` + 1px translate-down (no scale). Secondary: `cream-50` bg, alpha-navy
|
||
border; hover `cream-200`. Ghost: transparent; hover `rgba(14,31,51,0.05)`. **Gold is a
|
||
text/border treatment only, never a primary button fill.** Danger: red text + faint red
|
||
border.
|
||
- **Cards** — radius `r-lg` (12px), on cream with a hairline `border-1` and `shadow-sm`.
|
||
Premium/featured cards get a **1px gold inner stroke** (`gold-500`) + `shadow-md`.
|
||
- **Badges** — pill (`r-pill`), tinted semantic bg + matching text; gold/neutral = transparent
|
||
with a gold border.
|
||
- **Forms** — white bg, alpha-navy border, radius ~7px; focus = navy border + `ring-focus`
|
||
halo. Monospace variant for keys.
|
||
- **Code blocks** — `navy-950` bg, `cream-50` text, `r-lg`, JetBrains Mono; gold/cream syntax.
|
||
- **Icons — Lucide**, stroke 1.75px, 16/20/24px. **No emoji in product UI. No PNG icons** (the
|
||
logo mark is SVG; only the source thumbnail is PNG). The logo mark is never recolored —
|
||
navy, or cream on dark surfaces.
|
||
|
||
## 5. Layout
|
||
|
||
- **4px base grid**, spacing tokens `sp-1` (4px) → `sp-12` (128px). Use the scale; don't mint
|
||
magic numbers.
|
||
- 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 are cream with a subtle grain** (the `paper-texture` utility — two radial-dot
|
||
grids at ~2.5% opacity), never flat color. Section bands alternate cream → cream-200 →
|
||
cream-50 → navy-950 (dark CTAs/footers).
|
||
|
||
## 6. Depth / elevation
|
||
|
||
A **paper-shadow** system, not a glassy one. `shadow-xs`/`sm` for resting cards; `shadow-md`
|
||
for elevated/premium cards; `shadow-lg` for popovers/menus; `shadow-xl` for modals/command
|
||
palettes. `shadow-inset` gives buttons subtle paper relief. Elevation comes from **shadow,
|
||
not heavy borders**. Transparency/blur is rare — acceptable only for the sticky marketing
|
||
header (`blur(12px)` over `rgba(245,241,232,0.85)`) and the modal scrim (`rgba(14,31,51,0.55)`).
|
||
|
||
## 7. Do's and don'ts
|
||
|
||
**Do**
|
||
- Lead copy with *what the creator owns* — the signing key, the customer list, the payment
|
||
rails. Sovereignty-first is the brand's center of gravity.
|
||
- Keep gold rare and accenting; keep motion quiet (200ms standard, 120ms hover).
|
||
- Use solid surfaces, restrained radii, hairline alpha borders, the paper grain.
|
||
- Link a one-sentence definition the first time a term appears (Ed25519, BTCPay webhook,
|
||
`.s9pk`).
|
||
|
||
**Don't**
|
||
- **No hype words:** revolutionary, seamless, unlock, supercharge, leverage, ecosystem,
|
||
journey, paradigm, game-changing.
|
||
- **No emoji** in product UI; **no PNG icons**; **no Bitcoin orange** in the UI (navy/cream
|
||
stands alone); no blue/purple gradients, no glassmorphism.
|
||
- **Gold is never a primary button fill.** Radii never exceed ~18px (`r-xl`) for surfaces —
|
||
no 24px+ rounding (reads as a consumer fintech app, which Keysat is not).
|
||
- No spring physics, no scale-up on hover (cards move at most 1px; buttons darken, not grow).
|
||
- Never remove focus rings.
|
||
|
||
## 8. Responsive behavior
|
||
|
||
Breakpoints in use: **980px** (grids collapse), **720px** (sidebar → slide-in drawer),
|
||
**640px** (phone: tighter chrome, single column). Container padding steps 32px desktop → 20px
|
||
tablet → 14px phone. Marketing is full-width hero + stacked sections; docs is a 3-column
|
||
(sidebar | prose | TOC) collapsing to single column at 980px; admin is a 240px sticky sidebar
|
||
+ main, sidebar drawering at 720px.
|
||
|
||
## 9. Agent prompt guide
|
||
|
||
When building or changing a Keysat UI:
|
||
|
||
- **Pull every color, size, space, radius, and shadow from `design/tokens.tokens.json`** (or a
|
||
CSS custom property derived from it — see `design/brand/palette.css`). Do not hardcode hex or
|
||
px values that bypass the scale.
|
||
- Match the **existing surface** you're editing (landing / docs / admin) — they share the token
|
||
set; keep them consistent rather than introducing a new look.
|
||
- Default to **navy primary buttons, cream pages, gold-as-accent-only**, paper shadows, Lucide
|
||
icons, sentence-case labels, no emoji.
|
||
- If a needed value genuinely isn't in the tokens, **add it to the tokens file** (and ideally
|
||
`palette.css`) rather than inlining a one-off — keep the contract the single source of truth.
|
||
- Known debt (see ROADMAP): the three surfaces currently inline their own copy of the
|
||
variables. Prefer importing `design/brand/palette.css`; when you touch a surface, move it
|
||
toward that shared source rather than perpetuating a private copy.
|