Why we built this
This started as an internal cleanup. Six weeks ago we sat down to ship
a marketing-site overhaul on an 8-week deadline and realised the first
week would have to be an audit. The site had grown six separate token
files over two years — each one written by someone solving a real
problem, none of them coordinated. The numbers were ugly: 1,016 unique
CSS variables, ~2,400 ad-hoc border-radius values, a
three-way collision on --radius-md that made the resolved
value depend on which file loaded last.
We could have papered over it. Most teams do. The reason we did not is that we run with a tiny crew (one operator, an AI agent rotation) and could not afford to ship a 7-week feature push on a foundation that would punish us for every component we wrote. So Week 1 became a token audit. Week 2 became seven primitives. Weeks 3 and 4 became a site-wide codemod (499 files, 8,814 replacements). Week 5 was motion. You are reading the result.
The decision to publish this as a public reference site, rather than a private Storybook, came late and was not obvious. The argument that won: the audit numbers, the principle essays, and the changelog are useful to anyone running a similar migration — and the discipline of writing them for a public audience forces us to make stronger arguments. The private version would have been a lazier version. So this is the public version, version-tagged, link-able, and citable. If it helps someone else avoid a 99999-vs-100001 z-index arms race, the writing time was worth it.
What is next
The remaining two weeks of the sprint:
- Week 7 Visual regression suite
Playwright-driven screenshot diff for every /design page + a representative cross-section of reading-surface and cockpit pages. Catches token drift before it ships.
- Week 7 Accessibility audit
axe-core sweep of every primitive + manual keyboard pass through the cockpit dashboards. Documented results in /design/a11y. Reduced-motion compliance verified.
- Week 8 [email protected] tag
Lock the v1 surface area: tokens, primitives, and contracts that the next 12 months commit to. Anything not in v1 is explicitly experimental.
- Week 8 Launch post + reference site public
Long-form write-up of the audit findings, the migration story, and the design arguments. Publishes the same day /design/* goes live on the public domain.
Inspiration
Nothing here is novel; almost everything is borrowed. Below is an explicit accounting of which existing systems shaped which parts of this one, because credit-where-due is part of how a vocabulary grows.
-
Stripe Press
The reading-surface aesthetic: dark, generous whitespace, type-first, every visual decision earning its presence on the page. The essays under /design/principles owe their structure directly to how Stripe Press lets a single argument breathe.
-
Linear
The cockpit aesthetic on the operational side. Density tokens (--ds-density-pad-multiplier, compact-mode control heights) are a direct translation of the way Linear treats list density as a first-class control. The data-density attribute pattern is theirs.
-
Vercel (vercel.com/design)
The /design site as a public artefact, not an internal Notion page. Reading their public design site convinced us the audit doc and the changelog belonged on the same domain as the marketing site, not behind a login.
-
Radix UI
The headless-primitive model + accessibility-first approach. Our Dialog, Tooltip, Tabs, Select primitives all ship with focus-trap, ESC-to-dismiss, and roving tabindex defaults because Radix made those table stakes.
-
Material Design (Google)
The 4pt spacing grid + the elevation-as-shadow-scale pattern. Our spacing scale is a 4pt grid because Material proved it composes well across every layout density. Our shadow scale follows the same elevation-ladder idea, but without the brand tint.