Figma Design Tokens Sync: Automatic Export to CSS Variables

Why Manual Token Management Breaks Design Systems

Honestly, copying hex codes from Figma into your CSS by hand is one of the most reliable ways to introduce drift between design and code. You do it once, it's fine. You do it twenty times across a six-month project and suddenly your button component renders #1A73E8 while the Figma file says #1A72E7. Nobody notices until a client does.

The problem isn't laziness. It's that manual processes have no feedback loop. When a designer updates the primary brand color, nothing in your codebase breaks — it just silently becomes wrong. That gap is where design systems go to die.

The fix is a token pipeline. Tokens defined once in Figma, exported automatically, and transformed into CSS custom properties that your components actually consume. Change the source, run the script, done. No copy-paste, no drift.

What Are Design Tokens (and What They're Not)

Design tokens are named values that represent design decisions. color.brand.primary is a token. --color-brand-primary: #1A73E8 is its CSS output. Tokens live at a higher abstraction than raw values — they carry intent.

They're not just variables with fancy names. A token like spacing.component.gap.sm encodes the *decision* that small component gaps are 8px. When that decision changes, you update one source and regenerate. Contrast that with hunting through five stylesheets for every gap: 8px instance.

Token categories typically cover color (primitives, semantics, component-level), spacing, typography (font size, weight, line height), border radius, shadow, and motion. If you're building on Tailwind v4.0.2, most of these map directly to the new @theme block — which we'll get to in a minute.

Setting Up the Figma Tokens Pipeline

You'll need two things: a way to get tokens *out* of Figma, and a way to transform them into usable CSS. The most common path right now is the Tokens Studio for Figma plugin (free tier works) paired with Style Dictionary v3.

Tokens Studio exports a JSON file — either to a local file sync or directly to a GitHub repo via its built-in integration. The JSON structure looks like nested objects keyed by token name, each with a value and type. Once that's in your repo, Style Dictionary takes over.

Install it with npm install style-dictionary@3. Then create a sd.config.js at your project root. Point it at your tokens JSON, configure your platforms (CSS, JS, whatever you need), and you have a repeatable build step. Pair it with a GitHub Action and token updates from Figma auto-publish to your CSS on every push.

Style Dictionary Config and Output Format

Here's a minimal but production-ready Style Dictionary config that transforms Figma token JSON into CSS custom properties:

// sd.config.js
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'empire',
      buildPath: 'src/styles/tokens/',
      files: [
        {
          destination: 'variables.css',
          format: 'css/variables',
          options: {
            outputReferences: true,
          },
        },
      ],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'src/tokens/',
      files: [
        {
          destination: 'index.js',
          format: 'javascript/es6',
        },
      ],
    },
  },
};

The outputReferences: true option is important — it preserves token aliases in the output. So if your semantic token color.surface.overlay references color.neutral.900 with opacity rgba(255,255,255,0.15), the CSS output keeps that relationship rather than flattening to a raw value. Easier to debug, easier to understand at a glance.

Run npx style-dictionary build --config sd.config.js and you'll get a variables.css with a :root block containing every token prefixed with --empire-. Import that single file in your app entry point and every component in your tree has access.

Mapping Tokens to Tailwind v4 Theme Variables

Tailwind v4.0.2 made something interesting official: CSS variables as first-class theme values. The new @theme directive in your CSS file lets you define theme tokens that Tailwind's utility classes consume directly. This is where your design token pipeline pays off immediately.

/* src/styles/main.css */
@import './tokens/variables.css';

@theme {
  --color-brand-primary: var(--empire-color-brand-primary);
  --color-surface-default: var(--empire-color-surface-default);
  --color-surface-overlay: var(--empire-color-surface-overlay);

  --spacing-gap-sm: var(--empire-spacing-component-gap-sm); /* 8px */
  --spacing-gap-md: var(--empire-spacing-component-gap-md); /* 16px */

  --radius-card: var(--empire-border-radius-card); /* 12px */
  --radius-button: var(--empire-border-radius-button); /* 6px */
}

Now bg-brand-primary works as a Tailwind class, sourced directly from your Figma tokens. When the designer updates the brand color in Figma and the Tokens Studio sync runs, a single CSS variable update cascades through every component using that utility. No tailwind.config.js edits needed.

This also plays nicely with theme toggling in React. You can scope different token sets under [data-theme="dark"] and swap the underlying CSS variable values without touching any component logic. Your design system handles the colors; components just use semantic class names.

Automating the Sync With GitHub Actions

Manual pipeline runs defeat the purpose. The real win is a GitHub Action that triggers whenever Tokens Studio pushes an update to your tokens branch — which it does automatically if you set up the GitHub sync in the plugin settings.

# .github/workflows/sync-tokens.yml
name: Sync Design Tokens

on:
  push:
    branches: [tokens/figma-sync]
    paths:
      - 'tokens/**'

jobs:
  build-tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
      - run: npx style-dictionary build --config sd.config.js

      - name: Commit generated tokens
        run: |
          git config user.name "tokens-bot"
          git config user.email "tokens-bot@empire-ui.com"
          git add src/styles/tokens/ src/tokens/
          git diff --staged --quiet || git commit -m "chore: regenerate tokens from Figma sync"
          git push origin tokens/figma-sync

From there, open a PR from tokens/figma-sync into main whenever there are changes — or merge automatically if you trust your token linting. Either way, the generated CSS files are always in sync with the Figma source. No designer has to ping a developer to "please update the colors."

Token Linting and Preventing Bad Values From Shipping

What happens when a designer accidentally sets a font size token to 0 or a color to an invalid hex? Without guards, that ships. Token linting catches it before the CI passes.

The token-transformer package (part of the Tokens Studio ecosystem) includes a --expandTypography flag and basic validation. But for serious pipelines you'll want a custom validation step. A simple Node script that reads your tokens JSON and asserts constraints — no color value with opacity outside 0–1, no spacing token above 200px, font weights only in [400, 500, 600, 700, 800] — runs in under a second and blocks bad merges.

Also worth thinking about: token naming collisions. If you have color.brand.primary and color.brand-primary as separate tokens (a surprisingly easy mistake in Tokens Studio), Style Dictionary will silently overwrite one. Add a lint step that flattens your token namespace and checks for duplicates. The color system design article has a good breakdown of token naming conventions that avoid this class of problem entirely.

Once your pipeline is solid, document it in Storybook. A dedicated "Tokens" story that renders all your CSS variables in a grid — showing color swatches, spacing scales, type ramp — gives designers a live view of what's actually in the codebase. The Storybook component library guide covers the setup if you haven't done it.

Connecting Tokens to Empire UI Components

Empire UI components are built to consume CSS custom properties rather than hardcoded values. That's intentional. It means swapping your design token output into an Empire UI project is a matter of making sure your --empire-* variables match what the components expect.

Is every component token-aware out of the box? Most color and spacing ones are. A few of the more opinionated visual styles (glassmorphism styles reference rgba(255,255,255,0.15) directly for the overlay — see what is glassmorphism for context) use inline values for predictability. Those can be overridden at the component level if your token pipeline defines them.

The figma to react guide covers the manual version of this workflow in detail — useful for understanding the full picture even if you're automating it. Start with that, get the pipeline running, then layer in the automation described here. Doing it in that order means you actually understand what the scripts are doing, which matters when something breaks at 11pm before a release.

FAQ

Read next