Token: The Named Design Decisions That Keep a Product Consistent
A design token is a named value, such as a color or spacing amount, so one change updates every screen that uses it.
In short
A design token is a named value, such as a color or spacing amount, that stores one design decision, so one change updates every screen that uses it.
10 min readFree
What you will learn
Every product is made of small decisions. A button is one shade of orange. A heading has a certain size. Two cards have a gap between them. In a design system, these decisions are not typed in again and again on every screen. They are stored once, given a name, and reused. That stored, named decision is called a token.
In this lesson you will learn what a token is, why teams name tokens instead of copying raw values, how tokens are sorted into layers, and how one token change can update a whole app. You will also follow one checkout button step by step.
The words below come up often. Read them first, then keep going.
Key words
- Design token
- A named value that stores one design decision, such as a color, a font size, or an amount of space.
- Raw value
- The plain value itself, such as a hex code like #1A1A1A. It tells you the value but not why it was chosen.
- Hex value
- A way of writing a color as a code: a # sign followed by letters or numbers.
- Primitive token
- A base token that holds a raw value, such as blue-500. Also called a global token.
- Semantic token
- A token named for its job, such as color-action-primary. Also called an alias token.
- Component token
- A token for one part of one specific component, such as the background of a primary button.
- Alias
- A token that points to another token instead of holding its own value.
- Theme
- A named set of token values that gives the product one look, such as light mode or dark mode.
What is a token?
A design token is a named value that stores one design decision. The decision might be a color, a font size, or an amount of space. Designers and developers both use the name instead of the raw value. If the value changes in one place, every screen that uses that name changes too.
A token has two parts. The name says what the decision is for. The value says what it is right now. Imagine a text color written as #1A1A1A on every screen. The hex code tells you the color, but nothing about its purpose. If the same color is stored as color-text-primary, the name explains the purpose. The value can then change later without forcing a rewrite of every screen that uses it.
Why do names beat raw values?
Names explain purpose
A name such as color-text-primary says where the color belongs. A bare code only says what the color looks like.
Values can change safely
Screens point to the name, so the team can change the value once. Nobody has to search for the old code across the whole product.
One shared word
A designer who picks color-text-primary in a design file and a developer who uses the same name in the product are talking about the same decision.
Tip
Name tokens by their job, not by how they look. A name like color-blue-500 describes appearance. If the brand later moves away from blue, that name becomes misleading. A name like color-action-primary still makes sense after the change.
What are the three layers of tokens?
Most systems do not keep every token in one flat list. They sort tokens into layers, and each layer does one job. Because of this, a change usually touches one layer and leaves the others alone. Many teams describe three layers. The first holds raw values. The second gives those values a purpose. The third connects a purpose to one part of one component.
Primitive tokens
Primitive tokens are the raw palette. They hold every color, size, and spacing step that the product allows. An example is blue-500. The name tells you it is a shade of blue, but not where it is used. Primitives are the base material. Designers rarely place a primitive directly on a screen.
Semantic tokens
Semantic tokens point to a primitive and describe how the value is used. color-action-primary is one example. It points to a primitive value, and its name says it is meant for main actions. Semantic tokens are the names most people use day to day. They also make theming possible, because the same name can point to different primitives in different themes.
Component tokens
Component tokens are the most specific layer. They describe one part of one component, such as the background of a primary button or its color when a mouse hovers over it. A component token usually points to a semantic token. Teams add this layer only when one component must change on its own. Small products often skip it.
Which way do the links point?
Think of the chain as component, then semantic, then primitive. A component can point to a semantic token, and that semantic token points to a primitive. A component should not skip the middle layer and point straight to a primitive. If it did, it would lose the meaning the middle layer adds, and a later change would be harder to make safely.
How do the layers connect?
- 1
Store the raw value
Keep each approved value once, as a primitive. For example, store one orange as orange-500.
- 2
Give it a job
Create a semantic token, such as color-action-primary, that points to that primitive.
- 3
Add a component token only when needed
If one component must differ from the rest, create a component token that points to the semantic token.
- 4
Use names in screens
Designers pick semantic tokens in their design files, not raw codes. Developers read the same names when they build the product.
How do you keep design and code in sync?
A token gives designers and developers one shared source. When a designer picks color-action-primary, the developer building that screen uses the same name. When the team changes the value later, both sides see the update from the same place, instead of comparing notes or copying new codes by hand.
Tokens also travel between tools. The format lets different tools read the same token file. It is a community group report, not an official W3C standard, and tools are progressively adopting it.
Tip
You do not need to write a token file to understand tokens. The key idea is simple: one named decision, stored once, and read by many tools and people.
Worked example: the checkout button
This example is an illustration built to show the idea. It imagines a food delivery app with a checkout screen. The screen has a Place Order button. Follow one token from the button back to its raw value.
- 1
Find the token on the button
The Place Order button's background uses the semantic token color-action-primary. A designer chose this name in the design file. No hex code was typed in.
- 2
Follow the alias
color-action-primary points to the primitive orange-500. The semantic token adds the meaning 'main action' on top of a plain orange.
- 3
See who else uses it
Other primary buttons in the app, such as the ones on the cart and address screens, use the same token. They all share one definition.
- 4
Rebrand with one edit
The company picks a new brand orange. The team changes the value of orange-500 once. Every primary button that uses the token updates, and no screen needs to be opened.
- 5
Add a dark theme
For dark mode, the team maps color-action-primary to a lighter orange primitive from the same palette. The checkout screen keeps the same name. Only the mapping changed.
Tip
Spectrum, Adobe's design system, uses the same chain. A base blue token is aliased first into an accent color and then into a content color. That final token is shown in use for radio and checkbox labels, a toggle label, a hyperlink, and a menu checkmark.
Check your understanding
Quick check
Your company is moving its brand from blue to green. Your app has 400 screens where buttons, links, and icons all use hard-coded hex values. Which change is the best way to do the work?
Changing a whole product at once
Rebranding
A new brand color is one edit to a primitive value, or one new mapping for a semantic token. The screens keep their names and their layout.
Dark mode
A dark mode maps the same semantic names to different primitives. A page background can point to a dark gray instead of a white, and every screen that uses that name follows.
Theming
A theme is a named set of token values. A product can offer a few themes, and each one changes only the values, not the structure of the screens.
Notice what stays fixed. The screen layouts, the component structure, and the semantic names remain the same. Only the values behind the names change.
What do tokens not do?
Tokens store decisions. They do not make those decisions for you. Choosing a color palette, a type scale, or a spacing system is covered in other lessons. So are the rules for who approves a change. A token also does not build a button. It names the values a button uses, and the button itself is a component made from parts and rules.
Using raw values in screens
If a screen uses a raw code instead of a token, a later change will miss that screen. Use the semantic token instead.
Naming by appearance
A name such as blue-button-color becomes wrong after a redesign. Name tokens by purpose so they stay true when the look changes.
Too many component tokens
Each component token adds to the total count. Add them only when a part must change on its own.
Key takeaways
A token is a named design decision with a value. Tokens sit in three layers. Primitive tokens hold raw values, semantic tokens give those values a purpose, and component tokens connect a purpose to one part of one component. Because screens use names, one edit updates every place that uses the name. That is why rebranding, dark mode, and theming become faster when a product uses tokens.
Final check
Quick check
A team has a card component that uses the semantic token surface-default. That token points to the primitive white-100. The team adds a dark theme and wants cards to turn dark gray there, while light mode stays white. What should they change?
Sources
- Adobe Spectrum, Design tokens
- UAL Design System, Design Tokens
- Penpot, The developer's guide to design tokens and CSS variables
- Eule Institute, What Are Design Tokens? Types and Examples
- Osam Design, Design Tokens and Variables, Explained
- Midrocket, Design tokens: what they are and how to use them
- Pegasus Design System, What are design tokens? A practical reference
- Design Agent, Primitive vs Semantic Tokens: When to Use What
- Contentful, Design tokens explained: How to build a design token system
- Sujeet Jaiswal, Design Tokens and Theming Architecture
- W3C Design Tokens Community Group, Design Tokens Format Module 2025.10
- Mateus Villain, The Ultimate Guide to Design Tokens: Formats, Types and Specifications
Last updated on 17 November 2026
Related lessons
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.