Systems

Colour tokens are an API

Rename a colour and every page that assumed it breaks quietly. Tokens deserve the same discipline as a public function: versioning, deprecation, and aliases.

Intermediate1 min read (computed · recorded 8)updated 2026-09-12tokensthemingapi-design

by Motif Editors

revised 2026-09-12 — First publication in bank-3 batch 4.

Key takeaways

— A token consumed twice is an API with consumers you cannot email.
— On rename: alias, don't redirect — and never change the value under the old name.
— Contrast is part of the token's contract, measured per pair.

The contract you already shipped

The moment a second file reads a colour variable, that variable is an API. Consumers include your own components, user overrides, and the embed pages other people host — the last group cannot be migrated by a find-and-replace.

Alias on rename, never redirect

When a token's name must change, keep the old name as an alias pointing at the new value for one release, and print the deprecation in the token table itself. The site's /integrations/tokens page prints the pairs, so the alias cannot rot in a comment.

What you must not do is change the value under the old name. That is a silent breaking change wearing a migration's clothing.

Name tokens by role (surface, ink, accent), never by colour (blue-400).
One accent per theme; a second accent is a new decision, not a new token.
Contrast is part of the contract — the catalog computes it per pair and publishes the failures.

Practise the lesson

Theory sticks when you ship it. These original Motif assets put this guide's lesson to work — open one and copy it into your own page.

Drag-a-theme Chippractice Colour Pickerpractice Hero with Product Mock Framepractice

Keep learning

All guides Try the interactive Lab