Building a design system from scratch with Figma tokens & Tailwind

Why most design systems fail

I've seen this happen three times at three different companies. Someone builds a beautiful design system in Figma — consistent spacing, tokens, a proper type scale — and six months later the engineering team has drifted so far from it that the two are completely out of sync. Nobody's fault. Just entropy.

The problem is almost never the design. It's the handoff layer. When tokens live in Figma and values are manually copy-pasted into CSS variables, you've created a system that requires human discipline to stay consistent. And human discipline at scale doesn't work.

The token pipeline architecture

The stack I settled on after way too many failed experiments: Figma Variables → Style Dictionary → Tailwind config. Here's why each piece matters and what I almost got wrong.

Figma Variables as the source

Since Figma introduced native Variables (not just styles), you can export a structured JSON of your entire token set. The key is naming discipline — everything follows a category/scale/variant pattern from day one. If you start with arbitrary names, the pipeline becomes a mess fast.

// Exported from Figma Variables
{
  "color": {
    "primary": { "value": "#efc983", "type": "color" },
    "surface": {
      "container": { "value": "#201f1f", "type": "color" },
      "low":       { "value": "#1c1b1b", "type": "color" }
    }
  }
}

Style Dictionary transforms

Style Dictionary takes that JSON and outputs whatever format your platform needs — CSS custom properties, JS objects, Swift, Kotlin, whatever. The transform step is where you handle platform-specific concerns like unit conversion or color format normalization.

---

Keeping Figma and code in sync

The real trick is automation. I run a GitHub Action that triggers whenever the design team exports a new token file, runs it through Style Dictionary, and opens a PR with the diff. Engineers review a real code change. Nothing is invisible. Nothing drifts silently.

Practical tips from the trenches

A few things I wish someone had told me before I spent three weekends debugging a token collision between light and dark mode aliases inside Style Dictionary's reference resolution.

First — never use raw hex values in component tokens. Always reference a primitive. --color-button-bg: var(--color-primary) not --color-button-bg: #efc983. This is the difference between a system that supports theming and one that doesn't.