For eight months after we launched tokens, Northwind had two truths. The JSON in the repository said the action blue was #1f5ae0; the Figma library said #2160e8, because a designer had nudged it for a campaign mockup and published. Engineers built from the inspect panel, so the marketing site shipped one blue and the app another. Tokens solve consistency only if design files and code read from the same decisions.
Figma variables hold reusable values such as colors and numbers, grouped into collections. A collection can have several modes, each giving every variable in the collection a different value. A variable can also alias another variable. That’s enough to mirror the token architecture almost one to one:
\n| Token concept | \nFigma | \n
|---|---|
| Primitive tier | \nCollection “Primitives”, one mode | \n
| Semantic tier | \nCollection “Semantic”, modes Light and Dark | \n
| Density | \nCollection “Density”, modes Comfortable and Compact | \n
| Brand | \nAn extended collection per brand (Enterprise), or a Brand collection with modes | \n
Alias {color.blue.600} | \nVariable aliasing blue/600 | \n
Variable names use slashes to form groups, so color/action/bg appears as a group path in the picker and corresponds to the token color.action.bg. Figma frames pick modes the way the CSS attribute selectors do: a frame can set a mode explicitly, and anything inside it on Auto inherits that mode, so a dark hero frame on a light page works just like data-theme="dark" on a section.
For brands, Figma’s extended collections, available on the Enterprise plan, let you create a Tidewater collection that inherits from the Northwind semantic collection and overrides only the brand variables. Updates to variables that Tidewater didn’t override flow through automatically. On other plans, a separate Brand collection with one mode per brand gets you most of the way.
\nTwo settings matter more than any naming scheme. First, hide primitives from publishing. The semantic collection can still alias them, but designers in product files only see semantic variables, which is exactly the rule components follow in code. Second, give every published variable code syntax: Dev Mode then shows var(--nw-color-action-bg) instead of a hex value, so what the designer picked is literally what the engineer types. Scoping helps too: restrict color variables to the properties they’re meant for, so a text color doesn’t appear in the fill picker.
Designers still design in Figma; they just don’t publish token values directly. A change starts in a branch of the library file (branching is available on Figma’s Organization and Enterprise plans), where the designer can try it in real mockups. When it’s ready, the changed modes are exported as JSON: Figma can export and import a collection’s modes in the DTCG format. The export becomes a pull request against the tokens repository, where CI runs the checks from Section 2 and a core designer and engineer review it. After release, the released JSON is imported into the main library file and the library update is published.
\nSome teams automate the last step with a plugin or Figma’s REST API. Northwind does it by hand once per release; it takes ten minutes, and a human glancing at the variables panel has caught two bad imports.
\n\nThe same loop works for components, with Code Connect linking Figma components to their code in Dev Mode. In the exercise, you put the steps of a token change in order. Next, you version those releases so teams know what an update will do to them.
\n","toc":[{"id":"sec-1","text":"Mapping tiers to Figma variables","level":2},{"id":"sec-2","text":"Make the right variable the easy one","level":2},{"id":"sec-3","text":"The sync loop","level":2}],"takeaways":["Map token tiers to Figma variable collections, and map themes, brands and density to modes or extended collections.","Pick one source of truth for token values and make the other side a mirror that is updated by a defined process, never by hand.","Give semantic variables code syntax and hide primitives from publishing, so designers pick the same names engineers type.","Library updates are releases too; designers accept them in their files the way engineers bump a package version."],"further":[{"title":"Guide to variables in Figma","url":"https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma"},{"title":"Modes for variables (Figma)","url":"https://help.figma.com/hc/en-us/articles/15343816063383-Modes-for-variables"},{"title":"Extend a variable collection (Figma)","url":"https://help.figma.com/hc/en-us/articles/36346281624471-Extend-a-variable-collection"},{"title":"Guide to libraries in Figma","url":"https://help.figma.com/hc/en-us/articles/360041051154-Guide-to-libraries-in-Figma"}],"quiz":[{"q":"Northwind’s designers can pick any primitive like blue/600 from the library, and mockups keep using primitives where semantic tokens belong. What’s the best fix?
A designer changed color/action/bg in Figma last week, and an engineer changed the same token in the JSON yesterday, to a different value. What process failure does this show?
How should Northwind represent its two brands in Figma on an Enterprise plan?
","options":[{"text":"Duplicate the whole library for Tidewater and maintain both by hand.","why":"Duplicated libraries drift apart, which is the problem the system exists to solve."},{"text":"Put brand colors directly on each component as overrides.","why":"Overrides on components bypass variables, so themes and code mapping stop working."},{"text":"Extend the semantic collection for Tidewater and override only the brand variables.","why":"Correct. An extended collection inherits everything it doesn’t override, so shared changes still reach both brands."},{"text":"Store brand colors as text styles.","why":"Text styles describe typography, not colors, and don’t map to modes or tokens."}],"answer":2}],"exercise":{"kind":"order","items":["propose","export","ci","review","release","sync"],"title":"Ship a token change from Figma to code and back","prompt":"A Northwind designer wants to darken color/text/subtle because it fails contrast in the Tidewater dark theme. The JSON in the tokens repository is the source of truth, and the Figma library is a mirror. Put the steps of the change in order.
The designer explores in a branch, so nothing published changes yet. The exported JSON enters the source of truth through a pull request, where CI validates names, references and contrast and builds every platform. Humans review with that evidence, the release publishes a new version with a changelog, and only then is the released JSON imported into the main library and published, so Figma mirrors exactly what shipped.
\n","checkLabels":{},"itemText":{"propose":"Designer tries the darker value in a branch of the Figma library file","export":"Export the changed modes as DTCG JSON and open a pull request in the tokens repository","ci":"CI runs the naming, reference and contrast checks and builds CSS, Swift and Kotlin","review":"A core designer and engineer review the pull request and its visual diffs","release":"Merge and publish a new tokens version with a changelog entry","sync":"Import the released JSON into the main library’s variables and publish the library update"}},"words":725,"readMinutes":3}