Your designer wants to make the brand blue a little darker. It sounds like a five-minute change. Then the developer asks which blue: the one in the palette, the one for links, or the one for the main button?
That question is what design tokens are about. A token gives a design decision a name, so the team can change it in one place and know where the change will show up. Understanding the two most common kinds, primitive and semantic tokens, helps you ask the right questions about a design change before you sign off on it. The three questions at the end of this guide work even if you never open a token file.
What a Design Token Is
Google’s Material Design describes design tokens as “small, reusable design decisions.” Each token has a name and a value. The value can be a color, a typeface, a size, or even another token.
For example, a website whose body text is 16 pixels can store that size once as a token. A raw-value token named font-size-16 holds the size itself. A second token named body-text-size says what the size is for and points to font-size-16. Every paragraph that uses body-text-size shows 16-pixel text. If the team later decides body text should be 18 pixels, it points body-text-size to font-size-18, and every paragraph using that token changes together. Headings and captions that use their own tokens stay as they were. The next sections name these two kinds of token.
The W3C Design Tokens Community Group publishes a shared format for tokens so different tools can exchange them. Its definition is plain: a token is information with a human-readable name, at minimum a name and a value. The report is a community group format, not an official W3C standard, and it does not tell teams how many levels of tokens to use.
Primitive Tokens Name the Options
A primitive token names a raw value with no stated purpose. Think of it as a labeled paint chip. A name such as blue-600 tells the team which shade it is, but not where to use it.
Material calls these reference tokens. Its published example is md.ref.palette.secondary90, which holds the color #E8DEF8. Reference tokens list the options available to the system. They do not change with light or dark mode.
Other teams say “base” or “core” tokens for the same idea. The name matters less than the job: this level answers “what values do we have?”
Semantic Tokens Name the Job
A semantic token names what a value is for. Instead of blue-600, the team uses a name such as action-background or text-link. That name points to a primitive token.
Material calls these system tokens. They assign a purpose to a reference token, and they can point to different reference tokens in light mode and dark mode. Apple’s guidelines follow a similar principle for system colors, which Apple says are defined by their purpose rather than their appearance or color values.
This level answers “what is this color for?” It is the level most reviews care about, because visitors experience roles, such as links and buttons, not palette shades.
Component Tokens Apply a Decision to One Part
Some systems add a third level for individual components. Material’s example is md.comp.fab.primary.container.color, which sets the container color of its floating action button.
Material says component tokens should point to a system or reference token whenever possible. That means a component can still follow the shared decisions above it. Components can also use semantic tokens directly.
One Change Followed Through Three Levels
Picture a small online furniture store with three tokens in a chain. This is an illustrative example, not a copy of any real system:
- Primitive:
blue-600holds a specific dark blue. - Semantic:
action-backgroundpoints toblue-600. - Component:
checkout-button-fillpoints toaction-background.
Now follow three different requests through the chain.
Change the primitive. If the designer edits the value of blue-600, everything that leads back to that shade can change. That includes buttons, but also anything else that uses blue-600 directly, such as an illustration or a chart. Before the change goes ahead, ask the designer where blue-600 is used.
Change the semantic token. If the team points action-background to green-600 instead, every main action that uses action-background changes color. Links and illustrations that use blue-600 for other reasons stay the same. This level fits a change meant for everything using that role.
Change the component token. If only checkout-button-fill changes, only the parts that use the checkout-button-fill token change. That suits a deliberate exception. It also creates a difference that someone has to remember, so ask why the button needs to differ from every other main action.
Real systems can have overrides and light and dark mappings that change this picture. So treat the chain as a way to ask good questions, not a promise of exactly what will move.
Tokens Work for More Than Color
Tokens can name type, spacing, corner shapes, and depth too. Material’s corner shape scale has ten named styles, from none to full. It notes that changing a shape style affects every component mapped to it, while remapping one component changes only that component.
That is the same global-versus-local choice as the color example. It also shows why a shape change can be bigger than it looks. Large corners can clip content in small, busy containers.
Some tokens do not map to one visual property. Material’s elevation tokens describe the distance between surfaces, and the platform decides how to draw it. So “change the shadow token” may not be the right request at all.
Why “Reference” Means Two Things
One word trips up even experienced teams. In Material, a reference token is a token that holds an option from the palette. In the W3C group’s format, a reference, also called an alias, is any token whose value points to another token.
So a Material system token can contain a reference in the W3C sense while not being a reference token in Material’s sense. If your team mixes these sources, agree which meaning you use in conversation.
How to Use This When You Review a Change
When someone proposes a design change, ask three questions:
- Which level is changing: the option, the job, or one component?
- What else uses that token, on which pages?
- Is this a new shared rule or a one-off exception, and who will remember it?
Then look at the pages where the change appears. Tokens describe intent. The pages show the result, including combinations nobody planned, such as a new button color on a promotional background.
Tokens will not tell you whether a color pairing reads well or whether a site has drifted from its palette. For that review, see our guide to reviewing your website’s color palette in use. For how tokens fit with components, patterns, and the rest, start with our guide to what is in a design system.
