A design token is a variable that stores a design value (a color, a spacing amount, a font size, or a corner radius) and is referenced by name everywhere that value is needed, instead of the raw value being typed in directly.
When values are typed in directly, a color like #0B5FFF appears in dozens of files. When the color needs to change, the code contains 40 copies of the same number. Finding all 40 requires a manual audit. Changing th
em requires 40 edits. Missing even one edit means the product now has two “primary action” colors, and which one is active depends on which file loaded first.
When values are named, the same color is stored once as color-action-primary: #0B5FFF, and every file refers to the name. Change the value once, and all 40 usages update automatically. The name is the contract. Everything that uses the name must accept whatever value the name currently holds.
The human parallel explains why names matter: you have an ID number that never changes and a name that stays stable while what it refers to changes. Everyone knows you as your name. When your hair changes, your name does not, and nobody has to update your contact card. A design token is the same structure. #0B5FFF is the ID number: exact and unchanging. color-action-primary is your name: stable, understood by everyone, and free to point at a different value when the time comes.
The scaling problem shows up because code does not naturally enforce names. A designer or engineer can copy #0B5FFF into a new file without asking permission. Nothing breaks. The file works. But the product now has two copies of the same color, and one of them will get out of sync the moment anyone changes a color without knowing about the other copy. At 10 teams, 40 products, or with an AI agent generating designs without human oversight, you go from one problem to dozens simultaneously.
Image note: diagram showing three states. Left: raw values in three files, each with a different color that should be the same. Center: the token system with one value. Right: after a change, the same token applied everywhere. Caption: Why names solve the scaling problem.
What Breaks at Scale Without Tokens
Unnamed values create four specific failure modes as a product grows, and each one costs differently.
1. Consistency drift with multiple teams. Two designers on different squads need the same color for the same semantic reason, but they receive the code as a hex value, not a name. They copy it into their files. Weeks later, someone decides the color needs adjusting for accessibility. They find and change one copy. The other copy is now orphaned, used by screens that look wrong but nobody can explain why. The product now has two “action primary” colors, and which one appears depends on which team built the screen.
2. Geometric multiplication with themes. The moment you add a second theme (dark mode, high contrast, or a client brand), every value needs a double. Without a naming system, you now maintain two separate lists: light colors and dark colors. A contrast change requires finding the pair. An update to a new contrast standard requires auditing both. The maintenance burden multiplies, not adds.
3. Acceleration breaks with AI design tools. A founder recently came to us with a product built partially with Google Gemini generating screens. The problem: Gemini had no constraint system, so every generated screen used different colors for visually identical elements. Three buttons on three screens could be three different shades of blue because nothing enforced that color-action-primary meant the same thing everywhere. The product looked inconsistent and unstable, even though functionally everything worked.
4. Inability to enforce intent. Without names, you cannot tell the difference between “this blue should be the action color” and “someone copied a blue hex value from somewhere.” The code looks the same. The rendering is identical. But one is a decision and one is an accident. That distinction matters the moment you need to change something and can’t tell which instances are intentional.
Atlassian documented this when moving onto tokens, stating that tokens simplify building for designers and engineers, improve accessibility, and enable theming. The order is important: theming is not a bonus feature you add after tokens are built. Theming is what tokens make possible.
The Three-Level Token System for Scalability
A token system that scales has three layers, each solving a different problem. This is the structure we built for the founder with the AI-generated design consistency problem.
Level 1: Primitive tokens store raw values with no meaning attached. Examples: blue-600, space-16, radius-4. These are the facts. They change rarely (only when the entire palette shifts) and are stored once for the whole system. Primitives are the foundation, but if a screen uses primitives directly, you still have the consistency problem. Nothing enforces that every blue-600 usage is actually for the same purpose.
Level 2: Semantic tokens attach meaning to primitive values and create a contract about intent. Examples: color-action-primary (what the user does), color-text-error (warning state), color-background-secondary (secondary information). Semantic tokens answer the question: “Why is this value here?” They map to primitives underneath: color-action-primary might currently reference blue-600, but if the action color needs to shift to blue-700 or even purple-500, only the semantic token needs updating. Screens use semantic names, so the change cascades everywhere that token is used.
Level 3: Component tokens are where scalability actually happens. They compose semantic tokens into reusable patterns: button-primary-background, button-primary-border, button-primary-text. A component token says “this is what a primary button looks like,” and it references semantic tokens underneath. When the action color changes, color-action-primary updates once, and every component token that references it updates automatically, and every screen using that component updates automatically. The propagation is automatic.
This three-level structure is what solved the Gemini problem. The founder had no naming system, so the AI saw only raw values and copied them without understanding intent. By adding semantic tokens, every color now had a meaning, and by adding component tokens, every visual pattern was defined once. Now when the AI generates a button or a form, it can reference button-primary and get all three colors correct automatically, because the three-level system enforces the relationship.
| Layer | Purpose | Example | Who uses it | Changes when |
| Primitives | The actual values | blue-600 | Semantic tokens reference this | You swap the entire palette (rare) |
| Semantic | Why you are using this value | color-action-primary | Screens and developers reference this | The design intent changes (sometimes) |
| Component | Complete patterns for reuse | button-primary | Designers and AI tools reference this | You need a new pattern (often) |
The component level is the one that prevents your product from looking chaotic as it scales. It says “a primary button always looks exactly like this,” and that definition sits in one place. Add 10 new designers, bring in an AI agent, or ship to a second team, and they all reference the same component tokens. No more color variation across the same element type.
Image note: three stack diagram showing primitives at the base, semantic tokens referencing them in the middle, and component tokens at the top referencing semantic. One arrow showing how a single primitive change flows up through all three levels.
How to Check Whether Your Product Has Tokens
You can find out without being able to read code, and it takes one conversation plus one test.
Ask your engineering lead three questions:
- If we change our brand blue tomorrow, how many files do you touch? One file means you have tokens. “I would need to check” means you do not.
- Could we ship dark mode without redesigning screens? If the answer involves redesign, values are not named.
- Could a client see this product in their own brand colors without us forking the code? This is the token question that shows up in your sales pipeline.
Then run the test. Atlassian documented a neat diagnostic while migrating: switch every token to a single color, and anything still showing its original color is a hardcoded value. Everything correctly using tokens turns that one color. Everything that does not stands out immediately.
In the naming analogy, this is the roll call. You call out one name, and whoever does not answer to it was never actually registered.
Image note: two product screenshots side by side. One normal, one with all tokens set to a single flat color, with the remaining unaffected elements circled.
What Tokens Cost, and Where Teams Overdo It
Tokens are not free, and the three-level system makes the cost structure explicit.
Primitives are cheap. Define your color palette, your spacing scale, your type sizes. One to two weeks for a new product. Update them rarely.
Semantics are where the real work sits. You have to decide what color-action-primary means, what color-text-secondary means, and which primitives they reference. For every color you have a primitive for, you may have three semantic tokens. For every semantic decision, you also decide: what happens to this in dark mode? In error states? In disabled states? Atlassian warned that their automated migration only suggested replacements, and humans still had to review. That is what semantic work looks like at scale. For a small product, this is two to three weeks. For an enterprise product, it is two to three months.
Component tokens are optional until they are not. A single product with one designer needs primitives and semantics. The moment you add a second designer, add AI code generation, or scale to multiple teams, you need component tokens, because component tokens are what prevent visual drift. They also require the most maintenance because they have to reflect actual component definitions in your code.
The overbuilding happens when teams build all three layers from day one without knowing whether they will need them. Do not define button-secondary-hover-disabled if you do not have five different button states. Do not create a component token taxonomy larger than your actual component library. The cost is in naming overhead that nobody uses.
Our approach: start with primitives and semantics. Add component tokens when you have real patterns to protect. For the founder with the Gemini problem, we built all three because the problem was uncontrolled visual variation across generated screens. That justified the upfront cost. If your product is one team and one theme, primitives and semantics are enough.
For the fundamentals underneath all of this, our guide to building a UI design system covers the layers that tokens sit at the bottom of.
FAQ
What are design tokens in simple terms?
Design tokens are names for the visual values in your product. Instead of a screen containing a raw color code, it refers to a name like color-action-primary, and the name points at the value. Change the value once and everything using that name updates automatically.
Are design tokens only for large companies No, but the payback scales with change. A single product with one brand and no dark mode gets modest benefit. A product with multiple themes, white label clients, or an upcoming rebrand gets most of its value back on the first change request.
Do design tokens require a design system?
No. Tokens stand alone. Start with primitives and semantics for palette consistency and theme management. Add component tokens only once you have patterns worth reusing, which usually arrives when a second designer or AI tool starts generating screens.
How long does it take to adopt design tokens?
For a single product, defining and applying tokens usually takes a few weeks rather than months. The variable is not the naming work, it is how many hardcoded values already sit in the code, and the single color test will tell you that before anyone commits to a timeline.
Is there a standard format for design tokens?
Yes. The Design Tokens Community Group published its first stable specification in October 2025. Tokens can now move between design tools and codebases in a single shared format, rather than needing a custom export built and maintained for each separate tool.
What is the difference between a design token and a variable?
A variable is the mechanism, a token is the agreement. Figma variables and CSS custom properties are places to store a named value. A token is that value plus a naming convention and a decision about where it may be used, which is what makes it useful across teams.
Conclusion
Naming things is the cheapest structural decision available to a product team, and it is the one most often skipped because nothing breaks immediately. What breaks later is your ability to change quickly: a rebrand that should take weeks, a dark mode launch that should be a setting, an enterprise client who wants your product in their colors and cannot be told yes.
If you are unsure where your product stands, you do not need a design audit to find out. Ask your engineering lead how many files change when the brand color changes, and run the single color test on your own product. Both answers arrive the same week, and they tell you whether your visual values have names or just numbers.
Let’s build with intent.
