Design Token Naming Conventions
Design token names encode meaning through a consistent, layered structure so values stay portable across themes and platforms. A clear convention like category-type-item-state turns scattered constants into a self-documenting, predictable system that…
Why it exists
As design systems grow, raw values like hex codes and pixel numbers scatter across code and design files, making global change risky. Naming conventions exist to give every design decision a stable, meaningful identity so it can be reused, themed, and refactored without hunting for magic numbers.
The mental model
Think of token names as a path from general to specific. A common pattern moves through tiers: a category like color or space, a semantic role like text or background, an optional component or item, and finally a variant or state like primary, hover, or disabled. The name describes intent, answering what is this for rather than what does it look like.
How it works
Tokens are usually layered. Primitive or global tokens hold raw values, such as a palette of greys and blues. Semantic or alias tokens point at primitives and carry meaning, like color-text-default referencing grey-900. Component tokens reference semantics, like button-background-primary. A build tool then transforms this structured naming into CSS variables, iOS, or Android outputs. Because names are consistent, transformation and theming become mechanical.
When it matters
Naming discipline pays off at scale: multi-brand theming, dark mode, multiple platforms, and large teams. It matters most when you need to change a value everywhere at once or when new contributors must understand intent without reading docs. For a tiny single-theme site, lighter conventions are fine.
A concrete example
Instead of writing color blue-500 directly on a button, you define a primitive color-blue-500, a semantic color-action-default that aliases it, and a component token button-bg-primary that aliases the semantic one. To launch a new brand, you only repoint the semantic layer; primitives and component names stay untouched, and every button updates automatically.
Interview question
Why is a semantic token name like color-text-primary preferred over a literal name like blue-500 for component usage?
- a.Semantic names always use fewer characters
- b.Semantic names describe intent and survive theme or brand changesCorrect
- c.Literal names cannot be used as CSS variables
- d.Literal names compile faster in CSS
Why? this is the answer
Semantic names encode purpose, so rebranding or switching themes means repointing one alias rather than editing every usage. Literal names tie code to a specific value and break when the palette changes.
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-tokens — each one lists the topics its interview covers.
See open roles