The short answer

A design token is a named design decision stored as data - color.bg.default, space.4, radius.card - instead of a raw value scattered through files. Each token has a name and a value, and everything in the product references the name. Change the value once and every place that used the token updates with it.

Tokens are the layer beneath a design system. Components are built from tokens; tokens are built from decisions. If a design system is the shared language, tokens are its vocabulary - and you can see full token tables in the wild in Design system examples.

Why tokens exist

The problem tokens solve is drift. When a brand color lives as #2A6FDB hard-coded in two hundred places, a rebrand is a two-hundred-place search-and-replace, and some get missed. When it lives as color.brand.primary, the rebrand is one edit.

  • Single source of truth. One value, one name, one place to change it.
  • Consistency by default. Designers and engineers pull from the same set, so a "blue" is always the same blue.
  • Theming for free. Dark mode, brands, and density become alternate value sets behind the same names.

The three tiers

Mature token sets are layered, so raw values stay separate from how they are used:

  • Primitive (global) tokens. The raw palette - blue.500 = #2A6FDB, gray.900, size.16. No meaning yet, just values.
  • Semantic (alias) tokens. Named by role - color.text.primary, color.bg.surface - each pointing at a primitive. This is the layer components use.
  • Component tokens. Scoped to one component - button.bg.hover - pointing at a semantic token. Optional, for the largest systems.

The indirection is the point: a component references color.text.primary, which points at gray.900 in light mode and gray.50 in dark. The component never changes.

What gets tokenized

Anything that repeats and might change is a candidate:

  • Color - backgrounds, text, borders, states.
  • Spacing - a scale (often 4 or 8px based) for padding, margins, gaps.
  • Typography - font families, sizes, weights, line-heights.
  • Radius, borders, shadows - the shape and depth of surfaces.
  • Motion - durations and easing curves.

Across platforms

Tokens are usually authored as platform-neutral data (JSON) and then transformed into whatever each platform needs: CSS custom properties for the web, Swift for iOS, XML for Android. Tools like Style Dictionary and the emerging W3C Design Tokens format exist to do exactly this transform, so one source produces every platform.

Using them well

  • Name by role, not value. color.text.danger, not color.red - the whole point is that the value can change.
  • Do not over-tokenize. A token for a one-off value adds indirection with no payoff. Tokenize what repeats.
  • Keep the tiers honest. Components use semantic tokens, semantic tokens point at primitives. Skipping the middle layer is how drift creeps back in.

References