Why semantic color tokens are worth the extra naming effort

Raw hex values in a stylesheet are a maintenance liability. Semantic tokens — names like --color-surface-primary or --color-action-default — decouple intent from implementation and make design system changes much cheaper. The naming effort pays for itself the first time you change a theme.

Tokens Systems Development

Highlights

Semantic tokens separate intent (what this color means) from implementation (what hex value it currently has). This separation allows the underlying color to change without every component that uses it needing to be updated.

A well-structured token system has two layers: primitive tokens (raw color values organized by lightness step, like --color-blue-400) and semantic tokens (intent-based names that reference primitives, like --color-action-default: var(--color-blue-400)).

The practical benefit emerges at theme switch time: changing from light to dark mode requires only remapping the semantic tokens to different primitive values — no component code changes, no new CSS, just a token reassignment.

The two-layer token model

A semantic color token system has two distinct layers. The primitive layer contains the full color vocabulary — every shade available, named by color and lightness step. Primitive names are descriptive but not meaningful: --color-teal-300 is a specific lightness of teal, nothing more. The semantic layer maps intent onto primitives — --color-action-default might reference --color-teal-300 in the light theme and --color-teal-400 in the dark theme. Components consume only semantic tokens. This separation is the key insight: components become indifferent to the underlying color values because they only care about semantic intent. A button that uses --color-action-default will look correct in any theme as long as the token is mapped correctly.

Common semantic categories

A minimal semantic layer needs five categories to cover most interface needs. Surface tokens describe backgrounds at various depths: surface-primary for page background, surface-secondary for card backgrounds, surface-elevated for floating layers. Border tokens describe edge treatments: border-default, border-subtle, border-focus. Text tokens describe content: text-primary, text-secondary, text-placeholder, text-inverse. Interactive tokens describe action states: action-default, action-hover, action-pressed, action-disabled. Status tokens describe system feedback: status-success, status-warning, status-error, status-info. The Nocturne Tech collection maps cleanly onto this framework — every color in the set has an obvious semantic role, which is why it exports so cleanly as a token set.

Starting with semantic tokens in a new project

The fastest way to adopt semantic tokens is to start from a well-structured collection and assign semantic names to the colors you already know you need. ColorArchive packs include pre-named CSS custom properties organized by semantic role — the Complete Archive ships with a full token set covering surface, border, text, interactive, and status categories for both light and dark themes. The hardest part of semantic naming is resisting the temptation to use color names — calling a token --color-blue-hover instead of --color-action-hover defeats the purpose. A useful rule: if you can replace a semantic token name with a color name and the name still makes sense, it is not semantic enough. Surface, action, status, border, and text are semantic. Blue, coral, and amber are not.

Newer issue

The 60-30-10 ratio is a heuristic, not a law — but it points at something real

2026-06-25

Older issue

Color transition strategy: how to animate between palette states without visual chaos

2026-07-09