Design Token Specification

Context

Design tokens are the contract between design and code. Without them, developers invent values, designers lose control, and the codebase accumulates visual debt. This skill produces the exact CSS and config files developers copy into the project.

Procedure

1. Map every visual identity value to a semantic token name. Color tokens: --color-primary, --color-surface, --color-text-primary. Spacing tokens: --space-1 through --space-16. Typography tokens: --font-display, --text-body, etc.
2. Define the CSS custom properties in a :root block for light mode and a [data-theme="dark"] or .dark block for dark mode.
3. Create the Tailwind theme extension that maps tokens to utility classes. Use theme.extend.colors, theme.extend.spacing, theme.extend.fontSize.
4. Build a token reference table showing: token name, CSS variable, Tailwind class, light value, dark value.
5. Define component-level composite tokens for common patterns: --card-bg, --card-border, --card-shadow, --button-primary-bg, --button-primary-text.
6. Add responsive tokens where needed: --container-max, --grid-columns, breakpoint-specific spacing overrides.

Output Format

/* tokens.css */

:root {
  /* Colors — Brand */
  --color-primary: hsl(221, 83%, 53%);
  --color-primary-hover: hsl(221, 83%, 46%);
  --color-secondary: hsl(262, 83%, 58%);

  /* Colors — Semantic */
  --color-surface: hsl(0, 0%, 100%);
  --color-surface-raised: hsl(0, 0%, 98%);
  --color-text-primary: hsl(0, 0%, 9%);
  --color-text-secondary: hsl(0, 0%, 40%);
  --color-border: hsl(0, 0%, 90%);

  /* Typography */
  --font-display: 'Inter', sans-serif;
  --font-body: 'Inter', sans-serif;
  --text-display-xl: 4.5rem;    /* 72px */
  --text-display: 3rem;          /* 48px */
  --text-heading-lg: 2rem;       /* 32px */
  --text-body: 1rem;             /* 16px */

  /* Spacing (base: 4px) */
  --space-1: 0.25rem;   /* 4px */
  --space-2: 0.5rem;    /* 8px */
  --space-4: 1rem;      /* 16px */
  --space-8: 2rem;      /* 32px */
  --space-16: 4rem;     /* 64px */

  /* Radii */
  --radius-sm: 0.375rem;
  --radius-md: 0.75rem;
  --radius-lg: 1rem;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px hsl(0 0% 0% / 0.05);
  --shadow-md: 0 4px 12px hsl(0 0% 0% / 0.08);
  --shadow-lg: 0 8px 24px hsl(0 0% 0% / 0.12);
}

.dark {
  --color-surface: hsl(225, 25%, 7%);
  --color-surface-raised: hsl(225, 20%, 11%);
  --color-text-primary: hsl(0, 0%, 95%);
  --color-text-secondary: hsl(0, 0%, 60%);
  --color-border: hsl(0, 0%, 18%);
  --color-primary: hsl(221, 90%, 64%);
}

// tailwind.config — theme.extend
{
  colors: {
    primary: 'var(--color-primary)',
    surface: 'var(--color-surface)',
    'surface-raised': 'var(--color-surface-raised)',
  },
  spacing: {
    '1': 'var(--space-1)',
    '2': 'var(--space-2)',
  },
  borderRadius: {
    sm: 'var(--radius-sm)',
    md: 'var(--radius-md)',
  },
}

QA Rubric (scored)

• Naming consistency (0-5): all tokens follow the same semantic naming convention.
• Coverage (0-5): zero raw values in component code — every value is a token reference.
• Dark mode completeness (0-5): every token has a dark-mode counterpart.
• Developer ergonomics (0-5): token names are intuitive without needing documentation.

Examples (good/bad)

• Good: --color-surface-raised for elevated cards. Semantic name tells you what it does regardless of the actual color value. Switching themes only changes the value, not the variable name.
• Bad: --gray-100 for card backgrounds. Breaks in dark mode because "gray-100" is meaningless when the card is actually dark blue.

Variants

• Tailwind-native mode: skip CSS custom properties entirely — define everything directly in tailwind.config.ts using the default color/spacing system.
• Multi-brand mode: token file per brand with a shared structural layer — swap brand tokens at build time via CSS import order.