tokens

Design tokens

Give repeated visual decisions a shared home. Inspect existing tokens and consumers before defining another palette or replacing the system.

Work

• Establish audience, platform, brand constraints, and reading versus task density. Choose roles before values.
• Define only needed surface/text, action/foreground, border, focus, and status pairs; add type, spacing, radius, and motion scales where repetition warrants them.
• Reuse the current format and naming. OKLCH is useful for perceptual adjustment but does not guarantee contrast. Literal values are appropriate at the source; a one-off measured dimension does not automatically deserve a token.
• Support the themes the product actually needs. For each supported theme, verify actual foreground/background pairs and interactive states; do not mechanically invert colors.
• Show how one real primitive and one composed screen consume the roles. Use those examples to discover missing roles before growing the system.
• For existing work, explain additions and migrations, including consumers that may change visibly.

Deliver

Give the source path, compact role/value table or implementation, usage example, and contrast/visual checks. For an authorized implementation task, update the source and its consumers.

## Token foundation

Source: Roles: surface/text, action/foreground, border, focus, status pairs Type / spacing / radius: scales added where repeated Themes: pairs verified per theme Usage: one primitive + one screen consume the roles Checks: contrast, focus, enlargement, theme transitions

Example: pair action background with action text; pair warning surface with warning text. A name such as “primary” does not prove either pairing is readable.

Check text enlargement, focus visibility, and theme transitions in context. Avoid compulsory dark mode, fixed type ratios, or a token for every pixel. Use `$system` for ongoing drift and migration review; `$craft` for broader visible design work.

## Worked example

```markdown
## Token foundation

**Source:** `src/styles/globals.css` (detected `@theme inline` block)
**Detected:** body `--font-sans` (current stack); mono `--font-mono` (current); spacing scale in use; radius in use; existing surface/action/border/focus roles
**Preserve:** keep detected type, spacing, radius, and theme pairs unchanged; reuse format and naming
**Change (justified):** add only the missing status pair the task requires; no new type or radius scales
**Usage:** Button consumes the detected action pair; dashboard card consumes the detected surface pair with the existing radius
**Checks:** measured contrast per pair in shipped themes; focus visible; text enlargement without clipping

Gotchas

• A role named primary says nothing about readability; measure the actual text color on the actual surface in every shipped theme.
• Even steps in OKLCH lightness look consistent but do not guarantee contrast.
• Inverted light values make a dark theme with glaring surfaces and muddy status colors; choose dark values per role.
• A token for every measured value becomes a lookup table nobody uses; one-offs stay literal.
• An undocumented token system gets reinvented by the next agent; publish the exact token and class names agents may use.

Boundaries

• Do not use to audit an existing token system for drift or migrate its consumers; use $system instead. Adding a missing role to an existing system stays here.
• Do not use when the question is layout shells; use $layout instead.