# Design Token Foundation Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Give chopin a real design-token layer — surface, shadow, radius, type and motion scales — so hierarchy comes from a system rather than from values invented at each call site. **Architecture:** All tokens live in one `@theme static` block in `apps/web/src/theme.css`. Nothing else declares a scale. The editor package reads tokens through `var()` and never redefines them. Where a Tailwind theme namespace exists (`--color-*`, `--radius-*`, `--text-*`, `--shadow-*`, `--ease-*`), tokens are declared under that namespace so the matching utility classes are regenerated with our values and existing markup upgrades without being touched. **Tech Stack:** Tailwind CSS v4.3 (`@theme static`), Vite 7, React 19, Bun test. ## Global Constraints - The palette is **light only**. Dark mode is explicitly out of scope; do not add `prefers-color-scheme` blocks or a second token set. - Every token is declared in `apps/web/src/theme.css` inside the single `@theme static { }` block. `packages/editor/src/styles.css` may **read** tokens but must never declare a scale. - `@theme` must keep the `static` keyword. `scripts/check-tokens.ts` fails the build otherwise — Tailwind prunes theme variables that only hand-written CSS reads. - Every `var(--token)` without a fallback must resolve. `bun scripts/check-tokens.ts` enforces this and runs in `bun run ci`. - Sizes are declared in `rem`. Pixel equivalents belong in comments, not values. - Run `bun run fix` before every commit — `dprint check` runs in CI and rejects unformatted files. - Do not touch press states (`active:`), focus-ring unification, or enter/exit animations. Those are the next slice. - Existing test baseline is **525 passing, 0 failing**. It must stay green. --- ## File Structure | File | Responsibility | Change | | ----------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------- | | `apps/web/src/theme.css` | The single source of every scale | Modify — add surface, shadow, radius, type, motion tokens | | `apps/web/src/tokens.test.ts` | Asserts the scales hold their invariants (monotonic, perceptible, no arbitrary sizes left) | Create | | `apps/web/src/workspace.tsx` | Three-pane shell; applies the rail surface | Modify | | `apps/web/src/app.tsx` | Header; applies the rail surface | Modify | | `apps/web/src/chat/chat.tsx` | Chat rail; type + radius migration | Modify | | `apps/web/src/chat/transcript.tsx` | Tool cards; type + radius migration | Modify | | `packages/editor/src/styles.css` | Reads tokens for document type, motion, radius | Modify | | `packages/editor/src/decisions.tsx` | Decisions rail surface | Modify | | `scripts/check-tokens.ts` | Drops `--radius-` from the external allowlist once we own the scale | Modify | `apps/web/src/theme.test.ts` already tests highlight perceptibility by parsing CSS. `tokens.test.ts` is a sibling in the same idiom, kept separate because it tests scale _structure_ rather than colour perception. --- ## Task 1: Surface token and the rails Gives the layout a depth axis: the plan document stays pure white, the chrome around it recedes to a faint tint. **Files:** - Modify: `apps/web/src/theme.css` (`@theme static` block) - Create: `apps/web/src/tokens.test.ts` - Modify: `apps/web/src/workspace.tsx:85` (chat `