Color Naming for Design Systems: Why Your System Breaks Down and How to Fix It

Design system color naming is one of the most consequential and least discussed decisions in product design. The naming system you choose determines how well the system scales, how accurately designers communicate intent, and how long the system remains coherent as products expand. A review of the three primary naming strategies, their failure modes, and the hybrid approach that most durable systems use.

Design Systems Color Naming UI Color

Highlights

Descriptive naming (Blue-500, Red-200, Gray-100) is the most common and most brittle naming strategy. It encodes color in the name itself — which means any rebrand or palette update requires renaming every token and every reference in code. When the brand evolves from blue to indigo, 'Blue-500' is now either a lie or a migration project. Descriptive names also leak implementation into the semantic layer: 'Blue-500' tells the consumer what the color is, not what it means or where to use it.

Semantic naming (Primary, Secondary, Destructive, Surface, Muted) solves the rebrand problem and the intent problem simultaneously. The name encodes purpose: Primary is always the brand's primary action color, whatever that color happens to be at any point in the brand lifecycle. The failure mode: semantic names become overloaded when a system has many components. 'Primary' eventually conflicts — primary text? primary surface? primary button? primary icon? The solution is hierarchical semantic naming: tier-one semantic names for the most stable roles, component-scoped semantic names for complex components.

Functional naming (Action, Background, Border, Text, Icon) addresses component structure rather than brand role or hue. These names age extremely well because they describe UI function — even as the product scales, 'Action' is always the color of interactive elements and 'Border' is always the color of dividing lines. The weakness: functional names do not communicate tone. 'Action-Strong' versus 'Action-Subtle' is clear enough, but 'Action-Strong-Brand' versus 'Action-Strong-Destructive' starts to feel verbose. The tradeoff between clarity and verbosity defines the practical ceiling for functional naming systems.

The hybrid naming architecture used by mature design systems

Figma's and GitHub's mature color systems use a three-tier hierarchy: (1) Primitive tokens — numeric or descriptive names that map to specific color values (Blue-500, Gray-100). These are never used directly in component design; they exist as the raw material for the semantic layer. (2) Semantic tokens — functional or role-based names (Text-Primary, Surface-Raised, Border-Subtle) that reference primitives. These are what designers and developers use directly. (3) Component tokens — component-specific overrides (Button-Background-Default, Input-Border-Focus) that reference semantic tokens or primitives directly. The key insight: each tier can evolve independently. Primitives can be recalibrated without changing semantic names; semantic tokens can be remapped to different primitives without changing component implementations.

Dark mode as the stress test for naming quality

Dark mode is the definitive stress test for color naming systems. If your system uses descriptive naming (White, Black, Light-Gray), dark mode requires either maintaining two separate naming systems or creating confusing names like 'Light-Background' that are wrong in dark mode. If your system uses semantic naming (Surface, Background, Raised) dark mode becomes a simple token remapping — Surface-Default changes from near-white to near-black and every component that references Surface-Default automatically responds. Well-named semantic tokens make dark mode implementation a 2-3 hour project; poorly named descriptive tokens make it a multi-week migration.

Newer issue

Material Color: How Physical Material Properties Change Color Perception

2028-08-19

Older issue

Color in Motion: How Animation Changes Color Perception and What Designers Miss

2028-09-02