What is a design token?

What does design token mean?

The Design Tokens Community Group’s format document defines a token as information associated with a human-readable name. At minimum, it is a name/value pair. The document’s example is color-text-primary: #000000.

Without tokens, the same orange appears as #FF6B3D in dozens of files. To change the colour, you have to find each one. With tokens, you change one line.

Primitive and semantic tokens

Tokens are usually kept in two layers. A primitive token names the raw value. A semantic token says what job that value does.

This site’s own file is an example. In src/ds/tokens.css, the first layer holds primitives such as --c-orange-500: #FF6B3D. According to the comment in the file, components never use them directly.

The second layer is semantic: --accent: var(--c-orange-500), --text: var(--c-ink-900), --bg: var(--c-cream-100). Buttons and cards read only these names.

Layer	What the name says	Example on this site
Primitive	The value itself	--c-ink-900
Semantic	The value’s job	--text

Themes: the same component, different values

A theme binds the semantic tokens to different primitives. The component’s code doesn’t change, only the values behind the names.

That’s how the dark sections of this site work. The data-mood="inverse" rule sets --bg to --c-ink-900 and --text to --c-cream-100. The button’s CSS isn’t touched at all.

Live mini theme

Shipping

Your order is on its way

Estimated delivery: Thursday

Track package

Semantic token	Linked primitive token
--dtk-bg	--c-cream-0 #FFFDF8
--dtk-text	--c-ink-900 #1A1916
--dtk-accent	--c-orange-500 #FF6B3D

The light theme is shown.

The card component reads only three semantic tokens. The theme buttons change which primitive colour those tokens are bound to. The card’s own CSS stays untouched. The colours are the primitives from this site’s src/ds/tokens.css file.

When the theme changes, the contrast changes too. I recommend checking new colour pairs in the contrast checker. You’ll find the thresholds in the WCAG guide.

The W3C Design Tokens Community Group format

To move tokens between tools, there is a shared file format. The Design Tokens Community Group (DTCG) develops it. The group works under the umbrella of the W3C Community Groups.

The Design Tokens Format Module 2025.10 was published on October 28, 2025 as a “Final Community Group Report”. The document notes that it is not a W3C Standard and is not on the W3C Standards Track. It considers itself stable and says it is intended for implementation.

The format is based on JSON. The recommended file extensions are .tokens and .tokens.json. Any object with a $value property is a token; $type is optional. A token can use another token’s value with the {group.token} syntax.

In the separate Color Module of the same date, a colour value is an object: colorSpace and components are required, and hex can be added as a fallback.

{
  "color": {
    "orange-500": {
      "$type": "color",
      "$value": {
        "colorSpace": "srgb",
        "components": [1, 0.4196, 0.2392],
        "hex": "#ff6b3d"
      }
    },
    "accent": { "$type": "color", "$value": "{color.orange-500}" }
  }
}

For different contexts such as light and dark themes, a separate Resolver Module was published on the same day. The same site also hosts a live draft. The draft calls itself a preview and asks not to be implemented.

My note

What I see most often in codebases is several very similar shades of the same colour written all over the place. When a product like that needs a dark theme, you have to open each component one by one.

My advice is to start with a few semantic tokens: background, text, accent, border. Clean up the list of primitives afterwards. In the Design & Ship Sprint, I carry the tokens from the design file into your repository.

Tokens organise the visible layer of the interface. What the interface is, I describe in the glossary entry on UI.