What Are Design Tokens and Why Your AI Needs Them

Design tokens, explained simply

A design token is a named value that represents a design decision. Instead of saying "the primary button background is #9C4221," you say:

--color-primary: #9C4221;

That name - --color-primary - is the token. The value (#9C4221) can change, but the name stays the same. Every component that uses --color-primary updates automatically when the value changes.

Tokens are not a new idea. Designers have used them in Figma, Sketch, and design systems for years. What is new is their importance to AI: tokens are how agents understand your visual system without reading a 40-page PDF.

The three layers of tokens

Design tokens operate at three levels of abstraction:

1. Global tokens - The raw values

These are your palette: every color, every font size, every spacing value your system uses.

/* Global tokens - raw values */
:root {
  --color-rust-700: #9C4221;
  --color-amber-600: #D97706;
  --color-cream-50: #FFFBF5;
  --color-stone-900: #1C1917;

  --font-serif: 'Instrument Serif', serif;
  --font-sans: 'DM Sans', sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-8: 2rem;
  --space-16: 4rem;
}

2. Semantic tokens - The roles

Semantic tokens assign meaning to global tokens. This is where design decisions live.

/* Semantic tokens - roles and meaning */
:root {
  --color-primary: var(--color-rust-700);
  --color-accent: var(--color-amber-600);
  --color-bg: var(--color-cream-50);
  --color-bg-dark: var(--color-stone-900);

  --font-display: var(--font-serif);
  --font-body: var(--font-sans);
  --font-code: var(--font-mono);

  --spacing-section: var(--space-16);
  --spacing-component: var(--space-8);
}

3. Component tokens - The specific applications

Component tokens bind semantic tokens to specific UI elements.

/* Component tokens — specific applications */
:root {
  --button-primary-bg: var(--color-primary);
  --button-primary-text: var(--color-cream-50);
  --button-primary-hover: #7C3118;

  --heading-font: var(--font-display);
  --heading-tracking: 0.02em;

  --card-padding: var(--spacing-component);
  --card-radius: 4px;
  --card-border: 1px solid rgba(196, 181, 166, 0.3);
}

How AI agents consume tokens

This is where it gets interesting. An AI agent building a component does not need to know your entire brand guide. It needs to know which token to use where.

CSS custom properties

The most direct format. Agents generating HTML/CSS can reference variables directly:

.hero-cta {
  background: var(--color-primary);
  color: var(--button-primary-text);
  font-family: var(--font-body);
  padding: var(--space-4) var(--space-8);
  border-radius: var(--card-radius);
}

An agent that reads your tokens.css knows every visual constraint without interpretation.

Tailwind configuration

If your stack uses Tailwind CSS, tokens map to the config file:

// tailwind.config.js - generated from design tokens
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#9C4221',
        accent: '#D97706',
        cream: '#FFFBF5',
        dark: '#1C1917',
      },
      fontFamily: {
        display: ['Instrument Serif', 'serif'],
        body: ['DM Sans', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
      spacing: {
        section: '4rem',
        component: '2rem',
      },
      borderRadius: {
        card: '4px',
      },
    },
  },
};

Now an agent generating Tailwind classes knows to use bg-primary for CTAs and font-display for headings without reading a PDF.

Figma tokens (JSON format)

Figma's design token format is a JSON structure that tools like Style Dictionary and Tokens Studio consume:

{
  "color": {
    "primary": {
      "value": "#9C4221",
      "type": "color",
      "description": "CTAs, hero accents, key links. Never for body text."
    },
    "accent": {
      "value": "#D97706",
      "type": "color",
      "description": "Secondary actions, highlights, badges."
    }
  },
  "font": {
    "display": {
      "value": "Instrument Serif",
      "type": "fontFamily",
      "description": "Headlines and hero text only."
    },
    "body": {
      "value": "DM Sans",
      "type": "fontFamily",
      "description": "All body copy, UI text, navigation."
    }
  }
}

The description field is critical for agents. It is not enough to know the value. Agents need to know the usage rule.

The agent consumption pipeline

Here is how tokens flow from your brand guide to an AI agent's output:

Brand Guide (PDF/Figma)
       |
       v
   Extraction (BrandMythos)
       |
       v
  Token files (CSS, Tailwind, JSON)
       |
       v
  Repository (version controlled)
       |
       v
  Agent loads tokens at runtime
       |
       v
  Generated output uses correct tokens

Without this pipeline, agents guess. With it, agents are correct by default.

Why tokens matter more than brand guides

A brand guide says: "Our primary color is a warm rust tone, hex #9C4221. Use it for calls to action and key interactive elements. Avoid using it for large background areas or body text."

That is 30 words of prose that an agent has to parse, interpret, and remember.

A token says:

--color-primary: #9C4221; /* CTAs and key links only. Never body text. */

That is 1 line of code that an agent loads, indexes, and applies without interpretation.

Multiply this across 50 design decisions (colors, fonts, spacing, radii, shadows, breakpoints) and the difference is enormous. Prose requires interpretation at scale. Tokens do not.

Real-world example: Before and after tokens

Before tokens

A developer asks Claude: "Build a pricing card component for our SaaS."

Claude generates a card with:

• Blue background (generic default)
• Arial font (safe fallback)
• 8px border radius (Tailwind default)
• "Sign Up" button in green

None of this matches the brand. The developer spends 20 minutes fixing styles.

After tokens

The developer's repo contains tokens.css and a CLAUDE.md that references it.

Claude generates a card with:

• var(--color-bg) background (#FFFBF5)
• var(--font-body) font (DM Sans)
• var(--card-radius) border radius (4px)
• CTA button using var(--color-primary) (#9C4221)

First output matches the brand. Zero manual fixes.

From Figma to code to agent

The modern design-to-code pipeline should include agents as a first-class consumer:

1. Designer creates tokens in Figma (Tokens Studio or native variables)
2. Build tool transforms tokens to CSS, Tailwind, JSON (Style Dictionary, token-transformer)
3. Engineer commits token files to the repo
4. Agent reads token files when generating components or copy
5. CI validates that generated output uses tokens, not hardcoded values

BrandMythos slots into step 2: we extract tokens from any source (URL, PDF, Figma, Drive) and generate all output formats simultaneously. See how the extraction works.

Common mistakes with design tokens

1. No usage rules. A token without a description is a value without guidance. Always include usage constraints.

2. Hardcoded values in components. If agents (or developers) write color: #9C4221 instead of color: var(--color-primary), you lose the ability to update centrally.

3. Too many tokens. A system with 500 tokens is as hard to navigate as a PDF. Keep it under 50 for most brands. Start with colors, fonts, and spacing.

4. No semantic layer. Jumping from global tokens (--color-rust-700) to components without a semantic layer (--color-primary) creates fragile references. Always have the role layer in between.

5. Separate from brand governance. Tokens should live alongside CLAUDE.md and .cursorrules, not in a separate system. Co-locate them in the repo.

Getting started

If you already have a design system in Figma:

1. Export tokens as JSON using Tokens Studio
2. Transform to CSS custom properties using Style Dictionary
3. Commit to your repo alongside CLAUDE.md
4. Reference tokens in your CLAUDE.md visual section

If you do not have a design system yet:

1. Start with 5 colors, 3 fonts, and 4 spacing values
2. Write them as CSS custom properties
3. Document usage rules as comments
4. Commit and reference in CLAUDE.md

Or skip the manual work. Try BrandMythos. Enter your URL and we extract design tokens automatically, generating CSS custom properties, Tailwind config, and Figma-compatible JSON in one step.