Figma Variables and Libraries, in Sync with Code

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.

Mapping tiers to Figma variables

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:

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.

Make the right variable the easy one

Two 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.

The sync loop

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.

Some 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.

The 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.