What Is a Design Token? Definition, Examples, and Formats

Plain-English definition

A design token is a named storage unit for a single visual decision. Instead of hardcoding #0F172A in every button stylesheet, you define a token: --color-primary: #0F172A. Every component that needs the primary color references the token name, not the raw value.

When the color changes, you update the token once. Every component that references it updates automatically. That is the core value: tokens make visual decisions single-source-of-truth.

The term comes from Salesforce's Lightning Design System (2014), which popularized the pattern. Today, design tokens are a W3C standard (DTCG), supported by Figma, Style Dictionary, Tailwind, and every major design system framework.

Token types: primitive, semantic, and component

Most design systems organize tokens into two or three layers. Understanding the layers clarifies how tokens scale from a small project to a large design system.

Primitive tokens (global tokens)

Primitive tokens store raw values with no implied meaning. They define everything that exists in your palette — the full range of colors, every available font size, every spacing step.

/* Primitive tokens — what exists */
--indigo-100: #dbeafe;
--indigo-500: #6366F1;
--indigo-900: #1e1b4b;
--space-1:    4px;
--space-4:    16px;
--space-10:   40px;

Semantic tokens (alias tokens)

Semantic tokens map primitives to roles — they define where each value is used. A semantic token has a name that communicates intent, not just value.

/* Semantic tokens — where it's used */
--color-interactive:   var(--indigo-500);
--color-text-primary:  var(--indigo-900);
--spacing-component:   var(--space-4);
--spacing-section:     var(--space-10);

The separation matters for theming: swapping from a light to dark theme means updating semantic token mappings (e.g. --color-background: var(--indigo-900) in dark mode) without touching primitive values or component code.

Component tokens (component-specific tokens)

Component tokens are scoped to a single component. They reference semantic tokens and allow component-level customization without breaking the system.

/* Component tokens — scoped overrides */
--button-bg:          var(--color-interactive);
--button-text:        var(--color-text-inverse);
--button-radius:      8px;
--button-padding-x:   var(--spacing-component);

Small projects often skip component tokens and reference semantic tokens directly in component CSS. Large design systems with multiple themes and component libraries use all three layers.

What tokens look like in practice

Here is a minimal but complete token set for a typical SaaS product. This covers the decisions that matter most for visual consistency.

## Colors
--color-primary:    #0F172A   /* brand, headings, filled buttons */
--color-accent:     #6366F1   /* links, focus rings, interactive */
--color-success:    #22c55e   /* success states, confirmations */
--color-warning:    #f59e0b   /* warnings, caution indicators */
--color-danger:     #ef4444   /* errors, destructive actions */
--color-surface:    #F8FAFC   /* page background, card fills */
--color-border:     #E2E8F0   /* dividers, input borders */
--color-text:       #0F172A   /* primary body text */
--color-text-muted: #94A3B8   /* secondary text, captions */

## Typography
--font-display:  'Inter', sans-serif
--font-mono:     'Menlo', 'Monaco', monospace
/* Typography shorthand: size / weight / line-height (reference format, not valid CSS) */
--text-xs:    12px / 500 / 1.4
--text-sm:    14px / 400 / 1.5
--text-base:  16px / 400 / 1.6
--text-lg:    18px / 400 / 1.6
--text-xl:    24px / 600 / 1.3
--text-2xl:   32px / 700 / 1.2
--text-4xl:   48px / 700 / 1.1

## Spacing (4px base unit)
--space-1:   4px    --space-4:  16px   --space-10: 40px
--space-2:   8px    --space-6:  24px   --space-16: 64px
--space-3:   12px   --space-8:  32px   --space-20: 80px

## Radius
--radius-sm:  4px    /* tags, chips */
--radius-md:  8px    /* buttons, inputs */
--radius-lg:  12px   /* cards */
--radius-xl:  16px   /* modals, sheets */
--radius-full: 9999px /* pills, avatars */

Token formats: DTCG JSON, CSS variables, Tailwind

The same token values can be expressed in multiple formats. Which format you use depends on where you consume the tokens.

DTCG JSON (W3C standard)

The Design Token Community Group standard uses JSON with $value and $type fields. This is the most interoperable format — supported by Style Dictionary, Figma Token Studio, Token Transformer, and most modern design system tooling.

{
  "color": {
    "primary": {
      "$value": "#0F172A",
      "$type": "color",
      "$description": "Brand color, used for headings and filled buttons"
    },
    "accent": {
      "$value": "#6366F1",
      "$type": "color"
    }
  },
  "spacing": {
    "component": {
      "$value": "24px",
      "$type": "dimension"
    }
  }
}

CSS custom properties

The most direct way to use tokens in web projects. Define at :root, reference anywhere in your stylesheets.

:root {
  --color-primary:   #0F172A;
  --color-accent:    #6366F1;
  --spacing-base:    4px;
  --spacing-section: 80px;
  --radius-button:   8px;
}

.button {
  background: var(--color-primary);
  border-radius: var(--radius-button);
}

Tailwind v4 config

Tailwind v4 uses CSS-based configuration. Your token values map directly to Tailwind utilities, making them usable as bg-primary, text-accent, etc.

@theme {
  --color-primary:   #0F172A;
  --color-accent:    #6366F1;
  --spacing-section: 80px;
  --radius-button:   8px;
  --font-sans: 'Inter', sans-serif;
}

Style Dictionary (multi-platform transformation)

Style Dictionary (Amazon open source) is a build tool, not a storage format — it reads a DTCG JSON token file and transforms it into any platform output: CSS custom properties, iOS Swift constants, Android XML resources, JavaScript ES modules.

// style-dictionary.config.js
export default {
  source: ['tokens/design-tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      files: [{ destination: 'variables.css', format: 'css/variables' }],
    },
    ios: {
      transformGroup: 'ios-swift',
      files: [{ destination: 'StyleTokens.swift', format: 'ios-swift/enum.swift' }],
    },
  },
};

If your project targets multiple platforms (web + iOS + Android), DTCG JSON as the source of truth fed into Style Dictionary is the industry-standard architecture. MYDESIGN.MD outputs DTCG JSON directly, so it drops into an existing Style Dictionary pipeline without conversion.

How to extract tokens from an existing website

Most production sites have an implicit token set encoded in their CSS — consistent colors, a repeating spacing scale, a defined type hierarchy. Extracting that set means surfacing the underlying decisions and documenting them explicitly.

The manual process (inspecting DevTools, recording values, writing JSON) takes 8–20 hours for a typical SaaS site. The automated approach:

1. Paste any public URL into MYDESIGN.MD
2. The extractor runs CSS parsing, DOM inspection, screenshot analysis, and font detection in parallel
3. Output: DESIGN.md, design-tokens.json (DTCG), variables.css, and tailwind.config.v4.css

The extracted tokens are ready to use — commit to your repo, import into Figma, feed into Style Dictionary, or paste into an AI agent context.

Why tokens matter for AI coding agents

AI coding agents (Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf) write code that works but looks wrong — wrong color, wrong spacing, wrong radius — because they have no access to your token values. Without explicit context, each session defaults to generic values.

Design tokens fix this. A DESIGN.md file in your project root, loaded into the agent as context, gives it your exact values. The agent then applies #0F172A instead of a generic dark color, 8px border radius instead of the default, and your Inter type scale instead of arbitrary sizes.

For step-by-step setup instructions for each agent, see the companion guide: Design Tokens for AI Coding Agents →

Frequently asked questions