Figma Variables are Figma’s native home for design tokens: named values, grouped into collections, with one value per mode. They are the closest thing a design file has ever had to the token tiers a codebase already uses — which means, for the first time, the two can be described in the same shape.

This guide covers the four concepts that actually matter (collections, modes, aliases and scoping), how they line up with a three-tier token system, and the part most teams get stuck on: getting tokens into a file and keeping them there.

The four concepts

Variables: A named value of one of four types — colour, number, string or boolean. space/4 is a number; action/primary is a colour. Slashes in the name create folders in the UI, which is how you get structure without a separate grouping concept.
Collections: A set of variables that share the same list of modes. This is the unit that matters most for structure: a collection is the natural home for one tier of a token system, because a tier is exactly a group of values that vary together.
Modes: Columns within a collection. One variable, several values — light and dark being the obvious pair, but density, brand and locale work the same way. A frame can be set to a mode, and everything inside it resolves against that mode.
Aliases: A variable whose value is another variable. This is the single most important feature for token work: an alias is the arrow in action-primary → indigo-600, and without it a Figma file has a list of values rather than a system.

Scoping, briefly

Each variable can declare where it may be applied — a colour restricted to Frame fill and Shape fill will not be offered as a text colour. Scoping is quiet, unglamorous, and the thing that makes a large collection usable: without it, every colour picker in the file offers every colour in the system.

Mapping token tiers onto collections

The structure that holds up at scale is one collection per tier, with modes only where the tier genuinely varies:

Collection	Modes	Contents
Primitives	One (no modes)	The raw ramps and scales — `indigo/600`, `space/4`. A primitive has one value; it does not change between themes.
Semantic	Light, Dark	The roles — `action/primary`, `surface/raised`, `text/muted`. Every value here is an alias to a primitive, and the two modes alias to different ones.
Component	One (no modes)	Optional, and only where a component diverges: `button/bg → action/primary`. Aliases to semantic, never to primitives.

Why light and dark should not be two colour styles

Before Variables, dark mode in Figma meant duplicating a page and swapping styles, or maintaining two libraries. Modes replace that entirely: one component set, one frame-level switch. But the benefit only lands if the semantic tier exists.

Bind a button’s fill to indigo/600 and it is indigo in every mode. The mode switch does nothing.
Bind it to action/primary, which aliases indigo/600 in Light and indigo/400 in Dark, and the same component is correct in both. Nothing about the component knows a theme exists.

The second is the entire reason to adopt Variables. A file that binds components straight to primitives has taken on the migration cost without collecting the benefit.

Getting tokens into a file

Figma’s UI can create variables by hand, which is fine for twenty and unbearable for four hundred. The realistic options:

By hand. Viable for a first pass at the semantic tier. Not viable for primitives, where a single colour family is ten values and a system has several families.
A plugin that imports a token file. The common path. Works well; the catch is that the token file itself has to come from somewhere, and if it is hand-maintained you have moved the manual work rather than removed it.
Generated from the system, re-runnable. The variables are compiled from the same model the code exports come from, and running the sync again updates the existing variables in place rather than creating a second set beside them.

The third is what Arkitype’s free companion plugin does. Arkitype Figma Sync, on the Figma Community, turns a system built in the builder into a real file: both collections with their modes, aliases intact, a page per component, and documentation. Re-run it after any change and it updates the file you already have.

The in-place requirement

Whichever route you take, this is the property to check before committing to it. A sync that creates Primitives 2 beside Primitives has not synced anything — it has forked your system, and now every component in the file is bound to the old copy. “Updates in place” is the difference between a pipeline and a one-time import.

Variables and code: what still does not happen automatically

Figma can export variables, and plugins can push them into a repository. What none of that establishes is agreement: nothing in the toolchain notices when the shipped CSS stops matching the file. Variables make the design side describable; they do not make the two sides reconcile.

The practical mitigation is to make one artefact upstream of both. If the Figma variables and the Tailwind theme and the CSS custom properties are all generated from the same source, they cannot disagree — not because anyone is disciplined, but because there is only one place a value is written.

Same source, three destinations

design system (one model)
   ├── Figma Variables   →  collections, modes, aliases
   ├── CSS / Tailwind    →  custom properties, theme keys
   └── documentation     →  the styleguide everyone reads

Nothing is transcribed. Every arrow is generated.

A short checklist

One collection per tier; modes on the semantic tier only.
Every semantic variable is an alias, not a literal value.
Components bind to semantic or component variables — never to primitives.
Scope variables so pickers stay short and misuse is hard.
Name with slashes to build the folder structure you actually want to navigate.
Whatever generates the variables must be able to re-run into the same file.

Figma Variables, and how design tokens reach them