Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What are design tokens?

Design tokens are the named values of a design: a color called brand.primary, a spacing step, a font size. Instead of hard-coding #1A73E8 in ten places, you give the value a name once and everything refers to the name. The W3C Design Tokens Community Group defines a JSON format so design tools and code read the same file.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

A designer changes one token; the tokens file feeds CSS variables and components, and every screen picks up the new value from the name.designerdesign toolFigma, Penpot, a scripttokens filebrand.tokens.jsonCSS variables--color-brand-primarycomponents, docsread names, not valuesevery screen1. changes a color2. exports tokens3. build3. build4. renders4. renders
  1. Name each decision: color.brand.primary, space.4, font.size.body. The name says what it is for, not what it is.

  2. Put the values in a tokens file. In the W3C draft format (JSON), an object with a $value is a token, one without is a group, and $type names the kind.

  3. Point one token at another with an alias such as {color.brand.primary}, so button.background follows the brand color automatically.

  4. A build step turns the file into CSS custom properties, platform constants or a theme object. Code refers to names only.

  5. Change the value in one place and every tool, component and page that uses the name updates on the next build.

Source: Design Tokens Community Group: Design Tokens Format Module (draft)

Design tokens versus hard-coded values

A hard-coded value is a decision made in the wrong place. Someone chose #1A73E8 once, and now it appears in a stylesheet, a Figma file, an email template and a chart library, each copy drifting a little. A design token moves the decision up a level. The value gets a name, color.brand.primary, and every place that needs it refers to the name. Change the value and every surface follows.

The W3C Design Tokens Community Group draft puts it plainly: a token is information associated with a human readable name, at minimum a name/value pair. That is the whole idea. Everything else, the file format, the types, the aliases, exists so that tools made by different companies agree on how to read that pair.

Example: one brand color, three outputs

A tokens file in the draft format is JSON. An object with a $value is a token; an object without one is a group; $type says what kind of value it is, and tools are not allowed to guess the type from the value.

{
  "color": {
    "$type": "color",
    "brand": { "primary": { "$value": "#1A73E8" } },
    "button": { "background": { "$value": "{color.brand.primary}" } }
  }
}

{color.brand.primary} is an alias: color.button.background follows the brand color wherever it goes. A build step reads this file and writes a CSS custom property, a Swift constant and a theme object for the web app. Nobody types the hex again. The draft also allows JSON Pointer references with $ref, a $description for documentation, $extensions for tool-specific data and a $deprecated flag for values on their way out.

When to use them

Use tokens as soon as two things need to agree: a design tool and a codebase, two apps on one brand, a light and a dark theme. Name tokens by purpose where you can: text.muted says what it is for, grey.500 says what it is. Purpose-named tokens are what let a dark theme swap values without touching components.

Tokens also help coding agents. An agent that is told the tokens uses them; one that is not will invent a plausible blue. On an Intraface board the collab.md file carries the board's design language, so every agent that pulls the board reads the same palette and type scale before it edits anything.

Common mistakes

  • Tokenising everything. A token is a shared decision. A one-off padding on one component is not; it is noise in the file.
  • Naming by value. blue-600 cannot change to green without lying. color.action.primary can.
  • Treating CSS variables as the source. CSS custom properties are one output of the tokens file. If designers edit Figma and developers edit CSS, you have two sources and no tokens.
  • Guessing types. The draft forbids tools from inferring $type from a value. Set the type on the group once and let tokens inherit it.
  • Citing the draft as final. The format is a Community Group draft (latest published version 2025.10), widely implemented but still changing.

FAQ

Are design tokens the same as CSS variables?
No. CSS custom properties are one thing you generate from a tokens file. The tokens file is the tool-neutral source, which the same build can also turn into platform constants or a theme object.
Is the W3C design tokens format an official standard?
Not yet. It is a draft report from the W3C Design Tokens Community Group, with 2025.10 the latest published version. It is not on the W3C standards track, but design tools and build tools already read it.
Do design tokens need a design tool like Figma?
No. A JSON file in your repository is enough. Design tools matter when designers and developers must share the same values; the file is the thing they share.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.