Practical color guide
Color Design Tokens: Naming CSS Variables for Scalable UI
Organize palette, semantic and component color tokens for CSS, design systems, themes and accessible interfaces.
Open related toolSeparate palette from meaning
Primitive tokens describe raw values such as blue-600 or gray-100. Semantic tokens describe intent such as action-primary, text-muted or status-danger. Components should consume semantic tokens so the palette can evolve safely.
Use a three-layer model
A scalable system can use primitive, semantic and component layers. Not every project needs all three, but the separation becomes valuable when several themes or products share one foundation.
- Primitive: --blue-600
- Semantic: --color-action-primary
- Component: --button-primary-background
Name roles, not appearances
A token named blue-button becomes misleading when the theme changes. A name such as action-primary communicates purpose and remains valid across light mode, dark mode and high-contrast themes.
Document state relationships
Specify default, hover, active, focus and disabled values together. Include contrast requirements and examples so developers do not invent new colors for every component.
Version tokens carefully
Add new semantic tokens before removing old ones, publish migration notes and test screenshots across themes. Token changes can affect many components even when the CSS diff is small.
Technical references
This guide was checked against the following primary references.
Frequently asked questions
What is a semantic color token?
It is a named value based on purpose, such as text-primary or status-success, rather than a specific visual color.
Should components use raw palette colors?
Prefer semantic tokens for product components. Raw palette tokens remain useful as the foundation and for controlled exceptions.