all insights
Oct 28, 20265 min readsystems

Design tokens without the drama

Design tokens are promises between design and code. Here is how to keep them without endless meetings.

Alex Vance

Design systems lead

  • Design tokens
  • Figma
  • CSS
  • Systems

Most design token rollouts fail for the same reason: they try to model every conceivable variation before shipping a single button. We treat tokens as living contracts that start tiny and grow with proof.

in short

Key takeaways

  1. 01

    Three tiers are enough

    Global values (colors, scale), semantic roles (surface, ink), and component overrides. Never add a fourth tier.

  2. 02

    Automate the boundary

    Figma variables should compile straight to CSS custom properties and typed TypeScript enums on commit.

  3. 03

    Lint for rogue values

    A pull request that introduces an arbitrary hex code or pixel spacing fails in CI before human review.

the details

The deep dive

The abstraction trap

When teams decide to create a design system, enthusiasm frequently outpaces discipline. Within three weeks, someone has invented a five-tier ontology with names like color-brand-primary-interactive-subtle-hover-active. No one can remember what it does, so developers inspect the Figma canvas and hardcode #7193ed anyway.

The cure is strict minimalism. Start with global raw values (your literal palette and scales), map them to semantic intents (--surface-page, --ink-primary, --border-default), and stop. If a component needs something special, let it declare a local token rather than polluting the shared lexicon.

tokens.css
/* 1. Global palette primitives */
:root {
  --blue-500: #7193ed;
  --blue-600: #4468d8;
  --void-900: #121213;
  --void-100: #f1f1f4;
}

/* 2. Semantic roles that components actually consume */
:root {
  --surface-page: var(--void-900);
  --ink-primary: var(--void-100);
  --accent: var(--blue-500);
  --accent-hover: var(--blue-600);
}

The best token system is the one that prevents arguments. If a designer changes a radius, code shouldn't need a PR discussion. — Alex Vance, Design systems lead

Automate or perish

Manual token sync is a fiction. If a designer tweaks an opacity token in Figma and has to paste a Slack message asking an engineer to update a JSON file, drift has already begun.

We wire Figma Variables directly to a GitHub Action via the Figma REST API. When variables are published in Figma, a workflow generates typed TypeScript definitions and CSS variables, runs visual regression tests, and opens an automated pull request with a visual diff summary.

drift between design & code
0
from Figma publish to PR
<30s
maximum token depth
3 tiers
next essayShipping AI features responsibly