What Is a Design Token? Design Systems Explained

A design token is a named, platform-agnostic value that stores a single design decision — a color, a spacing unit, a font size, a border radius — so it can be reused consistently across a codebase instead of being hardcoded in dozens of places. Instead of writing #3366FF in one component and #3366ff in another, both reference color.brand.primary. Change the token once, and every consumer updates.

Tokens are the connective tissue of a design system: the layer that lets a color chosen in a design tool and a color used in production CSS trace back to the same source of truth.

Why not just use CSS variables directly?

You can, and many teams do — CSS custom properties are a common output format for tokens. But a token system is a layer above raw CSS variables for a few reasons:

• Platform independence. A token like spacing.md needs to become 8px in CSS, 8.dp in Android XML, and 8pt in iOS Swift. The token itself is just a name and a value; a build step transforms it into whatever format each platform needs.
• Semantic naming. Tokens are usually layered: a base token (blue-500: #3366FF) feeds a semantic token (color.brand.primary: {blue-500}), which feeds a component token (button.background: {color.brand.primary}). Components reference the semantic layer, so redesigning the brand color only means repointing one alias.
• Tooling. Tools like Style Dictionary or Tokens Studio read a JSON or YAML token definition and generate CSS, Sass, Android, and iOS output from a single file, keeping design tools and code from drifting apart.

The three-tier pattern

Most mature token systems split values into three layers:

1. Reference (base) tokens — raw values with no semantic meaning: gray-100, blue-600, space-4. These rarely change.
2. System (semantic) tokens — meaning applied to a reference token: color.text.primary, color.surface.danger, spacing.card-padding. These are what most components should consume.
3. Component tokens — scoped to one component: button.primary.background, modal.border-radius. These exist for the rare case where a single component needs to diverge from the semantic default.

This layering is what makes a rebrand tractable: swap the reference tokens, and everything downstream — semantic tokens, component tokens, and every screen — updates without touching component code.

Tokens and dark mode

Design tokens are also how most teams implement theming. Rather than writing separate stylesheets, a semantic token like color.background.primary resolves to a light value in the default theme and a dark value under prefers-color-scheme: dark or a data-theme attribute — the same pattern covered in CSS’s light-dark() function. Because components only ever reference semantic tokens, they don’t need any theme-aware logic themselves; the token resolution handles it.

Design tokens vs a CSS framework

	Design tokens	Utility CSS framework
What it is	A data format for design decisions	A pre-built set of utility classes
Platform reach	Web, iOS, Android, design tools	Web only
Source of truth	JSON/YAML token file	Framework’s config file
Typical use	Powers a custom design system	Ships a ready-made visual language

They’re not mutually exclusive — a project can define tokens and then configure a utility framework to read from them, so class names like bg-brand-primary resolve to the same values used elsewhere.

Building a token pipeline

A minimal token pipeline looks like this:

1. Define tokens in a structured format (JSON is the most common; the W3C Design Tokens Community Group has a draft format many tools now support).
2. Run a build tool (Style Dictionary is the most widely used) that transforms the token file into per-platform outputs: CSS custom properties, a Sass map, Android resource XML, iOS Swift constants.
3. Consume the generated output in each platform’s codebase, ideally via a published package so every app pulls the same version.
4. Wire the pipeline into CI so a token change automatically opens a PR against consuming repos, or publishes a new package version.

Keep the raw token file as the single edit point. Generated CSS or Sass files should never be hand-edited — they get overwritten on the next build, and drift creeps back in exactly the way tokens were meant to prevent.

Common pitfalls

• Too many one-off values. If every component gets its own component-tier token, you’ve just reinvented hardcoded values with extra steps. Reserve component tokens for genuine exceptions.
• Skipping the semantic layer. Referencing base tokens (blue-600) directly in components ties your UI to a specific palette. When the brand changes, you’re back to a global find-and-replace.
• No naming convention. Token names should follow a predictable pattern (category.property.variant) so anyone on the team can guess a token’s name before searching for it.

The takeaway

A design token is a single named source of truth for one design decision, structured in layers — reference, semantic, component — so a rebrand or theme change is a data edit, not a codebase-wide search-and-replace. Pair semantic tokens with CSS mechanisms like custom properties and light-dark() for theming, keep raw values out of components, and let a build pipeline handle translating the same token file into whatever format each platform needs.