DESIGN.md is a prompt artifact. It tells AI tools what your design system looks like. But you also want those same tokens living in your actual codebase as CSS variables, so your hand-written code and your AI-generated code share the same values.

Here is the exact mapping. Copy what you need.

Why you want tokens in CSS

When an AI tool reads your DESIGN.md and generates a component with color: var(--primary), that variable needs to exist in your CSS. Otherwise the generated code references nothing.

More importantly: consistency. If your DESIGN.md says primary is #5E6AD2 but your global.css has --blue: #4A90E2, you have two different systems. One of them will win and it will not be the one you intended.

One source of truth. DESIGN.md defines it. CSS variables expose it. Tailwind references it. Done.

Colors

Every color token in your DESIGN.md becomes a CSS custom property. The names map directly.

:root {
  /* Colors */
  --primary: #5E6AD2;
  --on-primary: #FFFFFF;
  --primary-hover: #4F5BB5;
  --background: #0A0A0A;
  --surface: #111111;
  --surface-2: #1A1A1A;
  --text: #F4F4F5;
  --text-muted: #A1A1AA;
  --border: #27272A;
  --accent: #5E6AD2;
  --success: #16A34A;
  --danger: #DC2626;
  --warning: #D97706;
}

Use these exact names. AI tools that read your DESIGN.md will reference them by name in the code they generate. If your CSS uses different names, the reference breaks.

Typography

Typography tokens split into font family, size, weight, line height, and letter spacing. Each gets its own variable.

:root {
  /* Typography */
  --font-display: 'Inter', system-ui, sans-serif;
  --font-heading: 'Inter', system-ui, sans-serif;
  --font-body: 'Inter', system-ui, sans-serif;
  --font-code: 'JetBrains Mono', 'Fira Code', monospace;

  --size-display: 48px;
  --size-heading: 24px;
  --size-body: 15px;
  --size-code: 13px;

  --weight-display: 600;
  --weight-heading: 600;
  --weight-body: 400;

  --leading-display: 1.1;
  --leading-heading: 1.3;
  --leading-body: 1.6;

  --tracking-display: -0.03em;
  --tracking-heading: -0.02em;
  --tracking-body: 0em;
}

You will not use all of these in every component. But having them defined means you can write font-size: var(--size-body) anywhere and know it will always match what the AI is generating from the DESIGN.md.

Spacing and radius

The spacing scale becomes numbered variables. The numbers match the pixel values, not sequential indices.

:root {
  /* Spacing scale */
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-3: 12px;
  --spacing-4: 16px;
  --spacing-6: 24px;
  --spacing-8: 32px;
  --spacing-12: 48px;
  --spacing-16: 64px;
  --spacing-24: 96px;

  /* Border radius */
  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-xl: 16px;
  --radius-pill: 9999px;
}

Tailwind integration

If you are using Tailwind, wire the CSS variables into the theme extend section. This lets you use Tailwind classes like bg-surface and text-muted that AI tools will naturally reach for.

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: 'var(--primary)',
        'on-primary': 'var(--on-primary)',
        background: 'var(--background)',
        surface: 'var(--surface)',
        'surface-2': 'var(--surface-2)',
        foreground: 'var(--text)',
        muted: 'var(--text-muted)',
        border: 'var(--border)',
        accent: 'var(--accent)',
        success: 'var(--success)',
        danger: 'var(--danger)',
        warning: 'var(--warning)',
      },
      fontFamily: {
        display: 'var(--font-display)',
        heading: 'var(--font-heading)',
        body: 'var(--font-body)',
        code: 'var(--font-code)',
      },
      spacing: {
        '1': 'var(--spacing-1)',
        '2': 'var(--spacing-2)',
        '3': 'var(--spacing-3)',
        '4': 'var(--spacing-4)',
        '6': 'var(--spacing-6)',
        '8': 'var(--spacing-8)',
        '12': 'var(--spacing-12)',
        '16': 'var(--spacing-16)',
        '24': 'var(--spacing-24)',
      },
      borderRadius: {
        sm: 'var(--radius-sm)',
        md: 'var(--radius-md)',
        lg: 'var(--radius-lg)',
        xl: 'var(--radius-xl)',
        pill: 'var(--radius-pill)',
      },
    },
  },
};

Now when Claude or Cursor generates a card component using bg-surface border-border, those classes actually work.

Dark mode

Use data attributes, not the prefers-color-scheme media query. Data attributes let you toggle programmatically without fighting the browser default.

The only tokens that change between light and dark are backgrounds, surfaces, text, and borders. Colors like primary, success, danger, and warning stay the same.

[data-theme="dark"] {
  --primary: #5E6AD2;
  --on-primary: #FFFFFF;
  --primary-hover: #4F5BB5;
  --background: #0A0A0A;
  --surface: #111111;
  --surface-2: #1A1A1A;
  --text: #F4F4F5;
  --text-muted: #A1A1AA;
  --border: #27272A;
}

[data-theme="light"] {
  --primary: #5E6AD2;
  --on-primary: #FFFFFF;
  --primary-hover: #4F5BB5;
  --background: #FFFFFF;
  --surface: #F4F4F5;
  --surface-2: #E4E4E7;
  --text: #09090B;
  --text-muted: #71717A;
  --border: #E4E4E7;
}

Let the AI do it

You do not have to map all of this by hand. Drop your DESIGN.md into Claude and use this prompt:

Here is my DESIGN.md. Generate a complete CSS file with custom properties for all color, typography, and spacing tokens. Include both a light mode set under [data-theme="light"] and a dark mode set under [data-theme="dark"]. Use the token names from the DESIGN.md as variable names, kebab-cased.

You will get a complete CSS file back in under 30 seconds. Review it, drop it into your globals.css, and you are done.

The one thing to check: make sure the variable names in the generated CSS match what the AI will use when generating components. If you see any mismatches, fix the CSS variable names to match the DESIGN.md token names exactly.

Get the DESIGN.md first

Browse 110 design systems, download the DESIGN.md, then turn those tokens into CSS variables.

Browse the catalog