Insights
Design tokens are named design decisions that code, Figma and AI tools all read. What they fix, what they do not, and when to fund them. A design token is a named design decision.
The short answer
A design token is a named design decision. Instead of a button using the colour `#1D4ED8`, it uses a name such as `color.action.primary`, and one place says what that name currently means. Design tools, code and, increasingly, AI code generators all read the same name, so a change made once reaches every screen that uses it.
Atlassian puts it as a single source of truth to name and store design decisions: each token is a name paired with a value for a small, repeatable decision such as a colour, a spacing unit or a type style. The practice has a long history. Salesforce's own training material says its engineering team chose the term "design tokens" at the 2013 Salesforce1 launch for style values that had to work across native apps and the web, and Jina Anne, who worked on that system, describes the idea in a Smashing Podcast episode: values stored once as data, with a tool generating the code each platform needs.
For a product lead the useful question is not what a token is but what it buys you. Tokens make decisions portable. They do not make decisions good, and they do not make components consistent. The rest of this page covers what they fix, what they leave alone and how to tell whether your team needs them now, later or not yet.
One brand colour, three levels
Most mature systems layer tokens in three tiers. Material Design 3 documents the pattern clearly in its theming guide: reference tokens hold concrete values, system tokens give those values roles, and component tokens apply roles to a specific element. Take your brand blue.
- Primitive (Material calls it reference). `blue-600` equals one exact blue. It says nothing about where the blue is used. Its only job is to be the single place that blue is defined.
- Semantic (Material calls it system). `color.action.primary` points at `blue-600`. This is the tier that carries meaning. In dark mode, the same name can point at a lighter blue, and nothing that uses the name has to change.
- Component. `button.primary.background` points at `color.action.primary`. A component token lets one component deviate on purpose, without anyone editing the shared meaning.
Rebrand the blue and you edit one primitive. Add a dark theme and you re-point semantic tokens. Let one component differ and you touch only its component token. Atlassian's naming guidance adds a useful discipline: choose tokens by meaning rather than by how their values look, so `color.icon.success` is used for success, not because green happens to be nearby.
What tokens fix
- Theming and dark mode. A theme is a set of token values. Atlassian treats light, dark and high-contrast modes as colour themes, and compact views, reduced motion or custom typography as non-colour ones. Figma works the same way: a variable collection can hold several modes, each with one value per variable, so one set of designs switches contexts without duplicated frames.
- Several brands on one product. Re-pointing semantic tokens per brand is how one component library serves many. Our piece on designing one component for many brands covers that method, so we do not repeat it here.
- Rebrands. A change to a colour, typeface or radius becomes an edit to a small set of values rather than a search through every file.
- Platform parity. One token source can produce web, iOS and Android output, which is why the format was designed for cross-platform use. How you build that output is a pipeline question (Style Dictionary is one such build tool) and outside this page.
- Handing rules to AI code tools. Figma's guidance for its MCP server is to use variables for spacing, colour, radius and typography so an agent references your tokens instead of hardcoding values. Our view, which is a judgement and not a measured result: a tool can follow a token name it can see, and has nothing to follow when the decision was never named.
What tokens do not fix
Tokens are not a design system. They name values; they do not decide which components exist, which states each component has or who may change either. A team with tokens and no agreed components, states or owner has made its drift faster, not smaller, because inconsistent choices now propagate in one step.
| The problem you have | Do tokens help? | What else you need |
|---|---|---|
| Brand colours and spacing defined differently in design and code | Yes, directly | A named owner and one source of truth |
| Dark mode, high-contrast or density themes requested | Yes, this is their core job | Contrast checks on every theme, and design review of each |
| A rebrand or white-label deal is coming | Yes, they make it a small edit | Components that actually use the tokens |
| Several teams building the same component differently | Partly: they align values, not structure | Shared components and agreed API |
| Missing empty, error or loading states | No | Component design and a state checklist |
| Nobody owns decisions, so changes land unreviewed | No | A governance model |
| Interface feels confusing to users | No | Product design and research |
When you need them: now, later, not yet
Now if any of these is true: you have committed to dark mode, a second brand or a white-label offer; a rebrand is planned; you ship on more than one platform; or your engineers are already using AI tools to generate interface code from Figma. Each of these turns a design decision into something that must change in many places, or be read by a machine.
Later if you have one brand, one platform and one team, and the values mostly agree between design and code. Start by giving colour, spacing and type a clean set of Figma variables, and write semantic names even if you stop short of a full pipeline. That keeps the later move cheap.
Not yet if you have no shared components. Tokens applied to a product whose buttons are all built differently will not make it consistent. Fix the components first, or at the same time, and treat tokens as the layer that keeps them aligned.
A simple test: when someone asks to change the primary colour, does the answer take one edit or a search? If it takes a search, and you expect more than one such request this year, tokens are due.
What to ask your team
- Who owns token names? One named person or group approves additions and renames. Without this, names multiply.
- What is the source of truth? Figma variables, a token file in the repository, or a design tool synced to one. Pick one direction of change and write it down.
- How do Figma and code stay in sync? Ask what happens when a designer edits a variable on Monday. If the answer is a message in chat, you do not have sync yet. The tools are compared in our Figma and Storybook alignment roundup, so we leave the comparison there.
- Do component tokens exist, or only primitives? Primitives alone give you a palette, not theming.
- Are semantic names used in components, or raw values? Search the codebase for hardcoded colours as a quick audit.
- Which themes must work, and who checks contrast on each?
- What do AI tools see? If your team generates interface code with them, ask whether the tokens are exposed to the tool or whether it is guessing.
If you want a second opinion on the answers, our design system implementation work is where we help teams set this up.
Where the standard and Figma stand
For years every tool stored tokens its own way. On 28 October 2025 the W3C Design Tokens Community Group published its first stable specification, 2025.10, a vendor-neutral format developed by more than 20 editors and authors. Its announcement lists Figma, Penpot, Sketch, Framer and zeroheight among the tools supporting or implementing it, with Style Dictionary, Tokens Studio and Terrazzo as reference implementations.
The specification uses plain terms. A token is a name with a value and a type. A group is a container for organising tokens. An alias is a token whose value points at another token, which is how semantic and component tokens are expressed. Every token needs a type: set directly, inherited from its group, or, for an alias, taken from the token it points at.
On variables versus tokens: a Figma variable is a way to store a token inside Figma, and Figma presents variables as a way to implement design tokens. Figma's help centre documents importing variable modes from JSON files in the Design Tokens Community Group format, and separately lets you export modes as JSON. The import has limits: colours in HSL and sRGB only, dimensions in px, and no array font families. Check those limits against your tokens before relying on import, and check the exported file's format before assuming it matches the standard.
The practical point for a product lead: a stable, shared format means the file your tokens live in is less likely to trap you in one tool. It does not remove the need for the owner, the source of truth and the sync routine above.