Book a call

WritingAI-ready design systemsPart 14 of 20 in Making your design system AI-ready

Figma variables and code tokens out of sync? How to fix token drift before AI copies it

Design-to-code agents read Figma; coding agents read code. When the two disagree, both produce "correct" screens that don't match. Choose one source, reconcile every difference with a script, automate one direction and catch new drift within a day.

Diagram: Figma variables and code tokens compared line by line, with differences flagged, then a one-way sync from the token files to Figma.
On this pageThe problem: two sources of truth, two kinds of agent
  1. The problem: two sources of truth, two kinds of agent
  2. Step 1: choose one source of truth
  3. Step 2: reconcile once, with a script
  4. Step 3: automate one direction
  5. Step 4: catch drift in CI
  6. Name and structure rules that keep both sides aligned
  7. What changes for agents once drift is gone
  8. Common mistakes
  9. The short version
  10. Frequently asked questions
  11. Further reading

The short answer

When Figma variables and code tokens drift apart (different names, different values, tokens that exist on one side only), AI makes it worse: design-to-code agents read Figma's version, coding agents read code's version, and both produce "correct" output that doesn't match. Fix it in four steps. Pick one source of truth (usually the DTCG token files in code). Reconcile once: export both sides, compare them with a script, and decide every difference. Automate one direction: generate Figma variables from the token files, using Figma's DTCG import, a plugin such as Tokens Studio, or the Variables REST API. Check for drift in CI, so any new difference is caught within a day. Never let people edit both sides by hand.

  • Same structure, different separators: color/bg/surface in Figma, color.bg.surface in tokens, --color-bg-surface in CSS.
  • Check what your sync tool keeps: descriptions and some token types don't survive every export or import.
  • Part 14 of 20 in the series on AI-ready design systems.

The problem: two sources of truth, two kinds of agent

Almost every mature design system has some drift between Figma and code. A designer adjusted a grey in Figma last spring; an engineer added a token for a new chart that never made it into the library; a rename happened on one side only. People work around it. Agents can't, because each kind of agent only sees one side.

Figma
Text/Subtle#6B7280
Surface/Raised#FFFFFF
(missing)no chart tokens
Code
color.text.secondary#5A606B
color.bg.raised#FAFAF8
color.chart.1–8only in code
Result
Two "correct" screens that don't matchOne uses #6B7280 copied from Figma; one uses the token
Illustration Drift in Harbor. Different names stop agents connecting the two sides; different values mean the same name produces different colours.

There are four kinds of drift, and each causes a different agent failure:

KindExampleWhat agents do
Name driftText/Subtle vs color.text.secondaryCan't map the Figma variable to a token, so copy the hex value
Value driftSame name, #6B7280 vs #5A606BOutput looks "wrong" to designers even when the agent used the right token
Missing on one sideChart colours only in codeDesign-to-code invents colours; designers detach and hard-code
Structure driftModes in Figma (light, dark, compact) don't match themes in codeGenerated code ignores a theme, or applies the wrong one

Step 1: choose one source of truth

The single most important decision. Two-way sync, where people edit both sides and a tool tries to merge, sounds ideal and usually becomes a third source of conflicts. Choose one side people edit, and generate the other.

RECOMMENDED

Code is the source

DTCG token files in the design system repo. Changes are reviewed in pull requests, versioned with releases, and generate CSS, native platforms, the agent manifest and Figma variables. Best when engineers ship tokens and you need releases to be exact.

ALSO WORKS

Figma is the source

Designers edit variables in Figma; a pipeline exports them to DTCG files, which go through review before release. Best for design-led teams, as long as the export is automated and reviewed, not copied by hand.

Either way, the token files in the repo are what ships, what agents read, and what releases version. The question is only where people make edits. More on the wider practice in keeping Figma and code in sync.

Step 2: reconcile once, with a script

Before automating anything, make the two sides agree. Export both to the same format and compare them mechanically. Comparing by eye misses things.

  1. Export Figma variables as DTCG JSON

    Figma can export variables in the DTCG format natively (export works per mode), and plugins such as Tokens Studio can export too. Save one file per mode, e.g. figma-light.json.

  2. Build the code tokens for the same mode

    Resolved values, not aliases, so you compare final colours.

  3. Normalise names

    Convert both to dot-separated lowercase (Text/Subtle → text.subtle) and apply a rename map for known differences.

  4. Compare and list differences

    Only in Figma, only in code, same name with different values.

  5. Decide every difference

    A designer and an engineer go through the list together. Each line gets one decision: keep code, keep Figma, rename, add, or delete.

// scripts/token-drift.mjs: node token-drift.mjs figma-light.json dist/tokens-light.json
import { readFileSync } from "node:fs";

const RENAME = { "text.subtle": "color.text.secondary", "surface.raised": "color.bg.raised" };

// Flatten DTCG JSON into { "color.bg.surface": "#ffffff", … }
function flatten(node, path = [], out = {}) {
  for (const [key, val] of Object.entries(node)) {
    if (key.startsWith("$")) continue;
    const p = [...path, key.toLowerCase().replace(/\s+/g, "-")];
    if (val && typeof val === "object" && "$value" in val) out[p.join(".")] = normalise(val.$value);
    else if (val && typeof val === "object") flatten(val, p, out);
  }
  return out;
}
// Colours may be hex strings or DTCG colour objects; compare as lowercase hex.
const normalise = (v) => (typeof v === "object" && v?.hex ? v.hex : String(v)).toLowerCase();

const load = (f) => flatten(JSON.parse(readFileSync(f, "utf8")));
const figma = Object.fromEntries(Object.entries(load(process.argv[2])).map(([k, v]) => [RENAME[k] ?? k, v]));
const code = load(process.argv[3]);

