How to Name and Organize Colors in a Design System

How to Name and Organize Colors in a Design System
  • Design Systems
  • Color Tokens
  • UI Design

A palette becomes much easier to use when colors are organized by purpose. Names like blue-500 or coral-300 describe appearance, but they do not always explain how a color should be used. Role-based names help designers and developers apply colors consistently.

Separate Raw Colors From Semantic Colors

Raw colors describe the actual swatches in the palette. Semantic colors describe their job in the interface. For example, brand-blue-600 may become action-primary-background, while neutral-900 may become text-primary.

  • Raw color: blue-600
  • Semantic role: button-primary-background
  • Raw color: neutral-100
  • Semantic role: surface-subtle
  • Raw color: red-600
  • Semantic role: feedback-error

Use Names That Explain Intent

Names should help a team understand where a color belongs. Text-primary is clearer than dark-gray. Border-muted is clearer than gray-200 when the goal is implementation consistency. This becomes especially useful when a brand refresh changes the raw colors but the interface roles stay the same.

Keep the System Small at First

A design system does not need dozens of color roles on day one. Start with the roles used on real screens: text, background, surface, border, primary action, secondary action, success, warning, and error. Add more only when repeated use proves they are needed.

Document Contrast Expectations

For important roles, document which foreground and background pairs are approved. This prevents teams from combining colors that look close to the system but fail readability checks.

Example Naming Structure

A small project might use names such as text-primary, text-secondary, background-page, surface-card, border-muted, action-primary, action-primary-hover, feedback-success, feedback-warning, and feedback-error. These names tell the team how to use the color without needing to remember every hex value.

As the product grows, this structure can expand into light and dark themes. The role names can stay stable while the actual color values change for each theme.

A well-named color system reduces confusion. It helps a palette move from a visual idea into a reliable product language shared by design, development, and content teams.