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.