How to Build a Practical UI Color System

Design tokens and a thoughtful color system form the foundation of consistent, accessible user interfaces. A robust color system saves design time, reduces visual bugs, and makes it straightforward for developers to implement themes and variants. This guide walks through a practical, step-by-step approach you can apply whether you're working on a single product or a multi-brand design system.

1. Define token categories and roles

Start by grouping colors by purpose, not by hex values. Typical categories include:

• Brand tokens: primary, secondary, accent — the colors that express visual identity.
• Semantic tokens: success, warning, error, info — used for UI states and messages.
• Neutral tokens: background, surface, border, text — used for layouts and surfaces.
• Interactive tokens: focus, hover, pressed — stateful variants tied to interactions.

2. Choose naming conventions

Prefer semantic names over raw color names. Semantic tokens make your intent clear and make theming easier. Examples:

:root {
	--color-primary: #6A11CB;
	--color-primary-700: #5010a0;
	--color-surface: #ffffff;
	--color-text: #111827;
	--color-success: #16a34a;
}

For neutral scales, use numeric scales that represent light → dark (e.g., --neutral-50 to --neutral-900). This is easier to reason about than arbitrary hex names like ivory or charcoal.

3. Build accessible variants

Accessibility must be a first-class concern. For each token used for text or important UI elements, provide contrast-safe variants. Use tools to compute contrast ratios and include alternate tokens for dark/light surfaces.

• Detect contrast failures during design reviews and CI checks.
• Provide --color-text-on-primary tokens so components don't need to compute contrasting colors dynamically.

4. Theming strategies

There are two common theming strategies:

1. Swap variable sets: Provide a --theme-dark and --theme-light set and switch them at runtime by toggling a top-level class or attribute.
2. Map semantic tokens: Keep the same semantic tokens and map them to brand values per product or brand. This makes component styles resistant to theme changes.

Runtime performance is excellent when using CSS variables because the browser handles repaint efficiently. Avoid recomputing colors in JavaScript where possible.

5. Implementation examples

Practical examples help teams adopt the system. Here's a compact CSS approach and a small JavaScript helper to toggle themes.

:root {
	--color-primary: #6A11CB;
	--color-surface: #ffffff;
	--color-text: #111827;
}
.theme-dark {
	--color-surface: #0b1220;
	--color-text: #e6eef8;
}

function toggleTheme(isDark){
	document.documentElement.classList.toggle('theme-dark', isDark);
	localStorage.setItem('prefers-dark', isDark ? '1' : '0');
}

6. Token lifecycle and governance

Treat tokens like an API. Keep a changelog, document intended uses, and freeze tokens that are widely adopted. Provide migration guides when removing or renaming tokens to avoid visual regressions.

7. Automation and CI checks

Include automated checks to ensure tokens meet contrast thresholds and that there are no unused tokens. A simple Node script can parse CSS or JSON token files and compute contrast ratios for each token pair used for text on backgrounds.

8. Practical rollout steps

1. Audit current product colors and map them to semantic roles.
2. Create a minimal token set and implement it in one component library.
3. Publish tokens as a versioned package or shared file for other teams.
4. Run visual QA and automated contrast checks before a broad rollout.

Conclusion

A practical UI color system makes design and engineering faster while improving visual harmony and accessibility. Start with semantic tokens, keep accessibility non-negotiable, and provide clear governance to scale the system across products.

Back to Blog