Semantic vs. Primitive Design Tokens
Semantic tokens give meaning to raw values so components bind to intent, not hex codes. They let you rebrand or theme by changing aliases, not component code.
Why it exists
Design systems need to scale without leaking raw values into components. If every button hardcodes a hex code, a rebrand or dark mode requires touching hundreds of files. Primitive tokens store the raw palette and scale, while semantic tokens decouple the intent from the implementation, letting you change the underlying value in one place without rewriting component code.
The mental model
Think of primitives as the ingredients in a pantry and semantics as the recipe names. Flour and sugar are primitives; cake batter and bread dough are semantics. A recipe does not care which brand of flour you bought, only that it is the correct type. When the brand changes, the recipe still works.
How it works
Primitive tokens define the atomic values of your system. These are your colors at every shade, your type scale in fixed steps, your spacing increments, and your raw shadows. Semantic tokens reference those primitives to express purpose. For example, a primitive set might include --color-blue-500 and --color-red-500. A semantic layer would expose --color-text-link and --color-text-error, both pointing to primitives. In code, a button component uses --color-surface-primary, not --color-blue-500. If the brand shifts from blue to purple, you update the primitive reference inside the semantic token, and every button updates automatically without a single component file changing.
When to use it
Use primitive tokens when defining the base design language and global constants. Use semantic tokens inside components and layouts to express intent. Any system supporting multiple themes, brands, or modes should adopt semantic tokens. They are essential when the same primitive value must serve different roles in different contexts, such as a light gray used for both borders and disabled text but needing independent overrides later.
When not to use it
Avoid semantic tokens for one-off marketing pages or prototypes that will not evolve. Adding a full semantic layer too early creates indirection without benefit. Also, do not create semantic tokens that map one-to-one with primitives without meaningful abstraction, such as --color-red mapping only to --color-red-500, because that is just a longer name for the same thing and adds cognitive overhead.
One canonical example
A design system supports light and dark mode. The primitive palette includes --color-gray-100 through --color-gray-900. The semantic token --color-surface-default maps to --color-gray-100 in light mode and --color-gray-900 in dark mode. A card component references --color-surface-default. When the user toggles themes, the card background inverts automatically because the component is bound to meaning, not to a specific shade.
Interview question
How should a team rebrand a primary color from blue to purple without changing any component code when using semantic and primitive tokens?
- a.Update the semantic token alias to point to the purple primitive so components inherit the change automaticallyCorrect
- b.Remove the semantic layer and bind components directly to the new purple primitive
- c.Create a new purple semantic token and update each component to use it individually
- d.Replace the blue primitive token with purple inside every component file that references it
Why? this is the answer
Semantic tokens decouple intent from implementation, so updating the primitive reference inside the semantic token propagates the change to every bound component automatically. Option D is wrong because editing component files directly is the fragile approach that semantic tokens are designed to eliminate.
Just read this? Test yourself on what you have been reading.
Put your scrolling time to good use
Learn one idea, try a quiz and save useful cards for revision. Tezvyn makes it easy to learn and stay current in your tech field, a few minutes at a time.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on css — each one lists the topics its interview covers.
See open roles