hexcolors

Learn / Blog / Developers

Design tokens for color: how to name and organize them

Primitive, semantic and component tokens explained, with CSS variable examples and dark mode.

November 15, 20261 min readBy the hexcolors team

Key takeaways

  • Separate raw colors (primitives) from their meaning (semantic tokens).
  • Name tokens by role, not by color.
  • Dark mode becomes a remapping of semantic tokens.

A design token is a named value that stores a design decision. For color, tokens turn a pile of hex codes into a system that a whole team can use consistently.

Level 1: primitive tokens

Primitives are the raw palette, named by hue and step: --blue-500: #3b6cff. They describe what the color is, not where it is used. Generate each family with the shade scale generator.

Level 2: semantic tokens

Semantic tokens describe the job a color does: --color-text, --color-surface, --color-border, --color-action. They point at primitives:

:root {
  --blue-500: #3b6cff;
  --gray-950: #0c0c14;
  --gray-50: #f6f6fa;

  --color-action: var(--blue-500);
  --color-text: var(--gray-950);
  --color-surface: var(--gray-50);
}

Level 3: component tokens

Optional, and useful in larger systems: --button-bg: var(--color-action). This lets you restyle one component without touching the rest.

Name by role, not by color

A token called --color-blue becomes a lie the day your brand turns green. A token called --color-action survives the change, because only its value moves.

Dark mode as a remap

When components only use semantic tokens, dark mode means pointing those tokens at different primitives:

@media (prefers-color-scheme: dark) {
  :root {
    --color-text: var(--gray-50);
    --color-surface: var(--gray-950);
  }
}

Retest every pair afterward with the contrast matrix, because passing in light mode does not guarantee passing in dark.

Document and share

Keep one source of truth, publish it to designers and developers, and explain the rules. Our post on building a brand color system covers the thinking that comes before the tokens.

The hexcolors teamWe build free color tools and write practical guides. Follow us on X, Instagram and LinkedIn.