Tokens to Figma

Mirror the code's tokens in a Figma file as variables: primitives as raw values, semantic tokens as aliases with a Light and a Dark mode. Code stays the source of truth. Figma follows it, by name, and every write is checked by reading it back.

What it needs

Check all of these first. If one is missing, say what and stop.

1. The Figma MCP server, connected, with its use_figma tool. That tool runs Plugin API scripts in the file; it is how variables get written. Read-only Figma access is not enough.
2. Figma's figma-use skill, if your agent has it. Load it before the first use_figma call, every session. Skipping it causes failures that are hard to trace.
3. A Figma file URL with edit access. This skill writes into an existing file; it doesn't create one. With some setups the file must also be open in the Figma desktop app.
4. A Figma plan with variable modes (Professional or above). Starter files can't add a Dark mode, so 02 Semantic can't hold Light and Dark there. On Starter, say so and stop.
5. Tokens in the code, readable: a tokens JSON file, a Tailwind v4 @theme block, or :root and dark-mode custom properties. Ideally already split into primitives and semantic tokens (see token-foundations).

If the MCP server or use_figma isn't available, write a short status ("not synced: Figma MCP unavailable") and stop. Never describe a sync that didn't happen.

Steps

1. Read the tokens from code

Collect every token with its value per mode:

• Primitives: colour scales, spacing, radius, container widths, durations, easings.
• Semantic tokens: each colour role with its light and dark value, recorded as a reference to a primitive (--color-action-primary → brand-600 light, brand-500 dark).
• Component tokens: button and input heights, card padding, component radii.

Resolve var(…) chains so you know which primitive each semantic token points at. If a semantic token holds a raw value instead (white, a hex), list it. It can't become an alias until a primitive for it exists in code.

2. Build the name map

Code uses kebab-case CSS variables; Figma uses slash-separated PascalCase. One token, one variable, one name in each place:

Code	Figma
--color-brand-500	Color/Brand/500
--color-background	Color/Background
--color-surface-default	Color/Surface/Default
--color-action-primary-hover	Color/Action/Primary Hover
--spacing-4	Spacing/4
--radius-md	Radius/Md
--duration-fast	Duration/Fast

Show the map. Offer to save it in the repo (for example design-system/figma-map.json) so later runs and drift checks match by the same names. Ask before adding the file.

3. Inspect the file

With use_figma, list the file's variable collections, their modes and their variables. Sort every token into one of three:

• Exists and matches: skip it.
• Exists and differs: update it, matched by name.
• Missing: create it.

If the file already holds variables, ask which it is: update in place, or create only (leave every difference alone and list it for review). Never touch variables that aren't in the map.

4. Plan the collections

Collection	Holds	Modes
01 Brand	Primitive colour scales: brand, neutral, accent, state	one
02 Semantic	Semantic colour roles, each an alias to a 01 Brand variable	Light, Dark
03 Component	Button and input sizes, card and section padding, component radii	one, or Light and Dark if values differ by theme
04 Layout	Spacing, radius scale, container widths	one
05 Motion	Durations (number), easings (string)	one

Types: colours are COLOR, sizes and durations are FLOAT, easings and font families are STRING.

Scopes, so each variable only shows up where it belongs:

