Color naming is a systems design decision, not a branding exercise

How you name colors in a design system determines how teams reason about them, how documentation stays current, and how onboarding scales. Semantic names age well; descriptive names create maintenance debt. The naming strategy you choose in week one will shape token discussions for years.

Systems Tokens Process

Highlights

Descriptive color names — 'coral', 'slate-blue', 'warm-gray-3' — create a mapping problem: as soon as the brand color changes, every reference to the old name either becomes wrong or requires a rename cascade that touches every file that imports the token.

Semantic names — 'color-surface-primary', 'color-action-default', 'color-feedback-error' — describe the role of a color rather than its appearance, which means they survive rebrand without breaking references, and self-document their intended usage context.

The primitive/semantic split allows both: primitive tokens use descriptive names to define the raw palette, semantic tokens use role-based names for all component references — teams get clear color names at the bottom and stable API names at the top.

Why names matter more than values

Most design system conversations focus on choosing the right color values — the perfect primary blue, the exact warm neutral. But the more consequential long-term decision is what to call those values. A token named 'blue-600' is semantically opaque: it tells you nothing about where it belongs or what it does, and when the brand pivots to a different blue, every downstream reference is either wrong or needs updating. A token named 'interactive-primary' tells you exactly where it belongs and survives any number of underlying color changes without requiring consumers to update anything. The name, not the value, is what the rest of the system depends on.

The maintenance cost of descriptive names

Descriptive names feel intuitive when the palette is first defined because they are easy to understand in isolation. The maintenance problem becomes clear over time. When a brand color shifts from warm coral to cool terracotta, a token named 'coral' is now lying — it either needs to be renamed (touching every consumer) or left misleading (creating confusion in documentation and code review). Multiply this across a full palette that evolves over several product generations and the accumulated debt becomes a significant onboarding obstacle. New team members must memorize what 'coral' actually looks like today rather than reading what the token name tells them about its purpose.

A naming strategy that scales

The approach that scales reliably uses a two-layer structure. The primitive layer uses concise descriptive names — these are the raw color values and can use hue-lightness shorthands like 'teal-400' or 'neutral-200'. No component should reference primitive tokens directly. The semantic layer uses role-based names structured as category-role-variant — 'surface-primary', 'action-hover', 'text-secondary'. Components only reference semantic tokens. When the brand changes, you update the mapping between semantic and primitive tokens in one place. The semantic names and all component references stay untouched. This is the approach baked into the Complete Archive token set — primitives define the color space, semantics define the vocabulary.

Newer issue

Why dark mode colors need more saturation than you think

2026-05-14

Older issue

Color temperature as a communication tool: what warm and cool actually signal

2026-05-28