design-systemlisted

# Design system A design system is not a document, it is a **constraint that holds at build time**. Tokens nobody is forced to use are a colour list. ## Three layers, in this order 1. **Primitive** — the raw values. `blue-600 #2563EB`, `space-4 16`, `dur-fast 150ms`. No screen ever references a primitive directly. 2. **Semantic** — what it means. `text/primary`, `surface/elevated`, `semantic/error`, `motion/enter`. Screens reference these and only these. 3. **Component** — what a component uses. `button/primary/background` → `semantic/action`. Skipping layer 2 is the failure: a dark mode, a rebrand or a contrast fix then edits every screen. ## The rules - **A hardcoded colour, spacing, radius, duration or font size in a screen is a defect**, not a style preference. Name it or use the token that already exists. - **Every semantic token names its dark-mode value at the same time.** A token added light-only is a dark-mode bug already merged. - **A new component needs a reason the existing ones cannot compose it.** Write the reason in `docs/14-components.md`. "It looked different in the mock" is not one. - **Every component declares its states** — default, pressed, disabled, loading, error, empty where applicable — and its minimum touch target (44pt iOS / 48dp Android). - **Contrast is checked when the token is defined**, not when accessibility is audited. Text pairs meet 4.5:1, large text and non-text 3:1. A token failing contrast never ships and is never