Philosophy
Why this system exists, what it optimises for, and what it deliberately refuses to do.
One source of truth
Tokens, not constants.
Every visual value — colour, spacing, type, motion, radius, shadow — lives in src/app/globals.css. Components read variables via Tailwind v4's @theme block. Figma stays in sync via Tokens Studio. If a number isn't in the token file, it doesn't exist.
Variant-locked components
TypeScript is the door, the wall and the lock.
Components expose a tightly typed set of variants via class-variance-authority. There are no arbitrary color or size props. Designers and engineers read from the same vocabulary.
Inside loading
Never show a blank flash.
Skeletons match the shape they replace. Children stagger in on a 60ms cadence. Mutations apply optimistically and revert with a toast on failure. Page transitions add only opacity + a 6px shift — they feel like part of the design, not an interruption.
Accessible by default
WCAG 2.1 AA on every text/background combo.
Interactive components are Radix-based. Focus rings are visible in both themes. Animations honour prefers-reduced-motion. Screen readers get live-region announcements for async state.
What we refuse
The constraints that protect the system.
- · No hex codes outside the token file.
- · No spacing values outside the 8px scale.
- · No any types.
- · No CSS animations longer than 500ms outside page transitions.
- · No component without a variants table and live preview on this site.