Design Tokens: Stop Your Brand Colours Drifting Between Figma and CSS

#css #figma #webdev #design

A brand guideline PDF says the primary colour is orange. Six months later the website has four slightly different oranges, the email templates have a fifth, and nobody can say which one is right.

Design tokens fix this by turning brand decisions into named, versioned data that both designers and developers consume. This post shows a small, practical setup you can adopt without a big design-system project.

What a design token is

A token is a name paired with a design decision:

{
  "color": {
    "brand": {
      "orange": { "$value": "#F26D25", "$type": "color" },
      "yellow": { "$value": "#FDBE37", "$type": "color" }
    }
  }
}

The $value / $type shape follows the format being standardised by the W3C Design Tokens Community Group. Tools such as Style Dictionary can read token files and generate CSS, iOS, Android or JavaScript outputs from the same source.

Use three tiers, not one

Putting raw hex values straight into components recreates the original problem. A three-tier structure keeps changes cheap:

Tier	Example name	Holds	Who changes it
Primitive	`color.brand.orange`	The raw brand palette	Brand owner, rarely
Semantic	`color.action.primary`	The role a colour plays	Design system owner
Component	`button.primary.background`	A specific component decision	Component owner

Semantic tokens point at primitives, and components point at semantic tokens. When the brand refreshes its orange, you change one primitive. When marketing wants a different call-to-action colour for a campaign, you change one semantic token, and no component code moves.

Output as CSS custom properties

The simplest delivery format for the web is CSS custom properties:

:root {
  /* primitives */
  --color-brand-orange: #F26D25;
  --color-brand-yellow: #FDBE37;
  --color-neutral-950: #141414;
  --color-neutral-50: #f5f5f5;

  /* semantic */
  --color-action-primary: var(--color-brand-orange);
  --color-surface: var(--color-neutral-50);
  --color-text: var(--color-neutral-950);
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-surface: var(--color-neutral-950);
    --color-text: var(--color-neutral-50);
  }
}

.button-primary {
  background: var(--color-action-primary);
  color: var(--color-neutral-950);
}

Dark mode becomes a matter of remapping semantic tokens, not rewriting components.

Tokens are not only colours

Most brand drift comes from the things that are not colours:

Typography: font families, a type scale, line heights, and weights
Spacing: a small scale (for example 4, 8, 12, 16, 24, 32, 48) instead of arbitrary pixel values
Radius and elevation: corner radii and shadows
Motion: durations and easing curves

If your brand works in more than one script, for example Arabic and English, give each script its own typography tokens. Arabic type usually needs different sizes and line heights to read as comfortably as Latin text at the same visual weight.

Checks that keep tokens honest

Contrast checks in CI. Generate every text/background semantic pair and fail the build if any combination drops below the WCAG contrast ratio you have committed to.
Lint for raw values. A stylelint rule that rejects hex colours outside the token files stops drift at code review.
Version the token package. Treat token changes like an API: a changelog, semantic versioning, and a visual diff before release.
One source of truth. Designers and developers must edit the same token file (or a tool that syncs to it), never parallel copies.

Where to start this week

Export the brand palette and type scale into a single JSON token file.
Add semantic names for the five or six roles you actually use: primary action, surface, text, muted text, border, danger.
Generate CSS custom properties and replace hard-coded values in one high-traffic template.
Add the contrast check.

That is enough to stop the "five oranges" problem, and it scales into a full design system later.

DEV Community