Skip to content
UX Atlas
Plate SYS·001 · Design systemGrid D4 · Rev. 2026-09-14

Design Tokens

Named values that carry design decisions, so a change happens once rather than in every consuming file.

Design systemCraft conventionIntermediate

Definition

A design token is a named entity storing a design decision: a colour, a spacing step, a font size, a duration. Tokens are consumed by designs and by code, which is what keeps the two in sync.

Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.

On this plate
  1. 1Definition
  2. 2Three layers, and why the middle one matters
  3. 3Naming that survives
  4. 4One source, three outputs
  5. 5Keeping the set usable
  6. 6What the three layers buy you
  7. 7In practice
  8. 8Local chart
  9. 9Sources
  10. 10Continue from here

Reach for this when

  • Starting a design system.
  • Adding a theme or a second brand.
  • Consolidating values that have grown organically.

Common mistakes

  • Components referencing primitives.
  • Names describing appearance.
  • Too many tokens.
  • Tokens defined in design but not in code, or the reverse.

Three layers, and why the middle one matters

LayerExampleWho uses it
Primitiveblue-600, space-4, size-16Only the semantic layer. Never a component.
Semanticaction-primary, surface-raised, text-secondaryComponents and designers. This is the API.
Componentbutton-primary-backgroundOne component. Optional, and only where a component genuinely needs its own decision.

Naming that survives

  • Name by role, not by appearance. text-secondary survives a palette change; text-grey does not.
  • Use a consistent structure, such as category, role, variant, state.
  • Do not encode the value in the name. space-16 breaks when the scale changes.
  • Keep the set small enough that people can hold it in mind. A hundred colour tokens will be used inconsistently.
  • Document what each token is for, with an example of the wrong choice.

One source, three outputs

text
# source of truth: tokens/semantic.json (DTCG shape)
{
  "action": {
    "primary": {
      "$type": "color",
      "$value": "{palette.blue.600}",
      "$description": "Primary action fill. Not for links."
    }
  }
}

# generated: web/tokens.css
:root { --action-primary: #2563eb; }

# generated: ios/Tokens.swift
static let actionPrimary = Color(hex: 0x2563EB)

# generated: design tool variables, from the same pipeline

Tokens authored once and generated into every consuming format. Hand-copying any one of these outputs is where drift starts, and preventing that is the reason the layer exists.

Keeping the set usable

Do

  • Define the token set before the component library, since components built against ad-hoc values have to be rewritten.
  • Give every semantic token one job, and state in its description what the wrong use would be.
  • Generate every consuming format from the same source, including the design tool's variables.
  • Delete a token when its last consumer goes. Anything left in the list will be adopted by the next person reading it.

Do not

  • Do not add a token for a value used once. A one-off belongs in the component until it recurs.
  • Do not encode a theme in a semantic name. A token called text-primary-dark defeats the remap that makes theming work.
  • Do not let two semantic tokens resolve to the same primitive without a reason you can state. Either they mean different things or one of them should go.
  • Do not publish primitives as part of the API. Consumers will reference them, and the layer stops being replaceable.

What the three layers buy you

Primitiveblue-600grey-900space-16Semanticaction-primarytext-primarygap-tightComponentButtonCardTable rowDark, brand B, high contrastremap this layer only
Components reference the semantic layer and nothing else, which is what lets a theme, a brand or a contrast mode change the product without a component being edited.

In practice

  1. i.

    Rebranding without touching components

    Multi-brand products

    A product supporting several brands changes only the semantic token mapping per brand. Component code is untouched, which is what makes multi-brand maintainable at scale.

Local chart

SYS·001 · Region VI · Grid D4

This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.

Consistency and StandardsHEUR·004 · PRINCIPLES BEHIND THISThemingSYS·008 · RELIED ON BYFigmaTOOL·001 · OFTEN USED WITHFigma Dev ModeTOOL·042 · OFTEN USED WITHPenpotTOOL·003 · OFTEN USED WITHSketchTOOL·002 · OFTEN USED WITHStyle DictionaryTOOL·040 · OFTEN USED WITHSupernovaTOOL·039 · OFTEN USED WITHzeroheightTOOL·038 · OFTEN USED WITHChoosing a Density for an Analytics DashboardCASE·004 · PRACTICAL EXAMPLEMigrating Product Teams onto a Design SystemCASE·003 · PRACTICAL EXAMPLEDesign SystemTERM·084 · SHORT DEFINITION

Sources

Where a source establishes something narrower than the popular reading of it, the note says so.

  1. [1]

    Design Tokens Format Module

    Design Tokens Community Group, W3C Community Group

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Principles behind this

The reasoning this solution is an application of.

Relied on by

Entries that assume this is already in place.

  • ThemingSYS·008 · Design system

    Theming is token remapping. Without a semantic token layer there is nothing to remap.

Often used with

These usually appear in the same screen or the same decision.

Practical example

A worked decision where this was the deciding factor.

Short definition

The one-paragraph version, for when that is all you need.

Related concept

Connected closely enough to change how you apply this.