Semantic Color Tokens for Maintainable UI Themes

Raw colors and semantic colors answer different questions

A raw palette might contain blue-500, gray-50, and red-600. Those names describe a color family or scale position. A semantic layer contains names such as color-background, color-text, color-primary, and color-danger. Those names describe purpose.

:root {
  --blue-600: #2563eb;
  --slate-50: #f8fafc;
  --slate-950: #020617;

  --color-background: var(--slate-50);
  --color-text: var(--slate-950);
  --color-primary: var(--blue-600);
}

Components should usually consume the semantic layer. A button that references --color-primary can survive a rebrand or theme change without knowing which raw shade currently supplies that role.

Start with a small role vocabulary

Do not create hundreds of semantic tokens before the product has those needs. A compact system can begin with background, surface, primary, secondary, accent, text, muted text, and border. Add success, warning, danger, focus, selected, and disabled roles when the component system requires them.

Theme by remapping roles

Light and dark themes work best when components keep their semantic references and the theme changes which raw values fill those roles. This avoids component-specific inversion logic and makes theme review systematic.

[data-theme="dark"] {
  --color-background: var(--slate-950);
  --color-surface: var(--slate-900);
  --color-text: var(--slate-50);
  --color-primary: var(--blue-400);
}

Tokens do not guarantee accessibility

Semantic naming improves consistency, but it does not make a color pairing accessible by itself. The same primary token may be safe as a large filled button and unsafe as small text on a white background. Document which role combinations are permitted and test component states, not just token values.

Keep export formats secondary to the model

CSS variables, JSON, SCSS, and JavaScript objects are transport formats. The important part is the stable semantic model behind them. If every platform uses the same role names and meanings, teams can generate platform-specific files without losing the design intent.

A maintainable token review

1. List the raw palette independently from semantic roles.
2. Assign the smallest useful role set.
3. Define component-level tokens only when a component truly needs independent control.
4. Map light and dark themes through the same semantic vocabulary.
5. Audit allowed contrast pairings and focus/status states.
6. Export to code only after the naming and role model are stable.