Color naming for design systems: tokens that communicate intent

Naming is the invisible architecture of a color system. The names designers give to colors determine how the system scales, how it documents itself, and whether the team that inherits it can use it without reading a manual. Most color naming problems are not aesthetic — they are structural.

UI/UX Design Systems

Highlights

Avoid naming colors by their visual appearance at the primitive level (blue-500, #3B5FCA). Appearance names force context into the token name, which breaks when the theme changes. If 'blue-500' is used for primary actions and the brand pivots to a green palette, every token reference must be renamed. Semantic names — 'color-action-primary', 'color-surface-default' — remain valid regardless of the underlying hue.

The two-tier naming model (primitives + semantics) is now standard practice for good reason. Primitives define what the color is (blue-60, amber-30). Semantics define what the color does (action-primary, feedback-warning, surface-overlay). UI code references only semantic tokens. The mapping from semantic to primitive is the only place where palette decisions live — one edit there cascades correctly to the entire interface.

Scale naming (100–900 or 050–950) works only when the scale is linear in perceived lightness. Many teams generate a numeric scale from a design tool without checking whether the perceived brightness steps are even. An uneven scale makes it impossible to know which stop to reach for in a new context — you end up testing values until one works. Use a perceptually uniform color space (OKLCH or CIELAB) to generate your primitive scale, and the numeric naming becomes meaningful again.

The three layers of a color naming system

Most mature design systems separate color naming into three layers. Layer 1 — Raw values: the actual hex values, organized but unnamed beyond a reference index. Layer 2 — Primitives: named stops on a scale (brand-blue-60, neutral-gray-20). These exist in the token file but are not directly referenced in UI code. Layer 3 — Semantics: purpose-driven names (color-text-primary, color-border-interactive, color-feedback-error). UI code references only Layer 3. The separation means that changing the underlying hue of 'brand-blue' requires updating exactly one mapping, rather than finding every place in the codebase where 'blue-60' appears. Most naming system failures come from skipping Layer 2 or blending Layer 2 and Layer 3 into a single list.

Common naming failures and how to avoid them

Failure 1: Hue-specific primitive names that leak into semantics. 'color-blue-primary' is simultaneously a primitive and a semantic — it constrains the color (must be blue) while claiming to describe a function (primary). Fix: separate 'blue-60' (primitive) from 'action-primary' (semantic). Failure 2: Ordinal names without meaning. 'color-1, color-2, color-3' tells nothing about use or relationship. Anyone editing the system must read documentation rather than inferring from the name. Failure 3: Single-tier semantic names that don't compose. 'primary' and 'secondary' break when the system needs 'primary-hover', 'primary-disabled', 'primary-on-dark'. Plan the naming taxonomy before adding colors — the structure must accommodate states and contexts.

Naming conventions for dark mode and theming

Dark mode is a naming problem as much as it is a visual problem. If semantic token names embed light-mode assumptions — 'color-background-white', 'color-text-black' — the names become incorrect in dark mode. The fix is to name by role rather than by appearance: 'color-surface-default' is correct in both light and dark themes; 'color-background-white' is not. For theming beyond dark/light (brand themes, high-contrast modes), the semantic layer must be theme-agnostic. The pattern is: define a semantic token vocabulary first, then create multiple primitive-to-semantic mapping files — one per theme. The component code never changes; only the mapping changes. This is the only naming structure that scales to multiple themes without a full token audit each time.

Newer issue

Color in typography: how typeface color and palette work together

2027-03-18

Older issue

Color and wayfinding: spatial color for navigation and signage systems

2027-04-01