Skip to content
ColorArchive
Design Systems Guide
Search intent: design token color naming system

Design Token Color Naming: A System That Scales

How to name color tokens in a design system that survives rebranding, dark mode, and team growth. Covers primitive vs semantic naming, common mistakes, and the two-tier structure that most successful systems use.

Design SystemsUI/UXBrand
Key points
Primitive color tokens define what a color is (blue-60, amber-30). Semantic tokens define what it does (action-primary, surface-default). UI code should only reference semantic tokens — this means a complete rebrand changes one mapping file, not hundreds of component references.
Avoid hue-specific names in semantic tokens. 'color-blue-primary' locks the primary action color to blue, which breaks if the brand changes hue. 'color-action-primary' is theme-agnostic and equally valid in a green or violet rebrand.
Plan for states before naming anything. A semantic token named 'action-primary' must eventually accommodate 'action-primary-hover', 'action-primary-disabled', 'action-primary-on-dark'. If your naming taxonomy doesn't accommodate compound names from the start, you'll rename tokens mid-project.

The two-tier naming model: primitives and semantics

The two-tier model is the current standard for scalable color systems. Tier 1 — Primitives: named stops on a perceptually even scale (brand-blue-10 through brand-blue-90, neutral-0 through neutral-100). These exist in the token dictionary but are not directly referenced in component code. Tier 2 — Semantics: purpose-driven names that map to primitives (color-text-primary maps to neutral-90, color-action-primary maps to brand-blue-60). Components reference only semantic tokens. A rebrand or theme change updates only the primitive-to-semantic mapping — all component code remains unchanged. The key discipline: never let component code reference a primitive. If it does, the two-tier model degrades to a one-tier system and loses its main advantage.

Naming conventions for dark mode and multi-theme systems

Dark mode naming fails when semantic tokens embed appearance assumptions. 'color-background-white' is incorrect in dark mode; 'color-surface-default' is correct in both. The rule: name by role and context, never by appearance. For theming beyond light/dark, the semantic token vocabulary must be theme-agnostic — it defines the structural relationships (primary action, default surface, interactive border) without specifying the color that satisfies those roles. The primitive-to-semantic mapping files — one per theme — resolve the structural names to actual values. Components never change; themes are swapped by loading a different mapping.

Common naming mistakes and how to fix them

Mistake 1: Hue names leaking into semantics ('color-blue-cta'). Fix: split into primitive (blue-60) and semantic (action-cta). Mistake 2: Ordinal names without meaning ('color-1', 'color-2'). Fix: use semantic role names even in small systems — the documentation overhead of 'primary, secondary, tertiary' is lower than the cognitive overhead of numbered aliases. Mistake 3: Flat naming with no category structure ('primary, secondary, accent, muted'). Fix: namespace by category ('text-primary', 'surface-secondary', 'border-accent') so the system remains navigable as it grows past 20 tokens. Mistake 4: Not planning for states ('action-primary' with no hover, focus, disabled variants). Fix: define the full state vocabulary before assigning primitive values, so the taxonomy is consistent from the first token.

Practical next step

Move from the guide into a concrete palette lane

Guides explain the use case. Collections prove the taste. Packs handle the export and implementation layer.

Browse packsMore guides
Related guides
Design Systems
How to Build a Tints and Shades Color Scale for Any Brand Color
A complete guide to generating tonal color scales for design systems. Learn the difference between tints, shades, and tones, the WCAG contrast requirements for each step, and how to choose the right scale for your brand.
Web Design Guide
Color Palette for Apps: Building a System That Scales
App color systems are more complex than brand color palettes. An app needs colors for every state, every component, and both light and dark modes — from a starting point of three or four brand colors. Here is how to architect that expansion correctly.
Web Design Guide
Color Palette for Apps: Building a System That Scales
App color systems are more complex than brand color palettes. An app needs colors for every state, every component, and both light and dark modes — from a starting point of three or four brand colors. Here is how to architect that expansion correctly.