Design Token Color Naming
Color token names are small decisions with long-term consequences. A good name helps people understand when to use a color and when not to use it.
Poor names force every developer to reinterpret the palette each time they build a component.
Purpose names
Purpose names describe the job: color-action-primary, color-text-muted, or color-status-warning. They work well when the product has stable UI roles.
These names help teams avoid using a warning color as ordinary decoration.
Scale names
Scale names describe the color family and step, such as blue-50, blue-500, and blue-900. They work well for systems that need many tints and shades.
The drawback is that scale names do not explain component purpose by themselves.
Hybrid approach
Many teams use scales as primitives and purpose tokens as aliases. The primitive stores the color ramp. The purpose token chooses which ramp step is used in the interface.
This gives flexibility without making every component depend on raw color steps.
--blue-500: #3B82F6;
--action-primary: var(--blue-500);Naming review
If a name is vague, ask where the color should appear. If the answer is unclear, the token may not be ready.
A smaller set of well-named tokens beats a large set of mysterious colors.
Who this guide is for
This guide is written for teams creating color token names that designers and developers can understand months later.
A token named blue-500 may be useful in a ramp, while a token named action-primary explains component purpose. Many systems need both levels.
The goal is to move past a quick definition and give the reader enough context to make a better color decision in an actual interface.
Detailed implementation example
Use primitives like --blue-500 and semantic aliases like --action-primary. Components use semantic aliases so the underlying ramp can change later.
A good token handoff includes name, value, role, related states, and examples of correct and incorrect use.
This kind of example matters because a color that looks correct in isolation can still create confusion when it is copied into code, reused in a new component, or placed beside other interface states.
Mistakes to avoid
Most color problems are not caused by one dramatic failure. They come from small decisions that are repeated across a site until the interface becomes harder to read, harder to maintain, or harder to trust.
Use the list below as a practical review before treating the color decision as finished.
- Using vague names like nice-blue.
- Naming shared tokens after one temporary component.
- Skipping usage notes for semantic tokens.
Step-by-step workflow
A repeatable workflow makes the result easier to review and easier to reproduce later. Instead of relying on memory or taste alone, move through the same checks each time.
Token naming audits should identify colors that have values but no clear usage rule.
- Create primitive color ramps.
- Create semantic aliases.
- Map aliases to component roles.
- Document allowed usage.
- Remove unused tokens.
Real page placement
After the first color decision is made, place it on at least three real page surfaces: a clean white or light surface, a tinted surface, and a dense content area with surrounding text. This exposes issues that do not appear in an isolated swatch preview.
For this topic, the placement test should use the same scenario described above: A token named blue-500 may be useful in a ramp, while a token named action-primary explains component purpose. Many systems need both levels.
If the color works only in the easiest example, keep adjusting. A production color should remain usable when the layout becomes smaller, when text length changes, and when neighboring components introduce other colors.
Maintenance plan
A color decision becomes more valuable when it is easy to maintain. Store the approved value where the team expects to find it, name it by purpose, and avoid leaving older one-off values in nearby files.
The maintenance note for this topic is: A good token handoff includes name, value, role, related states, and examples of correct and incorrect use.
During future redesigns, compare new proposals against this documented role. If the role still exists, update the token deliberately. If the role no longer exists, remove the color instead of letting it remain as unused design debt.
- Keep one source of truth for the approved value.
- Record the component roles where the color is allowed.
- Review nearby raw HEX, RGB, HSL, or utility values for drift.
- Remove unused colors when the page or component changes.
Reader exercise
To make the guide actionable, try applying it to a real color from your own project. Pick one component, write down the current color value, and decide whether the value is a source token, a computed browser output, or a temporary experiment.
Then run the workflow below and compare the result with the original choice. The point is not to change every color immediately. The point is to learn whether the current color has enough context to be reused safely.
When the exercise is complete, the color should have a role, a format, a contrast expectation, a state plan when relevant, and a place in the project's documentation or token layer.
- Create primitive color ramps.
- Create semantic aliases.
- Map aliases to component roles.
- Document allowed usage.
- Remove unused tokens.
Final decision criteria
Color names should reduce interpretation, not create a second layer of mystery.
For AdSense and search quality, this is also what separates a useful article from a thin glossary page. The article should answer the visitor's practical next question: what should I do with this color information now?
Before publishing, confirm that the article connects the concept to a real design or development action, includes enough context to avoid misuse, and points the reader toward a clear next step.
A strong article should leave the reader with a decision they can repeat. If the reader only learns a definition, the page is shallow. If the reader learns how to choose, test, document, and maintain the color, the page has practical value.