How to Build a Figma-to-Storybook Design Token Sync Workflow

This guide shows you how to build a live sync pipeline that pushes design tokens from Figma directly into a Storybook component library. Following all steps takes roughly two to three hours. Once set up, any token change your designer makes in Figma appears in Storybook within minutes, without a developer touching a file manually.

What You'll Build

• A Figma Variables export powered by the Tokens Studio plugin, outputting a structured JSON token file
• A Style Dictionary transform that converts raw token JSON into CSS custom properties and JavaScript constants
• A GitHub Actions workflow that runs the transform on every push to main and commits the output automatically
• A Storybook 8 configuration that consumes the generated CSS so every component previews live tokens in real time

Prerequisites

• Node.js 20 or later and pnpm 9 installed locally
• A Figma file with at least one Variable collection (colours, spacing, typography)
• Tokens Studio for Figma plugin installed (free tier is sufficient)
• A GitHub repository with a React component library already initialised
• Storybook 8.x installed in that repository (pnpm dlx storybook@latest init if needed)
• Basic familiarity with GitHub Actions YAML syntax

Step 1: Export Your Figma Variables as Token JSON

Why does this step matter?

Figma's native export does not produce a format that build tools understand. Tokens Studio gives you a structured JSON file that matches the W3C Design Token Community Group spec, which Style Dictionary can process directly.

Open your Figma file and launch the Tokens Studio plugin. In the Settings tab, connect it to your GitHub repository using a personal access token with repo scope. Set the token file path to tokens/tokens.json and the branch to main.

Back in the Tokens tab, map each Figma Variable collection to a Tokens Studio set. A typical mapping looks like this:

• Primitives collection → global set
• Semantic/Alias collection → semantic set
• Component-specific collection → component set

Click Push to GitHub. Verify that tokens/tokens.json appears in your repository.

Common pitfall: If your Figma Variables use modes (light and dark), Tokens Studio exports them as separate sets. Name them semantic/light and semantic/dark so Style Dictionary can resolve them cleanly in the next step.

Step 2: Install and Configure Style Dictionary

What does Style Dictionary actually do here?

Style Dictionary reads your raw JSON and transforms it into platform-specific outputs. In this pipeline, you want two outputs: a CSS file of custom properties for the browser, and a TypeScript constants file for type-safe token usage in components.

Install the package:

pnpm add -D style-dictionary@4

Create a config file at sd.config.mjs in your project root:

import StyleDictionary from 'style-dictionary';

export default {
  source: ['tokens/tokens.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      prefix: 'ds',
      buildPath: 'src/tokens/',
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          options: {
            outputReferences: true,
          },
        },
      ],
    },
    ts: {
      transformGroup: 'js',
      buildPath: 'src/tokens/',
      files: [
        {
          destination: 'tokens.ts',
          format: 'javascript/es6',
        },
      ],
    },
  },
};

Run the build locally to confirm it works:

npx style-dictionary build --config sd.config.mjs

You should see src/tokens/tokens.css and src/tokens/tokens.ts generated. The CSS file will contain variables prefixed with --ds-, for example --ds-color-brand-primary.

Common pitfall: Style Dictionary 4 uses ES module syntax. If your project uses CommonJS, rename the config to sd.config.cjs and replace import with require. Check your package.json type field before running.

Step 3: Connect Tokens to Storybook

When should you skip this step?

Only skip it if your component styles are written entirely in CSS Modules that already reference the custom properties directly. If you use Tailwind, Emotion, or plain CSS imported at the app level, you need this step.

Open .storybook/preview.ts and import the generated CSS file:

import '../src/tokens/tokens.css';
import type { Preview } from '@storybook/react';

const preview: Preview = {
  parameters: {
    backgrounds: { disable: true },
  },
};

export default preview;

Now update one component to use a token variable. For example, a button component:

.button {
  background-color: var(--ds-color-brand-primary);
  padding: var(--ds-spacing-3) var(--ds-spacing-5);
  border-radius: var(--ds-border-radius-md);
  color: var(--ds-color-text-inverse);
}

