Design Tokens Explained

Every DESIGN.md in our library is, underneath the prose, a set of design tokens with job descriptions. Design tokens explained in one sentence: they are named, reusable design decisions — --color-ink: #171717 instead of a hex scattered through 200 files. The concept predates AI coding, but agents have raised the stakes: a model can't respect decisions that were never named. This article covers the tiers, the naming, and the export formats that make tokens work in an agent-driven codebase.

Primitive vs semantic: the two tiers that matter

Token systems get described with three or four tiers, but two do the real work:

Primitive tokens name raw values with no opinion about use: gray-100: #F2F2F2, blue-500: #0072F5, radius-md: 8px. They're the vocabulary.

Semantic tokens assign those primitives to roles: --surface-recessed: var(--gray-100), --interactive: var(--blue-500), --radius-control: var(--radius-md). They're the grammar — and they're what components should consume.

The payoff is indirection: when the brand shifts, you re-point semantic tokens and every component follows. The failure mode is components reaching past semantics into primitives (bg-gray-100 where bg-surface-recessed was meant) — which is precisely the mistake agents make when your Tailwind config exposes primitives but your DESIGN.md speaks in roles. Keep the two vocabularies synchronized.

Naming that survives contact with an agent

Good token names answer "where may this be used?" without a lookup:

• --color-interactive beats --blue (what happens when the brand goes green?)
• --surface-elevated beats --white (dark mode inverts the value, not the role)
• --text-muted beats --gray-3 (what's grayer, 3 or 4? nobody remembers)

Role-first names double as constraints in prose: "muted text uses --text-muted" is a rule a model can follow and a reviewer can check. This is why, in every design tokens explained walkthrough we write, naming gets more space than syntax — the names are the design system.

The categories a complete set covers

Color gets the attention, but a component is styled by six token families working together:

| Family | Examples | Common miss | | ---------- | --------------------------------------------------- | -------------------------- | | Color | ink, surfaces, interactive, status | roles for text on colors | | Typography | families, size/line-height pairs, weights, tracking | display-size tracking | | Spacing | base unit, scale steps, section rhythm | max content widths | | Radius | control/card/pill stops | which stop applies where | | Elevation | shadow recipes, incl. tint | shadow color ≠ pure black | | Motion | durations, easings | what never animates |

If your file covers all six with real values, an agent can build a screen without inventing anything. That completeness test is exactly what our generator aims at when it extracts a site's styles into a DESIGN.md draft.

Export formats: one source, three targets

Tokens are only useful where your toolchain can reach them. The three exports every brand page on this site ships:

CSS custom properties — the runtime source of truth:

:root {
  --background: #fafafa;
  --foreground: #171717;
  --primary: #0072f5;
}

Tailwind theme — so utility classes speak your vocabulary:

theme: {
  extend: {
    colors: { canvas: 'var(--background)', ink: 'var(--foreground)' },
  },
}

JSON (W3C draft format) — for Style Dictionary pipelines, Figma sync, and any tool that wants structured data. Design tokens explained at the format level is mostly this: one decision, three syntaxes:

{ "color": { "ink": { "value": "#171717", "type": "color" } } }

Pick CSS variables as the canonical layer and generate the other two — hand-maintaining three copies guarantees drift.

Design tokens explained next to DESIGN.md: the division of labor

A token file says what; a DESIGN.md says what, where, and never. Tokens alone can't tell an agent that blue is forbidden on decorative elements or that weight 700 doesn't exist — that's contract language, and it lives in the design file's role descriptions and don'ts (see how to write a design md). The two artifacts work as a pair: DESIGN.md for constraints and rationale, token exports for toolchain enforcement. Wire both into your agent per the Claude Code guide and generated UI stops needing color-correction review.

To see tokens extracted from production sites — with the role assignments that make them usable — open any brand in the library: Vercel and Stripe are the clearest studies in design tokens explained through real systems. Or point the generator at your own site and get your token inventory named, roled, and exported in one pass.