Design System · v0.1
Blueprint.
Every atom, molecule, and organism the site is built from.
Editing a token cascades through every component below — and through every page that uses them.
01 — Foundations
Foundations
The raw materials. Tokens defined once in tokens.css, consumed everywhere.
Contrast
Live WCAG contrast ratios on the key text-on-surface pairs. AA needs 4.5:1 for body text, 3:1 for large. AAA needs 7:1 / 4.5:1. Changes in Theme Studio update these in real time.
Aa
Body text on background
Aa
Body prose
Aa
Labels, secondary
Aa
Button text on accent
Aa
Accent text on bg
Aa
Critical badge text
Colour
Typography
Spacing
--space-1 --space-2 --space-3 --space-4 --space-5 --space-6 --space-8 --space-10 --space-12 --space-16 --space-20 --space-24 --space-32 Radii
--radius-sm --radius-base --radius-md --radius-lg --radius-xl --radius-pill Shadows
--shadow-sm --shadow-base --shadow-lg --shadow-glow Motion
Fast
--duration-fast 120ms — micro feedback
Base
--duration-base 180ms — hover, focus
Slow
--duration-slow 280ms — section transitions
Slower
--duration-slower 500ms — page-level changes
02 — Atoms
Atoms
Smallest indivisible UI units. Each is its own component in src/components/atoms/.
Button
Variants × sizes. Use variant="primary" for the most important CTA on a page. secondary for adjacent actions. ghost for inline links that need button affordance.
atoms/Button
Button
Change variant, size, label, and disabled state. The code panel updates as you do.
Controls
Code
All interactive states (default / hover / focus / active / disabled):
default:hover:focus:active[disabled]Anatomy:
All combinations at a glance:
primary · base secondary · base ghost · base primary · sm primary · lg primary · disabled Badge
Status / category / kicker chip. uppercase by default. Use variant="critical" for binding constraints, warn for constrained, subtle for tickers.
atoms/Badge
Badge
Pick a variant for the semantic role (status / category / kicker), change the size, change the label.
Controls
Code
Every variant:
accentcriticalwarnsuccessoutlinesubtledefault · tickeraccent · smKicker
Small uppercase label above a heading. Sets section context.
atoms/Kicker
Kicker
Switch tone between muted and accent. Edit the label.
Section context
Controls
Code
Check
Status glyph for feature lists. Default ✓. Use symbol="★" for emphasis lines.
atoms/Check
Check
Pick a tone, optionally swap the glyph symbol (✓ → ★, → •, etc.).
Controls
Code
Heading
Semantic level (h1-h6) decoupled from visual size (display | h1 | h2 | h3 | h4). Defaults to display font (Fraunces).
Display heading
H1 heading
H2 heading
H3 heading
H4 heading italic
Iconography
Stroke-based 24×24 SVGs. 1.5px stroke at base size to read confidently next to body type. currentColor on every stroke so they inherit ink colour and theme correctly. Click any icon to copy its SVG markup.
03 — Molecules
Molecules
Groups of atoms working together. Building next: PriceTag, ToggleGroup, FeatureList, FAQItem, LayerCardSummary, StatPill.
Molecules ship in the next pass. The Tracker's existing components (toggle, price block, feature list, FAQ item) will be extracted into reusable molecules here.
04 — Organisms
Organisms
Composed sections built from molecules. Building next: Hero, TierGrid, LayerGrid, MigrationFeed, FAQList, FounderNote, Header, Footer.
Organisms ship after molecules. Each will be a single Astro component — import it once, use it on any page.
05 — Templates
Templates
Page-level scaffolds. Building next: TrackerTemplate, BlogTemplate, IndexTemplate.
Once atoms / molecules / organisms exist, pages become very thin — just data + a template.
Reference
What this is built on
The design knowledge this blueprint stands on. Pulled from people who have already solved it.
Atomic Design
Brad Frost — Atomic Design (2016)
The five-tier taxonomy (atoms → molecules → organisms → templates → pages). The blueprint's structural backbone.
Component playgrounds
Storybook · Histoire · Ladle
Args panel, live controls, code snippet generation. We've built the same pattern in vanilla Astro to avoid framework lock-in.
Token systems
Style Dictionary · Tokens Studio · Open Props
Tokens-as-source-of-truth, with mathematical scale derivation. Type and spacing here scale via ratio formulas, not hand-typed values.
Theme builders
Material Theme Builder · Carbon Theme Builder · Adobe Spectrum
Live preset palettes, accessibility-checked colour pairs, export pipeline. The Theme Studio's preset bar comes from here.
Accessibility
WCAG 2.2 · Radix UI
Live contrast ratio checking with AA/AAA badges. Focus-visible rings on every interactive element. Keyboard navigation by default.
Visual register
Vercel Geist · Linear · Stripe Press · Stratechery
Editorial restraint. Confident typography. Sharp focus states. No decoration that doesn't earn its place.
Component libraries
shadcn/ui · Radix Themes · Geist UI
Copy-paste primitives over framework lock-in. Astro components live in the repo, owned by us — not in a node_modules package we can't change.
Pattern documentation
Shopify Polaris · GitHub Primer · Atlassian Design
Do's & don'ts, anatomy diagrams, behavioural notes per component. Pattern shipping next.
06 — Live editor
Live token editor
Sliders and pickers for primary tokens — preview changes across all the components above in real time. Generates the exact diff to apply to tokens.css when you're ready to commit.
Live editor ships next. For now: change --c-accent in src/styles/tokens.css and reload — every component on this page (and every page on the site) updates from that single edit.