Our Design Token System: How We Unified Design and Code

A red button. Sounds trivial. But if that red lives as a hardcoded #FF4B69 across 40 components, in 3 repos, and in 12 Figma frames, you’ve got a problem. Changing it is going to hurt.

Design tokens solve that. They’re variables with meaning that live in one place and propagate everywhere else. The contract between design and code.

Our convention: 3 layers

After breaking several systems, we landed on a structure that actually works:

1. Primitive tokens — raw values, no context.

--color-red-500: #FF4B69;
--space-4: 1rem;
--radius-md: 8px;

2. Semantic tokens — primitives with intent.

--color-brand-primary: var(--color-red-500);
--color-surface-danger: var(--color-red-500);
--space-section-gap: var(--space-4);

3. Component tokens — semantics applied to a specific component.

--button-primary-bg: var(--color-brand-primary);
--button-primary-radius: var(--radius-md);

Why three layers? Because changing the brand red (layer 2) shouldn’t force you to touch the 40 components that use it. And because primitives are neutral — they don’t know whether they’re meant for errors, brand, or a CTA.

Figma to CSS: the boring but critical part

We use Tokens Studio in Figma, which exports to JSON. Then Style Dictionary transforms that JSON into CSS custom properties, Tailwind config tokens, and TypeScript constants.

The workflow:

1. A designer tweaks a token in Figma.
2. Automated PR to a tokens repo.
3. Style Dictionary generates the assets.
4. The design system publishes a new version.
5. Consumers bump the dependency.

Not glamorous. But auditable, versioned, and reversible. Which is exactly what a mature system needs.

Mistakes we made

• Starting with component tokens first. Without a semantic layer, every change was a massive refactor.
• Names based on looks, not function: --color-blue-button ages badly. When the button stops being blue, the name lies.
• Not documenting the “why”: every semantic token has a comment explaining when to use it. Without that, nobody knows whether to pick --color-surface-danger or --color-text-error.

The bottom line

A token system isn’t a variables file. It’s a shared discipline between design and development. If your team doesn’t speak the same language, tokens won’t fix it. But if they do, tokens make it scalable.