Start Storybook with pnpm storybook and confirm the button picks up your token values. If colours look wrong, check that the token JSON used the same variable names you expect in the CSS output.

Pro tip: Add a Storybook Globals toggle for light and dark modes by wrapping the CSS import in a decorator that swaps a data attribute. Storybook's @storybook/addon-themes (included in Storybook 8 by default) handles this with about ten lines of config.

Step 4: Add a GitHub Actions Workflow to Automate the Sync

Why automate instead of running the build manually?

Manual runs break the promise of a live token sync. Designers push changes to Figma, Tokens Studio commits to GitHub, and the action should run immediately so developers never work with stale values.

Add a script to package.json:

{
  "scripts": {
    "build:tokens": "node --experimental-vm-modules node_modules/.bin/style-dictionary build --config sd.config.mjs"
  }
}

Create .github/workflows/sync-tokens.yml:

name: Sync Design Tokens

on:
  push:
    paths:
      - 'tokens/tokens.json'

jobs:
  build-tokens:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

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

      - run: pnpm install --frozen-lockfile

      - run: pnpm build:tokens

      - name: Commit generated tokens
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'chore: regenerate design tokens from Figma'
          file_pattern: 'src/tokens/**'

This workflow triggers only when tokens/tokens.json changes, which avoids unnecessary runs on every commit. The git-auto-commit-action commits the generated files back to the branch so Storybook always reflects the latest state.

Common pitfall: The action needs contents: write permission to push back to the repository. Without it, the commit step silently fails. Check your repository's Actions settings and confirm that workflow permissions allow writing.

Step 5: Validate the End-to-End Flow

How do you confirm the pipeline is actually working?

Run a deliberate change from Figma all the way through to Storybook. This catches configuration drift before your team relies on the workflow daily.

1. Open Figma and change a Variable, for example adjust your primary brand colour by one shade.
2. In Tokens Studio, click Push to GitHub. Add a commit message like test: update brand primary token.
3. Go to your repository's Actions tab. Watch the Sync Design Tokens workflow start within thirty seconds of the push.
4. Once the action completes, open the latest commit. Confirm that src/tokens/tokens.css contains the updated hex value.
5. Deploy Storybook (or run it locally on the updated branch) and verify your button component shows the new colour.

The full round trip, from Figma push to visible change in Storybook, should complete in under three minutes. If it takes longer, the bottleneck is usually pnpm install. Add a cache step if your dependency tree is large.

Pro tip: Add a Storybook Chromatic visual regression test at this point. When the token sync action commits new CSS, Chromatic can run automatically and flag any components where the token change causes unexpected visual diffs. Teams at companies like Atlassian and Shopify use this pattern to catch token misuse before it reaches production.

Step 6: Document the Workflow for Your Team

A working pipeline fails in practice if designers do not know how to push tokens or developers do not know where the generated files live. Write a short README section covering three things: how designers push from Tokens Studio, how developers import token constants in TypeScript, and what to do if the Action fails.

If your team manages a public-facing design system, you might also consider publishing the token CSS as an npm package so external consumers can stay in sync. A separate GitHub Actions job using npm publish --access public handles this with roughly ten additional lines of YAML.

At Lenka Studio, we follow a similar pattern on client design systems. Keeping design and code in sync from day one removes the category of bugs that comes from a developer hardcoding a colour that was changed in Figma three weeks ago.

If you are evaluating whether this workflow fits your current design system maturity, the brand health score assessment gives you a structured way to identify where your brand and design infrastructure has gaps worth closing first.

Frequently Asked Questions

Next Steps

Once your pipeline is running, consider three extensions. First, add a Chromatic step to your Action so visual regressions from token changes are caught before merge. Second, publish your token CSS as a versioned npm package so any downstream app can consume it. Third, introduce token linting with token-lint to enforce naming conventions before tokens are even pushed from Figma.

If you are building a design system for a growing product team and want the pipeline architected to production standards from the start, the team at Lenka Studio works with SMBs in Australia, Singapore, Canada, and the US on exactly this kind of design-to-code infrastructure. Get in touch and we can review your current setup.