Color naming systems: why the words you use for colors shape how teams use them

How you name a color changes how it gets used. Teams with semantic color names make different — and usually better — design decisions than teams using raw hex values or scale-position names like 'blue-500'.

Design Systems Naming Process

Highlights

Colors named by position (gray-100, blue-500) communicate what the color is but not what it is for — which leads to engineers choosing colors by feel rather than by intent when the designer is not available.

Semantic names (surface-primary, text-secondary, feedback-error) communicate intent and survive design system evolution better: when the exact blue changes in a rebrand, 'action-primary' still means what it meant, but 'blue-500' has to be re-mapped everywhere.

The most robust naming systems have two layers: primitive tokens (the raw palette values with position names) and semantic tokens (the functional role names that reference primitives). This structure makes both palette evolution and theme switching predictable.

What color names communicate to engineers

Design tokens are the handoff layer between design and engineering. When tokens are named by raw color values or palette positions ('blue-500', 'neutral-300'), the name communicates nothing about intended usage. Engineers implementing features without designer oversight — which is most features in most engineering environments — default to choosing tokens by visual approximation rather than semantic role. This produces color drift: the 'button text' color being pulled from 'text-primary' in one component and 'gray-900' in another, producing values that look similar but are not equivalent and diverge when themes change. Semantic naming prevents this by encoding intent directly into the token name. 'button-label-default' is unambiguous in a way that 'gray-900' is not.

Two-layer token architecture: primitives and semantics

The two-layer token pattern separates the palette definition (primitive layer) from the usage mapping (semantic layer). Primitive tokens define the complete set of color values available in the system — every step of every scale, named by their position in that scale (sand-10, sand-20, sand-30, through sand-100). Semantic tokens define usage roles — surface-background, text-primary, action-default — and reference primitive tokens as their values. The indirection is the key: when you need to adjust the palette (new brand blue, new gray tone, dark mode theme), you change the primitive values. The semantic layer stays stable, and every component that uses semantic tokens updates automatically. Components never reference primitives directly — only semantics. This architecture is what makes design systems resilient to change.

Practical naming conventions that travel well across teams

The most effective semantic naming conventions follow a consistent structure: context + property + state. 'button-background-hover' is unambiguous; 'button-bg-hov' and 'btnBgHover' are variations that create inconsistency in large codebases. Agreeing on a naming convention early — and enforcing it through a design system style guide — prevents the proliferation of synonyms (is it 'default', 'rest', 'base', or 'initial'?). The Brand Starter Kit ships with a pre-defined semantic token structure that covers the most common UI patterns: surfaces, text roles, interactive states, feedback states, and border treatments. Teams adopting it get a naming convention decision already made, along with Figma and CSS variable exports that follow the same naming pattern — so the token names match from design to code without a translation layer.

Newer issue

Dark mode is not just inverted light mode: the design decisions that make it work

2026-12-24

Older issue

Color in data visualization: why chart palettes need different rules

2027-01-14