What are design tokens? A plain-English guide with real examples

Design tokens are named, reusable values for the visual decisions in a product — a color, a font size, a spacing step, a corner radius — stored as data instead of hard-coded everywhere. Instead of #635BFF scattered across a codebase, you have color.brand.primary, defined once and referenced everywhere.

That one move — naming values — is what makes a design system consistent, themeable, and (increasingly) readable by AI coding agents.

The token types

Most systems cover the same handful:

• Color — brand, accent, text, surfaces, borders, semantic (success/warn/error).
• Typography — family, size, weight, line-height, letter-spacing, per role (display, body, caption).
• Spacing — a consistent scale (4, 8, 12, 16, 24…) used for padding, gaps, and layout.
• Radius — corner rounding steps.
• Elevation / shadow — the recipes for depth.

The three layers that make tokens powerful

Good token systems are layered:

1. Primitive — raw values: blue.600 = #2b7fff. No meaning, just the palette.
2. Semantic — intent: color.action = {blue.600}. Now the system knows when to use it.
3. Component — specifics: button.background = {color.action}.

The win: re-theme by swapping the primitive layer, and every button, link, and badge updates — because nothing hard-codes a hex value.

What it looks like in real products

Real design systems are just well-organized tokens plus rules:

• Stripe pairs the Söhne typeface with its signature blurple (#635BFF).
• Vercel is built on Geist with a near-monochrome palette.
• Linear leans on Inter and a tight, restrained scale.

Each of those is captured on duply as copyable tokens — colors, type, spacing — not just a screenshot.

Why tokens matter for AI coding

When you hand an AI agent a screenshot, it guesses values and drifts. When you hand it tokens — exact colors, the type scale, the spacing rhythm — plus the rules for applying them, it builds consistent, on-brand UI instead of a pile of plausible-but-random values. That combination (tokens + rules) is what a DESIGN.md file packages.

FAQ

Are design tokens the same as CSS variables? CSS variables are one way to implement tokens in the browser. Tokens are the broader concept — they can compile to CSS variables, a Tailwind theme, JSON, iOS/Android resources, and more.

Do I need three layers? For a small project, primitive + semantic is plenty. The component layer pays off as the system grows.

Where do I get a ready-made token set? Browse the duply library — every entry exposes its tokens as DESIGN.md, Tailwind v4, CSS variables, and JSON.