Primary references
These sources support the standards and technical explanations in this guide. Color Pick recommendations and product-specific limitations are identified separately in the article.
Web and UI
How to Build Color Design Tokens from One Brand Color
Turn one brand color into primitive, semantic, component, light-mode, dark-mode, and high-contrast color tokens without losing traceability.
Direct answer
Start with a perceptual primitive scale, preserve the canonical brand color as an explicit token, then map semantic roles such as canvas, text, border, action, focus, and status. Add component tokens only when a shared semantic role is not specific enough. Resolve every alias across light, dark, and high-contrast themes, then test the actual text, boundary, focus, and component-state combinations before export.
At a glance
Use three token layers with different responsibilities
A stable color system separates available colors, product meaning, and component implementation.
Primitive tokens describe the source scale without assigning product meaning. Semantic tokens describe roles such as text, canvas, border, primary action, focus, or danger. Component tokens narrow those roles to an explicit state such as a primary button hover background.
This separation makes theme changes and migrations easier to review because a component can inherit a semantic role instead of copying a raw HEX value.
| Layer | Example | Responsibility |
|---|---|---|
| Primitive | primitive.brand.600 | Canonical source color |
| Semantic | semantic.action.primary | Product intent |
| Component | component.button.primary.background | Explicit implementation state |
Generate a perceptual primitive scale
Build enough lightness range for backgrounds, borders, controls, text, and dark-mode adaptation.
- 1
Normalize the supplied brand color and preserve it as the canonical brand token.
- 2
Generate lighter and darker steps with a perceptual color model such as OKLCH.
- 3
Limit chroma at very light and very dark steps when the requested color leaves the display gamut.
- 4
Measure actual contrast for the combinations that will be used; do not assume a numeric shade name guarantees accessibility.
Map semantic roles before component details
Semantic roles let multiple components share intent across themes.
- Canvas, surface, and subtle backgrounds
- Primary, secondary, inverse, and disabled text
- Default and strong boundaries
- Primary action, hover, active, and on-primary content
- Focus-visible indicator
- Success, warning, danger, and informational status
Resolve aliases independently in every theme
A token path can keep the same name while its resolved value changes by context.
A dark theme should not be implemented by mechanically inverting every light value. Surfaces, text hierarchy, chroma, boundaries, focus indicators, and status colors need contextual review.
A resolver should expose missing aliases and circular references rather than silently replacing them. Token lineage makes it possible to trace a component value back to its semantic and primitive origin.
{
"component": {
"button": {
"primary": {
"background": { "$type": "color", "$value": "{semantic.action.primary}" }
}
}
}
}Validate constraints and component states
Test resolved pairings and state coverage, not isolated swatches.
| Area | Example evidence | Why it matters |
|---|---|---|
| Text | Label against button fill | Readable content |
| Boundary | Input border against canvas | Visible component edge |
| Focus | Focus ring against adjacent colors | Keyboard location |
| States | Default, hover, active, disabled, error | Complete interaction model |
| Aliases | Missing and circular references | Reliable build output |
Export a complete handoff pack
A useful export contains resolved values, source structure, theme context, and limitations.
Export source tokens for design-token tooling and resolved theme values for product implementation. Include version information, a migration note, and a project backup so future changes can be compared.
DTCG-based output improves interoperability, but teams must still validate the specific parser, resolver, build pipeline, and framework version used in production.
Put the guide into practice
Open Design System DoctorBuild a traceable color system
Generate themes, inspect token lineage, test constraints, repair failures, and export the complete token pack.
Frequently asked questions
Should semantic tokens contain raw HEX values?
They can, but aliases usually make ownership and theme changes easier to trace. Use a raw value when it is genuinely unique and document why it does not inherit from a primitive.
How many semantic color tokens should a system have?
There is no universal number. Use enough roles to express product meaning without creating multiple names for the same purpose. Track unused, duplicate, and overlapping roles as the system grows.
Can one token architecture support multiple brands?
Yes. Keep the semantic and component structure stable, replace the brand primitives, then independently audit each brand because the same role mapping can produce different contrast results.
Does OKLCH guarantee accessible colors?
No. OKLCH is useful for perceptual editing, but accessibility depends on the final rendered foreground and background combinations.