---
name: design-tokens-generator
description: Generates a full set of design tokens (color scale, type scale, spacing, radius, motion, elevation) and validates every foreground/background pair against WCAG AA. Emits CSS custom properties + a Tailwind config. Use when the user says "design tokens", "color scale", "type scale", "accessibility contrast", or is starting a new theme.
---

# Design Tokens Generator

Produce a coherent, accessible token set. Never eyeball ratios - measure.

## Output shape

- **`tokens.css`** - CSS custom properties on `:root` and `[data-theme="dark"]`.
- **`tailwind.config.ts`** - extends `theme.colors`, `theme.spacing`, `theme.fontSize`, `theme.borderRadius`, `theme.boxShadow` from the same tokens.
- **`tokens.json`** - machine-readable source (W3C DTCG format) so the same tokens can feed Figma via a plugin.

## Method

1. **Base scale** - 12-step color ramp per family (0 lightest → 12 darkest), interpolated in OKLCH.
2. **Semantic aliases** - `bg`, `bg-elev`, `fg`, `fg-dim`, `fg-faint`, `line`, `line-2`, `accent`, `success`, `warning`, `danger`, `card-bg`, `card-fg`.
3. **Contrast validation** - for every semantic pair (`fg` on `bg`, `fg` on `card-bg`, `accent` on `bg`, etc.), compute WCAG 2.2 relative luminance ratio. Fail the build if any pair is < 4.5:1 for normal text or < 3:1 for large text / UI elements.
4. **Type scale** - fluid `clamp(min, ideal, max)` where min = mobile size, max = desktop size, ideal = `calc(min + (max - min) * ((100vw - 400px) / (1440 - 400)))`. Steps: xs (12), sm (14), base (16), lg (18), xl (20), 2xl (24), 3xl (30), 4xl (36), 5xl (48), 6xl (60), 7xl (72).
5. **Spacing** - 4/8/12/16/20/24/32/40/48/64/80/96 (px), aliased as `1/2/3/4/5/6/8/10/12/16/20/24`.
6. **Motion** - durations 100/150/250/400/600 ms, easings `standard: cubic-bezier(0.16, 1, 0.3, 1)`, `entrance: cubic-bezier(0, 0, 0.2, 1)`, `exit: cubic-bezier(0.4, 0, 1, 1)`.

## Rules

- Never define a color directly in a component. Always via semantic alias.
- Dark ≠ inverted light. Rebuild the semantic layer per theme, keep the same **names**.
- Log a table of every failed contrast pair before returning tokens.

## Kickoff prompts

- "Generate tokens for a warm minimalist brand with pure black cards."
- "Audit these tokens: report contrast failures and suggest OKLCH tweaks."