Status: Phase 1 stub. Matures in Phase 5 per §8.1.

Statement

Every visual decision — color, surface, ink, border, radius, shadow, spacing, motion duration, type scale — resolves through a named token defined in tokens.json. Components consume token names, never raw values.

Why

The audit found 12+ surfaces where some components consumed surface tokens (--surf2, --surf3) correctly while others hardcoded the same hex on the same screen, producing per-component theme cascade drift (audit pattern #38). Hardcoded values fork the theme cascade silently — light mode breaks for one component but not its sibling. Tokens make the cascade auditable: a single tokens-file diff explains every visual change.

This is not aesthetic discipline; it is an integrity property. A design system without a single source of truth for visual atoms is decorated CSS, not a system.

How

In Phase 1 (this stub), tokens are stipulated; the file does not yet exist. Phase 2 ships src/components/design-system/tokens.ts + tokens.json + the ESLint hex-ban rule (§5.4 PR #13) that fails CI on any hex literal, raw font-size, or raw transition-duration in src/**/*.{ts,tsx,css} outside the tokens file.

The dark-theme hex ban is stronger than the generic ban (§5.1, audit pattern #38): dark-theme literals (#0a0a0b, #111113, #1a1a1a, etc.) are forbidden outside :root / .dark / .light CSS blocks specifically, even when not technically a "raw hex in TS." That blocks the per-component variant of the bug, not just the obvious one.

Phase 5 deepens this stub with the full token taxonomy, counter-examples (annotated audit screenshots), and PR citations.