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

Token foundation

Source: src/styles/globals.css (@theme inline) 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

• Verify actual foreground/background pairs in every supported theme; a token name does not prove contrast.
• Treat OKLCH as a perceptual adjustment tool only; it does not prove contrast — measure each pair.
• Reuse the current format and naming; inspect consumers before adding a role.
• Verify each theme pair directly; do not mechanically invert light values for dark.
• Mint a token only for genuine repetition; a one-off measured dimension stays a literal.
• Publish the exact token and class names agents may use; an undocumented system gets reinvented from description alone.

Boundaries

• Do not use when a token system already exists — use $system to audit drift instead of replacing it.
• Do not use when the question is layout shells — use $layout instead.