const rows = [];
for (const k of new Set([...Object.keys(figma), ...Object.keys(code)])) {
  if (!(k in code)) rows.push(["only in Figma", k, figma[k]]);
  else if (!(k in figma)) rows.push(["only in code", k, code[k]]);
  else if (figma[k] !== code[k]) rows.push(["value differs", k, `${figma[k]} (Figma) vs ${code[k]} (code)`]);
}
console.table(rows);
process.exit(rows.length ? 1 : 0);

Adjust flatten to match how your exports are nested (some exports put the collection name at the top level). The output is the decision list for the reconciliation meeting, and later the CI check.

DifferenceTokenDetailDecision
value differscolor.text.secondary#6b7280 (Figma) vs #5a606b (code)Keep code: Figma's fails 4.5:1 on raised surfaces
value differscolor.bg.raised#ffffff vs #fafaf8Keep Figma: the change was intended, never shipped
only in codecolor.chart.1…8Added for reportsAdd to Figma
only in Figmacolor.promo.gradient-startUsed on one marketing bannerDelete; not a system decision
Illustration Every line needs a person's decision. Some differences are mistakes, some are improvements that never shipped.

Step 3: automate one direction

With the sides agreed, set up the pipeline so the generated side can't be edited by hand. For code as the source, there are three common ways to get tokens into Figma variables:

MethodHowGood forCheck
Figma's native DTCG importImport token JSON files into a variable collection in FigmaSimple setups; occasional updatesManual step; check which fields and types are kept
A plugin (e.g. Tokens Studio)The plugin reads token files from your Git repo and writes variablesTeams that want Git sync without writing codePlugin settings decide naming and modes; review them once
Figma Variables REST APIA CI job creates and updates variables on releaseFully automated pipelinesRequires an Enterprise plan; you maintain the script
Three sync options. Documented Figma's native import and export follow the DTCG format; community reports suggest some fields (such as descriptions) and composite token types may not round-trip, so test with your own files.

Whichever you choose, make the generated side clearly read-only for people:

  • Label the collection in Figma: "Generated from harbor/tokens. Don't edit here; request changes in #harbor."
  • Restrict edit access to the variables file to the people who run the sync.
  • Set code syntax on every variable as part of the sync, so Dev Mode and agents see var(--color-bg-surface) (part 8).
  • Copy descriptions into the variable description field, if your sync method supports it, so designers see the same guidance agents do (part 3).

Step 4: catch drift in CI

Drift comes back the moment someone edits the wrong side. Make it visible within a day.

Nightly jobExport Figma variables per mode (API or exported files committed by the sync)
→
Build tokensResolved values per mode from the repo
→
Comparetoken-drift.mjs
→
Differences?Open an issue for the system team with the table
A drift check. It doesn't fix anything automatically; it tells a person what changed, so they can decide.

If you can't automate the Figma export, a monthly manual export and a script run is still far better than nothing.

Name and structure rules that keep both sides aligned

ConceptTokens (DTCG)FigmaCSS
HierarchyNested groups: color.bg.surfaceSlashes: color/bg/surfaceHyphens: --color-bg-surface
ThemesToken sets or resolver contexts: light, darkModes on the semantic collection[data-theme="dark"]
PrimitivesA separate file or group, marked as primitiveA separate collection, hidden from publishingVariables used only by semantic ones
Descriptions$descriptionVariable descriptionAgent manifest; docs
One structure, three spellings. Mode names in Figma should exactly match theme names in code.

What changes for agents once drift is gone

BEFORE

Design-to-code

color: #6B7280; /* Text/Subtle */

The agent couldn't map Figma's name to a token, so it copied the value.

AFTER

Design-to-code

color: var(--color-text-secondary);

The Figma variable's name and code syntax match the token, so the agent writes the token.

Common mistakes

MISTAKE

Two-way sync with two editing sides

Conflicts multiply. One side is edited; the other is generated.

MISTAKE

Reconciling by eye

Two greys a few points apart look identical in a meeting. Compare values with a script.

MISTAKE

Assuming every field survives export

Descriptions, composite types and aliases may be dropped or flattened. Diff a round trip once before relying on it.

MISTAKE

Fixing drift without a check

A one-off cleanup drifts again within months. The CI check is what keeps it fixed.

The short version

  • Drift between Figma and code means design-to-code and coding agents produce different "correct" answers.
  • Choose one side people edit; generate the other. Usually DTCG token files in code are the source.
  • Reconcile once with a script, and decide every difference with a designer and an engineer.
  • Automate sync through Figma's DTCG import, a plugin or the Variables API, and make the generated side read-only.
  • Run a drift check on a schedule so new differences surface within a day.

Next: How do I make Figma Make, v0 and Lovable use my design system?

Frequently asked questions

How do I keep Figma variables and design tokens in sync?

Choose one source people edit (usually DTCG token files in code), generate the other with Figma's DTCG import, a plugin such as Tokens Studio or the Variables REST API, and run a scheduled comparison that flags any differences.

Can Figma export variables as DTCG JSON?

Yes. Figma supports importing and exporting variables in the DTCG format, with export done per mode. Check which fields are kept for your files, as some details may not survive a round trip.

Should Figma or code be the source of truth for tokens?

Either can work if only one side is edited by people. Code is the more common choice because changes are reviewed, versioned and released together, and agents read the code side.

Why does AI copy hex values from Figma instead of using tokens?

Usually because the layer isn't bound to a variable, or the variable's name and code syntax don't match a code token, so the agent has no way to map it. Bind values to variables named like your tokens and set code syntax.

How do I find differences between Figma and code tokens?

Export both to DTCG JSON for the same mode, flatten them to name-value pairs with normalised names, and compare with a script that lists tokens only on one side and values that differ.

Further reading