Everyday Interface

Semantic Colour Tokens: Building a Palette That Scales Beyond One Theme

Semantic Colour Tokens: Building a Palette That Scales Beyond One Theme

Every design team eventually hits the same wall. The palette that worked beautifully for the first version of the product — a brand blue, a few greys, a red for errors — starts to crack the moment someone asks for a second theme, a white-label version, or better contrast for accessibility. Hex codes are scattered across hundreds of components, and nobody is quite sure which grey is "the" grey anymore. Semantic colour tokens are the way out of that mess, and getting them right early saves months of repainting later.

From Raw Values to Meaning

A colour token system typically has two layers. The first is the primitive layer: the raw palette itself. Blue 500, grey 100, red 600 — pure values with no opinion about where they're used. The second is the semantic layer, where things get useful. Instead of "grey 100", a component references "surface-secondary". Instead of "blue 500", a button uses "action-primary".

The distinction sounds academic until you need to change something. If your danger colour is referenced as "red-600" in forty components, shifting the error styling means forty edits and inevitable inconsistencies. If everything points at "feedback-danger", it's one change in one place. More importantly, semantic names encode intent: a new team member doesn't need tribal knowledge to know which colour a destructive button should use.

Naming Is the Hard Part

Most token systems fail not on technology but on vocabulary. A workable naming approach describes what a colour does, roughly in the pattern of category, role and variant:

Resist names tied to appearance. The token "light-grey-background" becomes a lie the moment dark mode arrives and the value turns near-black. Equally, resist over-specific names like "settings-page-sidebar-background" — tokens should describe roles that recur across the product, not individual screens. When a token only makes sense in one component, it probably belongs at the component level, aliased from a semantic token above it.

Dark Mode Is the First Real Test

A semantic layer proves its worth the day you build a second theme. Dark mode is not an inversion — elevation logic actually flips. In light interfaces, raised surfaces are often distinguished by shadow on white; in dark interfaces, raised surfaces get lighter, because shadows disappear against dark backgrounds. Saturated brand colours that sat comfortably on white can vibrate harshly on near-black and usually need desaturated, slightly lightened variants.

With semantic tokens, each theme is simply a different mapping from meaning to value. "Surface-raised" points to white with a shadow in the light theme and to an elevated grey in the dark theme. Components never change; only the mapping does. Teams that skipped the semantic layer discover this the hard way, hand-patching dark values into component after component and shipping a theme full of unreadable corners.

Contrast Belongs in the System, Not the Review

Accessibility checks are usually done screen by screen, late, under deadline. A token system lets you shift that work upstream. Because the number of meaningful colour combinations is finite — text tokens on surface tokens, action colours against their labels — you can validate contrast at the system level once, and every component inherits the result.

A practical rule: for every surface token, define which text tokens are permitted on it, and verify those pairs against WCAG contrast ratios (4.5:1 for body text, 3:1 for large text and essential UI elements). Some teams automate this in their token pipeline so a failing pair breaks the build. That sounds strict, but it converts accessibility from a periodic audit into a property the system simply guarantees.

Governance: The Unglamorous Bit That Decides Everything

Token systems decay through a thousand small exceptions. A designer needs a slightly different hover state, a developer hardcodes a hex "just for now", and a year later the system describes a product that no longer exists. Three habits keep things honest. First, make the token path easier than the workaround — good tooling in Figma and code autocomplete matter more than policy documents. Second, create a lightweight process for proposing new tokens, so unmet needs surface instead of festering as hacks. Third, periodically diff shipped styles against the token set; the gap tells you where the system is failing its users, who are your own colleagues.

Conclusion

Semantic colour tokens are one of those investments that feel bureaucratic on day one and indispensable by year two. They turn theming from a rewrite into a mapping exercise, make accessibility a built-in property rather than a recurring scramble, and give teams a shared language for colour decisions. Start with a small, honest set of roles, name them for meaning rather than appearance, and let the system grow with the product instead of chasing it.