Token Aliasing: Theme by Role, Not Value
Token aliasing names a color by its job, not its hex, so you swap the underlying value per theme. One library supports light mode, dark mode, or multiple brands without code changes. The footgun is deep alias chains that hide which primitive value renders.
Why it exists
Hardcoding raw values like hex codes inside components makes theming brittle. If every button hardcodes blue, changing to a new brand or adding dark mode requires touching every file. Even primitive tokens like color-blue-500 fail because they describe appearance, not purpose. When the brand palette shifts, components break semantically because color-blue-500 might no longer mean primary action. Token aliasing was invented to separate what a color does from what it currently looks like.
The mental model
Think of a theater production. The script says the hero wears the protagonist coat. In one show, the wardrobe department maps protagonist coat to a leather jacket. In another city, it maps to a trench coat. The actor never changes the script; the role stays the same while the physical garment swaps. Token aliasing works the same way. Your component asks for the role, and the theme file decides which primitive value fills that role today.
How it works
A mature system uses at least two layers. The bottom layer holds primitive tokens, which are raw values like color-gray-900 or font-size-16. The middle layer holds semantic aliases, names like color-surface-primary or spacing-layout-lg, each pointing to a primitive. Components consume only semantic aliases. To create a theme, you publish an alternate mapping for the semantic layer. In dark mode, color-surface-primary might resolve to color-gray-900 instead of color-white. The component code stays identical; only the lookup table changes.
When to use it
Use token aliasing when you need to ship multiple visual identities from one codebase. This includes white-label SaaS products, design systems serving multiple sub-brands, and any application supporting light and dark modes. It also pays off when non-engineers like brand designers need to tweak the UI without editing React or CSS files, because they can adjust the alias map in a token file.
When not to use it
Skip it for a single-theme product with no rebrand on the horizon. The maintenance overhead of naming, documenting, and versioning aliases is not free. Also avoid aliasing when your team lacks governance. If anyone can create a new semantic token for a one-off button, you end up with thousands of aliases that overlap and contradict each other. Finally, do not chain aliases more than two or three levels deep. Each extra hop makes debugging harder because you must trace a graph instead of reading a single value.
One canonical example
Imagine a primary button. The component references the semantic token action-background-primary. In the default theme, that alias points to primitive color-blue-500. In a dark theme, the same alias points to color-blue-400 to maintain contrast. In a partner brand theme, it points to color-green-600. The button file never changes, the prop API stays the same, and QA knows that if the button background is wrong, the fix lives in exactly one theme mapping file rather than scattered across the component library.
Interview question
Why should components consume semantic aliases rather than primitive tokens directly?
- a.Semantic aliases reduce CSS bundle size by deduplicating raw color values at compile time.
- b.It allows the same component code to support multiple themes by changing only the alias mapping file.Correct
- c.Primitive tokens cannot represent dark mode values because they are statically defined at build time.
- d.Semantic aliases use plain English names that designers can edit without learning CSS syntax.
Why? this is the answer
Semantic aliases separate a color's purpose from its current value, so themes swap the underlying primitive by updating the mapping file without touching component code. Option D is tempting because the card notes non-engineers can edit token files, but that workflow benefit is secondary to the core architectural goal of themeability.
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 design-systems — each one lists the topics its interview covers.
See open roles