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
- Check what already exists. Before generating anything, scan the codebase for: If tokens already exist, extend them rather than replacing. Identify gaps (missing dark mode, incomplete spacing scale, no motion tokens) and fill those.
- 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.)
- 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-designto 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"]orprefers-color-schememedia 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-schememedia 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.