Design tokens

A token separates the decision from where it gets used. The decision is that primary actions are this blue. Every button and link then refers to that decision by name, so nothing downstream has to know the value.

Most systems run in two layers. Base tokens hold the raw palette and scale, and semantic tokens say what each one is for, such as body text or a rule between rows. Design tools and code can read the same set, which is what keeps a file and a shipped page from quietly becoming two different brands.

Why it matters for a marketing site

Builders encourage one-off values, so a site collects seven nearly identical grays over a few years. Rebuilding it without tokens carries the drift into code. With them, a rebrand is a small edit, and a person or coding agent adding a page reaches for the system instead of guessing a hex code.

How I handle it

A migrated site gets its own token sheet and styleguide, made during the migration from what the old site actually uses. On this site the tokens live in one block of global.css and show on /style, and a build check fails when a component adds a raw color, or a raw pixel size for type, radius or tracking. A check holds up better than a rule people have to remember.

Example

Say a site uses #2850ff in 40 places. As a token it is one line, --color-blue, and the 40 places read the name. Changing the brand blue becomes one edit. Contrast checks can also test the token pairs once, rather than hunting through every page.

Common mistakes

• Naming tokens after their values. A token called blue-500 reads wrong the day the brand moves to teal. Name the job or keep one clear family.
• Tokenizing everything on day one. Start with the decisions that repeat. A token used once is just a longer way to write a value.
• Having no check. Without one, raw values creep back in with the first deadline.