Semantic Naming for Design Tokens
Don't name a token by its value (blue-500); name it by its job (color.action.primary). This decouples design intent from implementation, making systems scalable. It's key for theming and avoiding "lie" variables when designs change.
Why it exists
Systems need a way to manage design decisions like color, spacing, and typography without hardcoding values. Hardcoding a hex code like #3B82F6 everywhere makes it impossible to update a brand's primary color or introduce a dark mode. Design tokens solve this by abstracting values behind a name.
The mental model
Think of a token's name as its job description, not its physical description. A name like blue-500 describes its appearance. A semantic name like color.interactive.primary describes its role. This decouples the design decision's purpose from its current value, allowing the value to change without breaking the contract of its name.
How it works
Design tokens are key-value pairs, typically in a JSON file, where the name is the key. A semantic name follows a predictable, hierarchical structure, often like category.property.variant.state. For example, color.background.surface.hover. This structure tells developers and tools exactly what the token is for. Theming is achieved by creating different token sets (e.g., light.json, dark.json) that define the same token names with different values. The application then just swaps which set is active.
When to use it
Semantic naming is essential for any system that needs to scale or adapt. Use it when building a design system, supporting multiple themes (like light and dark mode), or creating white-label products where brand styles can be swapped out. It enforces consistency and makes maintenance dramatically easier.
When not to use it
For a quick, one-off prototype, a simpler naming scheme might seem faster. However, this is a dangerous trade-off. Non-semantic names (card-background) quickly become tech debt as soon as a second type of card is introduced, forcing refactoring or creating confusing exceptions. It's almost always better to start with a semantic approach.
One canonical example
Consider a primary call-to-action button. A non-semantic token for its background might be brand-blue. A semantic token would be color.background.action.primary. If the brand's primary action color changes from blue to green, the brand-blue token name becomes a lie. The semantic name color.background.action.primary remains true to its purpose, regardless of whether its value is blue, green, or any other color. This makes the system resilient to change.
Interview question
What is the main benefit of using semantic naming for design tokens (e.g., color.background.action.primary) compared to value-based naming (e.g., blue-500)?
- a.It ensures the token's function remains clear and consistent even if its visual appearance changes.Correct
- b.It makes the design system easier to learn for new team members by using descriptive names.
- c.It reduces the overall number of design tokens required, simplifying system maintenance.
- d.It allows for direct conversion of tokens into specific CSS variables without additional processing.
Why? this is the answer
Semantic naming ensures a token's purpose (e.g., primary action color) remains valid even if its value changes (e.g., from blue to green), preventing 'lie' variables and making the system resilient to updates. While descriptive names can aid learning, the primary benefit is this decoupling of purpose from value for scalability.
Just read this? Test yourself on what you have been reading.
Read the original → docs.tokens.studio
- #design systems
- #design tokens
- #ui
- #css
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
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