Storysync

Sync your design system from code to Figma, and diff Figma back against code, using Storybook MCP and Figma MCP.

Start here: What it does · How it works · Install · Your first push · What a push costs · Check the result · Find drift · What Figma can't do

Reference: docs/reference.md has every command and flag, how each step works, tokens, the GitHub Action and troubleshooting.

What it does

Storysync reads design tokens from your code (a Tailwind config, CSS custom properties or theme files) and components from Storybook MCP. Your AI client then uses Figma MCP to create matching Figma variables and component sets.

Component styling is measured, not guessed:

1. storysync snap renders every variant of every component in a headless browser and records the computed styles of each element that draws: fills, spacing, radii, type, icons and pictures.
2. storysync figma code turns those measurements into the Figma calls your AI client sends, unchanged.
3. storysync verify reads Figma back and scores it against the measurements, element by element.

There are three workflows: push (code to Figma), verify (score what landed against what rendered) and diff (find drift in either direction). Storysync never writes your code. See Non-goals.

Use it from	What it does
Claude Code, Cursor or Codex	A skill file runs the CLI commands, sends the Figma calls through use_figma, and scores the result with verify. It can also audit Figma against code.
The CLI	Extract tokens, map components, measure rendered styles, write a push's Figma calls, score a push, or diff Figma against code.
GitHub Action	Catch token and component drift in CI.

Why a skill file? Writing to Figma needs Figma's use_figma tool, which works only inside supported MCP clients such as Claude Code, Cursor and Codex. So the CLI does the extracting and the measuring and writes every Figma call, for tokens and components alike, and the skill tells your AI client to send those calls and run the commands around them. Storysync needs no Anthropic API key and makes no LLM calls of its own.

How it works

Say your Storybook has a Badge with 20 variants (5 tones, 2 styles, 2 sizes), and your designers need the same 20 in Figma.

1. Run one command. In Claude Code, run /storysync-push <figma-file-key>. The file key is the part of a Figma URL between /design/ and the next /.

2. It measures each variant. Storysync renders every variant in Storybook and records what the browser drew for each element: colors, padding, radius and type.

3. It builds the set in Figma. You get one variant per combination, named by its props, such as tone=success, variant=subtle, size=md.

4. It checks every value. It reads Figma back and compares it with the measurements:

   Fidelity: 100.0% of elements (60 of 60 verified), 100.0% of properties (820/820)
   20 verified, 0 drifted, 0 missing from Figma, across 20 variants
   

5. Later, it finds drift. Someone changes the success badge's fill in Figma. Run /storysync-diff <figma-file-key> and ask whether the sets still look like the code. It reads Figma, changes nothing, and names the variant, the property and both values:

   ~ Feedback/Badge tone=success, variant=subtle, size=md › (root): fills measured ["#dcfce7"], Figma ["#e9d5ff"] (node 1:27)
   19 verified, 1 drifted, 0 missing from Figma, across 20 variants
   

6. Check it in CI. Commit the snap and the readback a push saves (.storysync/snaps/ and .storysync/figma-readback.json). npx storysync verify --strict in CI exits 1 when they disagree, such as when the code changes and a new snap is committed without a push. The GitHub Action catches components and tokens that changed in code since your committed baselines.

Both outputs above are from a real push of that Badge into Figma. Your first push has the setup.

Before you start

For components:

• Storybook 10.1 or later with a Vite-based framework: @storybook/react-vite, @storybook/nextjs-vite or @storybook/sveltekit.
• @storybook/addon-mcp, which serves MCP at /mcp. storysync init sets it up.
• The Storybook dev server (storybook dev), not a static build.
• Node.js 20 or later and a Chromium-based browser, for snap.

For writing to Figma:

• A Full seat on a paid plan. Dev seats are read-only (Figma's docs).
• A supported MCP client, which signs you in to Figma.
• Figma limits MCP tool calls by plan and seat. See Figma's rate limits.

For tokens: Node.js 18 or later, and nothing else. Token extraction reads only local files, so it needs no Storybook, MCP connection or sign-in.

This is the beginning of the README. Read the rest at the original. Read the full README ↗