Design system · v0.1
The system behind the wire.
One vocabulary for the website, the application, and the docs site. Tokens are the contract. Components are the application of the contract. Everything else is taste — but documented taste, so the next person who joins can be opinionated without breaking things.
How to read this
This manual exists for two jobs. One: bring the application UI in line with the website — same tokens, same density rhythm, same components. Two: theme the Astro Starlight docs site so it reads like part of the same product, not a third-party add-on.
If you're a contributor: read Principles, then Color, Typography, Spacing. That's the foundation. Components are reference material — read them when you need them.
If you're integrating: jump straight to the integration page for your stack (Vuetify or Starlight). Each one ends with a copy-paste theme file.
The system at a glance
Principles
What we optimise for and what we won't compromise. Density, honesty, no marketing chrome in product surfaces.
Color
Surfaces, foreground, brand, semantic, protocol-coded. Every hex justified.
Typography
Three families, twelve sizes, five weights. Display vs. body vs. mono — when each one shows up.
Spacing & layout
4px scale. The website breathes; the app should too. Density rules per surface type.
Motion
Four durations, four easings. Where motion clarifies and where it patronises.
Iconography
Phosphor (regular weight). 18 / 20 / 24 px sizes. Mappings for protocols and verbs.
Accessibility
Contrast targets, focus rings, keyboard, motion-reduce. Non-negotiable list.
Buttons
Four variants, three sizes, destructive flavour. One primary per region.
Inputs & forms
Mono where structural, body where descriptive. Key-value rows, states, density.
Badges & tags
Protocol tags vs status badges. Pulse dot for live anything.
Empty · Loading · Error · Toast
The unsexy states. Most products half-ass these. We don't.
Code surfaces
Half the UI is code — payloads, hex dumps, diffs. First-class surface.
Tables
The proxy log, the history list. Density first, then everything else.
Tabs
Section tabs (Headers/Body/Auth) and surface tabs (open documents).
Vuetify theme
Theme config, CSS overrides, density rules. Vuetify covers ~70%; this is the rest.
Starlight theme
Token shim, sidebar styling, Expressive Code overrides. No brand seam between site and docs.
Current app · diagnosis
Annotated screenshots of the MVP build. Where it diverges and what to fix first.
Versioning
Versioned in lock-step with tokens.json. Token changes are major if a value moves more than one step on a scale; minor if a value adjusts; patch if only descriptions change. Component additions are minor. Breaking component changes are major. Current: 0.1.0 — pre-launch, expect adjustment.