Figma Variables → Tailwind v4 Sync

Handing a Tailwind project real design tokens usually means someone retyping hex codes and spacing values from Figma by hand. It is slow, and the numbers drift the moment either side changes. There is a sharper failure mode too: a generated token name that happens to match one of Tailwind's own reserved keys — a color family and step, or a bare spacing number — silently overrides that built-in value everywhere in the project, not just where you meant to use it.

What it does

• Reads every Variable across every collection in a Figma file, plus local Text Styles for weight, line-height, and letter-spacing that Variables alone cannot represent
• Converts colors, font sizes, spacing, radius, and border values to their correct Tailwind CSS custom property, with px-to-rem and RGB-to-hex conversion handled for you
• Checks every generated name against Tailwind v4's reserved namespaces before writing anything: a bare numeric spacing key and a default-palette color family plus step are both silent, project-wide override risks
• Renames only the tokens that actually collide, and reports exactly what was renamed and why — nothing is silently dropped or silently overridden
• Writes directly into your existing @theme block, or creates one if none exists yet

How it works

1. Takes a Figma file URL and fetches every Variable and local Text Style in that file
2. Converts each one to a Tailwind v4 custom property using the correct prefix and unit
3. Runs the reserved-namespace collision check against Tailwind's default spacing scale and default color palette
4. Finds your Tailwind CSS entry file and writes the tokens into its @theme block, renaming only what collided
5. Reports collections and variable counts, text-style-derived tokens, and a full list of renamed versus kept-as-is tokens

Why the collision check matters

This is not a hypothetical edge case. A Figma spacing variable named by its raw pixel value (spacing/120 = 120px) looks harmless, but Tailwind v4 computes --spacing-120 as 120 times your base unit — 480px, not 120px — for every p-*, m-*, gap-*, and w-* utility that uses the number 120, anywhere in the project. A color variable named neutral/500 does the same thing to Tailwind's own gray scale. This skill catches both classes of collision before anything is written, not after something breaks in production.

What it is not

This is a one-way pull: Figma Variables and Text Styles into Tailwind CSS. It does not push Tailwind tokens back into Figma — for that direction, see the companion tailwind-to-figma skill. It also does not touch component structure, layout, or anything outside variables and text styles. For collections with several modes (light and dark, for example), only the default mode is written, and the report names the mode used.

Requirements

Runs inside an agent connected to the official Figma MCP server — the same connection used for implementing Figma designs as code. Connection steps differ by agent and client — see https://www.figma.com/mcp-catalog/ for setup guides. Requires a Tailwind CSS v4 project (the @theme directive); v3 projects using tailwind.config.js are not supported.