design-tokens

Extract code-ready design tokens from a DESIGN.md file. Converts design system documentation into CSS custom properties, Tailwind CSS config, styled-components theme objects, CSS-in-JS themes, or W3C

SKILL.md

GitHub

Extract Design Tokens

Convert a DESIGN.md file into code-ready design tokens in the user's preferred format. This bridges the gap between design documentation and actual code — instead of manually copying hex values and pixel sizes, this skill extracts a complete, structured token set.

What gets extracted

From each DESIGN.md, extract these token categories:

Category Source Section What's extracted
Colors Section 2 All hex values with semantic names and roles
Typography Section 3 Font families, size scale, weight scale, line-heights, letter-spacing
Spacing Section 5 Base unit and full spacing scale
Shadows Section 6 Shadow definitions at each elevation level
Radii Section 5 Border-radius scale
Breakpoints Section 8 Responsive breakpoint values

Available Designs

Read design-md/_index.md for the full catalog of 58 design systems.

Workflow

1. Identify the design

If the user names a brand, match it against the catalog. Read design-md/{directory}/DESIGN.md to load the full design system.

If the user has a DESIGN.md in their project root, use that instead.

2. Determine the output format

Ask which format the user needs (or infer from their project):

CSS Custom Properties — For vanilla CSS or any framework

:root {
  --color-primary: #533afd;
  --color-background: #ffffff;
  --font-display: 'sohne-var', sans-serif;
  --spacing-4: 1rem;
  --shadow-sm: 0px 1px 3px rgba(50,50,93,0.25);
}

Tailwind CSS Config — For Tailwind projects

module.exports = {
  theme: {
    colors: {
      primary: '#533afd',
      background: '#ffffff',
    },
    fontFamily: {
      display: ['sohne-var', 'sans-serif'],
    },
    spacing: { /* ... */ },
    boxShadow: { /* ... */ },
  }
}

Theme Object (JS/TS) — For styled-components, Emotion, Stitches, or Chakra UI

export const theme = {
  colors: {
    primary: '#533afd',
    background: '#ffffff',
  },
  fonts: {
    display: "'sohne-var', sans-serif",
  },
  space: [0, 4, 8, 16, 24, 32, 48, 64],
  shadows: { /* ... */ },
}

W3C Design Tokens JSON — For cross-platform token exchange

{
  "color": {
    "primary": { "$value": "#533afd", "$type": "color" },
    "background": { "$value": "#ffffff", "$type": "color" }
  }
}

SCSS Variables — For Sass projects

$color-primary: #533afd;
$color-background: #ffffff;
$font-display: 'sohne-var', sans-serif;

3. Extract tokens

Read the DESIGN.md and extract every design token into the chosen format.

Colors (from Section 2):

  • Map every named color to a semantic token name
  • Group by role: primary, accent, surface, text, border, interactive, status
  • Include hover/active/focus variants from Section 4

Typography (from Section 3):

  • Font families with full fallback stacks
  • Font size scale mapped to named steps (xs, sm, base, lg, xl, 2xl, etc.)
  • Font weight scale
  • Line-height scale
  • Letter-spacing values

Spacing (from Section 5):

  • Full spacing scale from the base unit
  • Container max-width
  • Gutter sizes

Shadows (from Section 6):

  • Each shadow level as a named token (sm, md, lg, xl)
  • Include multi-layer shadow values exactly as documented

Border Radius (from Section 5):

  • Radius scale (none, sm, md, lg, full/pill)

Breakpoints (from Section 8):

  • Named breakpoints with pixel values

4. Naming conventions

Use consistent naming conventions per format:

Format Convention Example
CSS Custom Properties --{category}-{name} --color-primary, --shadow-lg
Tailwind Tailwind's standard keys colors.primary, boxShadow.lg
Theme Object camelCase nested objects theme.colors.primary
Design Tokens JSON Nested with $value/$type color.primary.$value
SCSS ${category}-{name} $color-primary, $shadow-lg

5. Generate the output file

Write the token file to the appropriate location:

  • CSS: tokens.css or variables.css
  • Tailwind: tailwind.config.js or tailwind.config.ts
  • Theme: theme.ts or theme.js
  • Design Tokens: tokens.json
  • SCSS: _tokens.scss or _variables.scss

Include a header comment noting which design system the tokens were extracted from.

6. Usage guidance

After generating tokens, briefly explain:

  • How to import/use the tokens in their project
  • Any font files or CDN links needed for the typography tokens
  • Which tokens are most important to apply first for maximum visual impact (usually colors + font-family)

Partial extraction

If the user only needs specific categories (e.g., "just give me Stripe's color palette as CSS vars"), extract only what's requested. Don't generate the full token set unless asked.

Multiple designs

If the user wants tokens from multiple design systems (e.g., for a theme switcher), generate separate token sets with a shared structure so they can be swapped at runtime.