Variables	Scopes
Colour (default)	FRAME_FILL, SHAPE_FILL, TEXT_FILL, STROKE_COLOR, EFFECT_COLOR
Color/Text/*	TEXT_FILL
Color/Border/*	STROKE_COLOR
Color/Background, Color/Surface/*	FRAME_FILL, SHAPE_FILL
Spacing/*	GAP
Radius/*	CORNER_RADIUS
Container/*	WIDTH_HEIGHT

Show the plan with counts (create, update, skip, conflicts) and wait for a yes.

5. Write, one collection per call

Order: collections, then modes, then 01 Brand, 02 Semantic, 03 Component, 04 Layout, 05 Motion, then scopes. One use_figma call per collection keeps each call small and each failure contained.

A new collection starts with one mode. Rename it Light and add Dark where the plan says two.

Figma stores colour as sRGB from 0 to 1, so convert each OKLCH value inside the script. The plugin runtime has no colour library; ship the conversion inline:

function oklchToRgb(L, C, H) { // L in %, returns Figma {r, g, b, a} plus clamped: true if out of sRGB
  const Lp = L / 100, a = C * Math.cos(H * Math.PI / 180), b = C * Math.sin(H * Math.PI / 180);
  const l = (Lp + 0.3963377774 * a + 0.2158037573 * b) ** 3;
  const m = (Lp - 0.1055613458 * a - 0.0638541728 * b) ** 3;
  const s = (Lp - 0.0894841775 * a - 1.2914855480 * b) ** 3;
  const lin = [4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
              -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
              -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s];
  const enc = v => v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055;
  const clamped = lin.some(v => v < -1e-4 || v > 1 + 1e-4);
  const [r, g, bl] = lin.map(v => Math.max(0, Math.min(1, enc(v))));
  return { r, g, b: bl, a: 1, clamped };
}

Pass Figma only { r, g, b, a }. Where clamped is true, the value was outside sRGB: list it in the report.

Find or create by name, never blindly create:

const cols = await figma.variables.getLocalVariableCollectionsAsync();
const brand = cols.find(c => c.name === "01 Brand")
  ?? figma.variables.createVariableCollection("01 Brand");
const vars = await figma.variables.getLocalVariablesAsync("COLOR");
const find = name => vars.find(v => v.name === name && v.variableCollectionId === brand.id);

const v = find("Color/Brand/500") ?? figma.variables.createVariable("Color/Brand/500", brand, "COLOR");
const { clamped, ...rgba } = oklchToRgb(60, 0.18, 250);
v.setValueForMode(brand.defaultModeId, rgba);
v.scopes = ["FRAME_FILL", "SHAPE_FILL", "TEXT_FILL", "STROKE_COLOR", "EFFECT_COLOR"];

Semantic variables hold aliases, never raw colours. Set one per mode:

semanticVar.setValueForMode(lightModeId, figma.variables.createVariableAlias(brand600));
semanticVar.setValueForMode(darkModeId, figma.variables.createVariableAlias(brand500));

That way a change to a brand primitive flows through every role that uses it.

6. Read back after every call

After each collection, read the variables again with use_figma and confirm:

• each variable exists, in the right collection;
• every mode has a value;
• scopes match the plan;
• each semantic alias resolves to the right primitive, in both modes.

Mark anything that fails as failed. Count only what the read-back confirmed.

7. Styles, only if asked

Variables carry single values. If the user also wants local styles, the same rules apply:

• Text styles (Display, Heading, Body, Caption, Label) match the code's type scale exactly: same sizes, line heights, weights and letter spacing.
• Effect styles (Shadow Xs to Xl, Focus Ring) take their colour from a variable, never a raw value.

Match by name, write, read back, as above.

8. Report

## Tokens to Figma

File: <url>
Mode: <update in place | create only>

| Collection | Created | Updated | Skipped | Failed |
|---|---:|---:|---:|---:|
| 01 Brand | | | | |
| 02 Semantic | | | | |
| ... | | | | |

Verified by read-back: <N of M>
Conflicts left for review: <list, or "none">
Out-of-gamut colours clamped: <list, or "none">
Raw values that couldn't alias: <list, or "none">
Tokens Figma has that code doesn't: <list, or "none">

Checking drift later

Read-only. Compare the file against the name map and today's code:

• Missing in Figma: in code, not in the file.
• Extra in Figma: in the file, not in code.
• Value mismatches: different value, missing mode, wrong scope, or an alias pointing at the wrong primitive.

Report every item, even minor ones. Partial is not in sync. Fix drift by changing code first and re-running, never by editing Figma alone.

Never

• Call use_figma before loading figma-use, when your agent has it.
• Claim a variable was written without reading it back.
• Pretend to sync when the MCP server is unavailable.
• Create a duplicate. Match by name and update in place.
• Invent a Figma-only token. Add it in code and the name map first.
• Store a raw colour in a semantic variable. Alias it to a primitive.
• Overwrite or delete Figma variables that aren't in the map.
• Ship a semantic collection without both Light and Dark modes.

Red flags: you're about to fake a sync

• "The script ran without errors." That isn't proof. Read the variables back.
• "I'll create them all fresh, it's quicker." That duplicates. Find by name first.
• "This one colour is only for Figma." Then it isn't a token yet. Put it in code first.