Defining Design Tokens: Named Design Decisions Shared by Designers and Builders
Learn how a design system turns colors, spacing and other visual choices into named values, so one change updates every screen that uses them.
In short
Design tokens turn colors, spacing and other visual choices into named values shared by designers and builders, so one change updates every screen that uses them.
13 min readFree
What You Will Learn
This lesson explains how a design system turns its visual decisions into design tokens. A decision might be which blue a team uses for links, or how much space sits between two items. A token gives that decision one name and one stored value. By the end, you will know what a token is, how tokens are sorted into layers, and how a team can start with a small first set. The idea is simple, but it changes how fast a whole product can be updated, so take your time with it.
Key words
- Design system
- A shared set of parts, rules and decisions that a product team uses so its screens look and behave alike.
- Design decision
- A choice about how something looks or works, such as the color of a button or the gap between two cards.
- Design token
- A named value that stores one design decision. The name says what the value is for.
- Hard-coded value
- A raw value typed directly into a screen or file, instead of pointing to a shared name.
- Hex code
- A way of writing a color as a # sign followed by six letters or numbers, such as #2E7D32.
- Primitive token
- A base value in the palette, such as a specific green. It has a value but no job yet.
- Semantic token
- A token named for its job, such as the color used for main actions. It points to a primitive token. It is also called an alias token.
- Component token
- A token tied to one part of the product, such as the fill of a button.
- Single source of truth
- One official place where each value is recorded, so every person reads the same answer.
- Theming
- Changing the look of a product by changing which values the names point to, for example when a brand gets a new color.
What Is a Design Token?
A design token is a named value that stores one design decision. Instead of writing a color as a code, a team gives the color a name that explains its purpose. For example, a team might record its main brand blue as color-brand-primary, with the value #1A73E8. When a screen needs that blue, it asks for the name. It does not carry the code around with it.
Tokens are not only for color. Tokens can cover any style choice, including spacing, type sizes, corner roundness and shadows. The token idea is the same in every case: one decision, one name, one stored value.
The name
The name says what the decision is for, such as color-brand-primary. A good name lets a new team member guess the job without asking.
The value
The value is the actual setting, such as a hex code, a number of pixels or a font size. This is the only place the setting has to be typed.
The purpose
The purpose is a short note about where the token should and should not be used. It stops people from picking a color just because it looks right.
Tokens also help people from different jobs speak the same language. The W3C Design Tokens Community Group publishes a file format for exchanging design tokens between tools.
Tip
The W3C group publishes a file format for passing tokens between tools. It is a community group report, not an official W3C standard. This lesson is about the idea of tokens, not about any file format. You do not need to write files to understand tokens.
Why Do Hard-Coded Values Cause Trouble?
Imagine a designer types the hex code #2E7D32 straight into a button's fill. Another designer copies that code into a link, a selected tab and an icon. Soon the same green sits in dozens of places across a product. Each copy is a separate fact that someone must remember to update. If the brand changes, the team must search every file, and any copy that is missed keeps the old color. Teams often call this kind of value hard-coded, because it is fixed in place and not connected to anything else.
A token fixes this by giving the team one place to store the value. Several sources describe this as a single source of truth. Every screen then points at the name, so the value lives in one spot and can be checked, changed and reviewed there.
Tip
A quick test: if you can change a color in one place and see it update on every screen, you are using tokens. If you have to open many files to change it, the values are probably hard-coded.
How Are Tokens Layered?
Most design systems do not keep all tokens in one flat list. They sort them into layers, usually three: primitive tokens, semantic tokens and component tokens. Each layer answers a different question. The primitive layer asks what values exist. The semantic layer asks what each value is for. The component layer asks where a value is used in one specific part of the product.
The names change from team to team. The idea behind each layer stays the same, so learn the idea first and the labels second.
Primitive Tokens: The Raw Palette
Primitive tokens are the raw building blocks. They hold every color, size and spacing step a team allows itself to use. A primitive might be called green-700 and hold one specific green. On its own, green-700 says nothing about what the green is for. It is like a paint tin on a shelf. It holds a color, but it does not tell you which wall to paint.
Because primitives have no job attached, designers should not usually place them directly on screens. A primitive is the source the rest of the system draws from.
Semantic Tokens: Naming the Job
Semantic tokens give a value a job. A semantic token might be called color-action-primary, meaning the color for the main action on a screen. It does not hold a color itself. It points to a primitive, such as green-700. The semantic token is the name a designer picks on a screen, and the primitive is the value behind it.
This pointing is the key idea. When the semantic token points to a primitive, changing the primitive changes every screen that uses the semantic name. Some systems also use the same semantic name for different themes, so the name points to one primitive in the light theme and another in the dark theme.
Component Tokens: Tuning One Part
Component tokens tie a semantic value to one specific part of the product, such as the background of a button. A component token might be called button-background and point to color-action-primary. It lets a team change one component without touching the shared meaning used everywhere else.
Component tokens are optional. Small products often do well with only primitive and semantic tokens. A team adds component tokens when one component needs its own setting, for example when a brand wants a single button to use a different green.
Tip
Keep the direction of pointing clear. A component token points to a semantic token, and a semantic token points to a primitive. Screens should use the semantic or component name, not the raw primitive. This keeps the meaning and the flexibility.
Why Does the Semantic Layer Make Change Easier?
The semantic layer sits in the middle for a reason. Designers pick names from it, and developers use the same names when they build. The primitive behind a name can change without anyone touching the screens. That is why this layer is the one that makes updates and theming manageable.
Think about a dark mode. A semantic token called surface can point to a light gray primitive in the light theme and a dark gray primitive in the dark theme. Every screen that uses surface then updates together, and no one edits each screen by hand. A brand change works the same way: re-point the semantic name, or change the primitive it points to, and the whole product follows.
The layers also limit damage. A change to one component token affects only that component. A change to a primitive affects everything that points to it, which is why primitive changes should be reviewed with care.
Worked Example: The Place Order Button
Here is a worked example. The app is a food-delivery product, and the screen is its checkout. The green Place order button has its fill hard-coded as #2E7D32. The team wants to move the button to tokens, so a future rebrand is one edit rather than a hunt across dozens of screens. Follow the steps.
- 1
Find the raw value
Open the checkout button and note its fill, which is the hard-coded hex code #2E7D32. Check whether other screens use the same green. Here they do, which is a sign that the value should become a shared token.
- 2
Record the primitive
Add the green to the palette as a primitive token called green-700. Record its value as #2E7D32 and a short note that it is a green from the palette. The primitive holds the value, but it still has no job.
- 3
Create the semantic token
Create a semantic token called color-action-primary. Point it at green-700. Write its purpose: the main color for the most important action on a screen, such as Place order.
- 4
Swap the fill
On the checkout button, replace the hard-coded hex code with color-action-primary. The button looks the same as before, because the name still resolves to the same green.
- 5
Rebrand in one edit
When the brand moves to a new green, change the value of green-700 in one place. Every element that uses color-action-primary updates, including the Place order button on checkout and the same action on other screens. No one has to open each screen.
Tip
The example shows the main benefit. The screen never needed to know the green's code. It needed to know the job the green does, and that job can keep its name while the value changes.
How Do You Define a First Small Token Set?
A team does not need hundreds of tokens on day one. Sources that describe token systems say component tokens are optional, and small products can often skip them. A first set should be small, clear and easy to check. The steps below show a simple way to start.
- 1
Choose the categories
Pick a few groups to begin with, such as color, spacing, type size and corner roundness. Keep the list short. You can add more later once the first set is in use.
- 2
Assign the values
For each category, list the values the product already uses. Keep only the ones that matter, and drop near-duplicates, such as two greens that differ by a tiny amount. Give each kept value a primitive name.
- 3
Record each token
Write every token into one single source of truth. For each token, record its name, its value and its purpose. A shared spreadsheet or a shared token file both work, as long as there is one agreed place that everyone checks.
- 4
Create the meaning layer
Add semantic tokens for the main jobs, such as action color, text color and surface color. Each one points to a primitive, and each one has a purpose note.
- 5
Check every value in use
Review the designs and find every color and spacing value in use. Each one should map to a token. Any value with no match is either a missing token or a value that should be removed. Write these gaps down and fix them one by one.
Tip
The last step is the one teams skip most often. Without it, hard-coded values slowly come back. Make the check a regular habit, not a one-time task.
Tip
Names matter, but how to choose them in depth is a topic for its own lesson. For now, use short, consistent names such as color-action-primary, and change them only when a team agrees.
Check Your Understanding
Try the scenarios below. Each one asks you to use the idea of tokens, not just repeat a definition.
Quick check
Your product uses the same blue for text links, primary buttons and selected tabs. Each blue was typed in as a hex code in the design files. The brand is now moving to purple. Which naming choice, made by defining tokens first, lets the team make this change in one place?
Now a second scenario. The checkout screen uses the same primary green as every other action on the product. The brand team wants only the Buy button on one special screen to use a slightly different green. The other buttons must stay as they are.
Quick check
Which approach fits this request best?
A last scenario. A designer is building a new onboarding screen and finds the hex code #2E7D32 in a file. Nobody remembers whether it is the same green as checkout.
Quick check
What is the best next step for the designer?
Summary
A design token is a named value that stores one design decision. Tokens sit in layers: primitives hold the raw values, semantic tokens name their job and point to primitives, and component tokens tune one part of the product when needed. The semantic layer is what makes updates and theming manageable, because a change in one place reaches every screen that uses the name. A good first set is small, has clear purposes and lives in one source of truth.
Sources
- W3C Design Tokens Community Group, Design Tokens Format Module 2025.10
- UAL Design System: Design tokens
- Pegasus Design System: What are design tokens? A practical reference
- Osam Design: Design Tokens and Variables, Explained
- EULE Institute: What Are Design Tokens? Types & Examples
- Tokens Studio documentation: Intro to Design Tokens
- Contentful: Design tokens explained, how to build a design token system
- Design Bootcamp (Medium): Design Tokens, The Foundation of Scalable Design Systems
- Design at ExxonMobil (Medium): Design tokens, unified approach to design system implementation
- Snapflow: Design Tokens, What They Are, the Standard, and How They Reach Code
- We Inc.: Design Tokens Explained with Examples
Last updated on 17 November 2026
Related lessons
- Design systemsToken: The Named Design Decisions That Keep a Product Consistent
- Design systemsDesign Editor: Set Up One Shared Design System File Your Team Can Trust
- Design systemsCreating Design Language: Turn Shared Look, Feel, and Behavior Into Clear Choices
- Design systemsDesign Principles: Short Statements That Settle Design Trade-Offs
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.