design-tokens

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: design-tokens
description: Generate a design tokens file (CSS variables or Tailwind config) based on a chosen aesthetic philosophy, with light and dark mode palettes, spacing scale, type ramp, and component-level tokens. Use when starting a new project, establishing a visual system, setting up tokens, or mentions "tokens" or "design system".
---

This skill generates the foundational design tokens for a project. Run this after the design brief and before building any components. Every component built after this references these tokens instead of hardcoding values.

## Example prompts

- "Set up design tokens for this project"
- "Generate a token system based on Dieter Rams"
- "I need a spacing scale and color palette before I start building"
- "Create tokens that match our brief"

## Process

1. **Check what already exists.** Before generating anything, scan the codebase for:
   - CSS variable definitions (`:root`, `[data-theme]`, custom property files)
   - Tailwind config (`tailwind.config.js`, `tailwind.config.ts`) and any theme extensions
   - Theme provider files (Material UI `createTheme`, Chakra `extendTheme`, shadcn `globals.css`)
   - Design token JSON files (Style Dictionary format, Figma token exports)
   - Any `tokens.css`, `variables.css`, `theme.css`, or similarly named files
   - `package.json` for UI framework dependencies (tailwindcss, @mui/material, @chakra-ui/react, etc.)

   If tokens already exist, **extend them** rather than replacing. Identify gaps (missing dark mode, incomplete spacing scale, no motion tokens) and fill those.

2. **Read the brief.** Look for a design brief at `.design/*/DESIGN_BRIEF.md`. If multiple subfolders exist, use the most recently modified one, or ask the user which feature they are working on. If a philosophy is named, use the parameters from `/frontend-design` to derive token values. If no brief exists, ask the user what direction they want.

3. **Generate tokens** in the format that matches the project's tech stack:
   - Tailwind project → extend `tailwind.config.js` and write to `globals.css`
   - CSS/HTML project → write to a `tokens.css` file
   - CSS-in-JS project → write to a `theme.ts` or `theme.js` file
   - If unclear, default to CSS custom properties (most portable)

4. **Always generate both light and dark mode palettes.** Use `[data-theme="dark"]` or `prefers-color-scheme` media query. Both palettes should feel intentional for the chosen philosophy, not just inverted values.

## Token Categories

### Color

```css
/* Semantic color tokens, not raw values */
--color-bg-primary:          /* Main background */
--color-bg-secondary:        /* Secondary/card background */
--color-bg-tertiary:         /* Subtle background (inputs, wells) */
--color-bg-inverse:          /* Inverted background */

--color-text-primary:        /* Main text */
--color-text-secondary:      /* Subdued text */
--color-text-tertiary:       /* Placeholder, disabled text */
--color-text-inverse:        /* Text on inverse backgrounds */
--color-text-link:           /* Link color */

--color-border-primary:      /* Default borders */
--color-border-secondary:    /* Subtle borders */
--color-border-focus:        /* Focus ring color */

--color-accent-primary:      /* Primary action color */
--color-accent-primary-hover:
--color-accent-primary-active:
--color-accent-secondary:    /* Secondary action color */

--color-status-success:
--color-status-warning:
--color-status-error:
--color-status-info:

--color-surface-overlay:     /* Modal/dropdown backdrop */
```

### Spacing

Generate a consistent scale. The base unit should match the philosophy:
- Tight philosophies (Brutalist, Swiss): 4px base
- Balanced philosophies (Rams, Scandinavian): 4px or 8px base
- Spacious philosophies (Japanese Minimalism, Editorial): 8px base with larger multipliers

```css
--space-0:   0;
--space-1:   /* base * 0.25 */
--space-2:   /* base * 0.5 */
--space-3:   /* base * 0.75 */
--space-4:   /* base * 1 */
--spa