design-tokens

$27

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

-

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.

-

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)

-

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

/* 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

--space-0:   0;

--space-1:   /* base * 0.25 */

--space-2:   /* base * 0.5 */

--space-3:   /* base * 0.75 */

--space-4:   /* base * 1 */

--space-5:   /* base * 1.5 */

--space-6:   /* base * 2 */

--space-7:   /* base * 3 */

--space-8:   /* base * 4 */

--space-9:   /* base * 6 */

--space-10:  /* base * 8 */

--space-11:  /* base * 12 */

--space-12:  /* base * 16 */

Typography

--font-family-display:       /* Headline/display font */

--font-family-body:          /* Body text font */

--font-family-mono:          /* Code/monospace font */

--font-size-xs:

--font-size-sm:

--font-size-base:

--font-size-md:

--font-size-lg:

--font-size-xl:

--font-size-2xl:

--font-size-3xl:

--font-size-4xl:             /* Hero/display size */

--font-weight-normal:

--font-weight-medium:

--font-weight-semibold:

--font-weight-bold:

--line-height-tight:         /* Headings: 1.1-1.3 */

--line-height-normal:        /* Body: 1.4-1.6 */

--line-height-relaxed:       /* Spacious body: 1.6-1.8 */

--letter-spacing-tight:      /* Display type */

--letter-spacing-normal:

--letter-spacing-wide:       /* All-caps, labels */

Layout

--max-width-content:         /* Max reading width (65-75ch equivalent) */

--max-width-wide:            /* Wide content area */

--max-width-page:            /* Full page max width */

--border-radius-sm:

--border-radius-md:

--border-radius-lg:

--border-radius-full:        /* Pill/circle */

--shadow-sm:

--shadow-md:

--shadow-lg:

--shadow-focus:              /* Focus ring shadow */

Motion

--duration-instant:   50ms;

--duration-fast:      150ms;

--duration-normal:    250ms;

--duration-slow:      400ms;

--duration-slower:    600ms;

--easing-default:     cubic-bezier(0.4, 0, 0.2, 1);

--easing-in:          cubic-bezier(0.4, 0, 1, 1);

--easing-out:         cubic-bezier(0, 0, 0.2, 1);

--easing-bounce:      cubic-bezier(0.34, 1.56, 0.64, 1);

Responsive Breakpoints

--breakpoint-sm:   375px;    /* Mobile */

--breakpoint-md:   768px;    /* Tablet */

--breakpoint-lg:   1024px;   /* Small desktop */

--breakpoint-xl:   1280px;   /* Desktop */

--breakpoint-2xl:  1536px;   /* Wide desktop */

Dark Mode

Always generate dark mode tokens alongside light mode. Rules:

• Do not simply invert colors. Dark backgrounds should be warm or cool depending on the philosophy.

• Reduce contrast slightly in dark mode (pure white text on pure black is harsh).

• Shadows should use darker, more transparent values in dark mode, not the same shadows as light.

• Accent colors may need lightness adjustments to maintain contrast ratios.

• Include a prefers-color-scheme media query AND a [data-theme="dark"] attribute selector so the user can support both system preference and manual toggle.

:root {

  /* Light mode tokens */

}

[data-theme="dark"] {

  /* Dark mode overrides */

}

@media (prefers-color-scheme: dark) {

  :root:not([data-theme="light"]) {

    /* System-preference dark mode, unless user explicitly chose light */

  }

}

Output

Save the tokens file in the appropriate location for the project's tech stack. State which philosophy the tokens are derived from and note any deviations or choices made.