Mastering Figma Variables: The Complete 2026 Playbook
12/6/2026 · 14 min read
Figma Variables launched quietly and changed everything. Two years in, most teams are still using 10% of what the feature can do. This is the complete guide — from first collection to production code sync.
Variables are Figma's native implementation of design tokens. Unlike Styles (which only handle static values), Variables are dynamic — they support multiple modes, can be referenced by other variables, and can drive conditional logic in prototypes. If you're still using Styles for color and spacing, you're building on a foundation that doesn't scale.
Variables vs Styles: What's the Actual Difference?
Styles are static, single-value properties. A color style called "Brand/Primary" always resolves to one hex value. No modes, no conditionals, no references.
Variables are dynamic. A color variable can have a Light value and a Dark value. Switch the mode — every frame using that variable updates instantly.
Variables can reference variables. A semantic token color/surface/default can point to a primitive color/neutral/0. Change the primitive and the semantic updates. This is the foundation of a real token architecture.
Variables drive prototype logic. Show/hide elements, swap component variants, change layouts — all based on variable values without a single line of code.
Collections: Structuring Your Variable Library
Collections are the top-level organiser. Each collection can have multiple modes. Think of a collection as a token tier, and modes as the variants within that tier.
Recommended Collection Structure
Primitives — One mode only. Contains every raw value in your system: the full color palette, every spacing step, every radius, every type size. No references to other variables. No modes needed — primitives don't change.
Semantic — Two modes: Light and Dark (or more if you have additional themes). All values reference Primitives. This is where surface colors, text colors and border roles live.
Brand — One mode per brand. Values reference Primitives. This collection overrides the brand-specific semantic tokens when a different brand is active.
Spacing/Scale — Often a single mode. Contains spacing, sizing, radius and elevation values referenced by components.
Component — Optional. Component-specific variables that reference Semantic tokens. Useful for complex components with many states.
Naming Conventions That Actually Work
Figma uses forward-slash grouping. color/brand/primary creates a group called "color", subgroup "brand", token "primary". Consistency here is not optional — it directly affects how Figma exports to code.
Modes are where Variables earn their keep. A mode is a named variant of all the values in a collection. Switch the mode on a frame and every variable in that frame resolves to its mode-specific value.
Setting Up Dark Mode in 5 Minutes
Open your Semantic collection. Click the "+" next to Modes at the top — you likely have "Light" already. Add "Dark".
For each variable, set the Dark value. color/surface/default Dark = {color/neutral/1000}. color/text/primary Dark = {color/neutral/0}.
Select a frame. In the Design panel, find the Variables section. Click the mode selector next to your Semantic collection. Switch to Dark.
Every element in that frame using semantic variables now shows dark mode. No duplicate frames. No manual recoloring.
Beyond Light/Dark: Advanced Mode Use Cases
Density modes: Compact / Default / Comfortable — use spacing variables with three modes. One toggle changes all padding and sizing throughout a complex form.
Platform modes: Web / iOS / Android — typography scales and border radii differ. One Spacing collection with three modes outputs platform-correct values for all three.
Breakpoint modes: Mobile / Tablet / Desktop — frame width variables drive responsive layout logic in prototypes without separate artboards.
State modes: Default / Error / Success — for form components, a State collection with modes drives the entire visual feedback system from a single toggle.
Variable Types: Beyond Color
Most tutorials only cover color variables. In practice, the other types are equally important.
Number variables — spacing, radius, elevation, font size, font weight, line height, opacity. Anything numeric. These are the most underused type and they unlock fully consistent spacing systems.
String variables — text content, font families, URLs. String variables drive content-swapping in prototypes (multilingual demos, A/B test variants) without duplicate frames.
Boolean variables — visibility, conditional logic. Bind a boolean variable to "Visible" on any layer. Toggle the variable in a prototype interaction to show/hide entire sections without component variants.
Number Variables for Spacing
/* Collection: Spacing — No modes needed */
spacing/4 → 4
spacing/8 → 8
spacing/16 → 16
spacing/24 → 24
spacing/32 → 32
spacing/48 → 48
spacing/64 → 64
/* Collection: Radius */
radius/sm → 4
radius/md → 8
radius/lg → 16
radius/full → 9999
/* Apply in Figma: */
/* Select auto-layout frame → padding fields → click the variable icon → pick spacing/16 */
/* Now spacing/16 is the source of truth. Change it once, everything updates. */
Code Sync: Variables → Tokens → Production
The point of Variables is that they become the single source of truth for both design and code. Here's the production workflow.
Option 1: Tokens Studio Plugin
Tokens Studio (formerly Figma Tokens) reads your Variables and writes them to a JSON file in the W3C design token format. Connect it to a GitHub repo — every time you publish tokens from Figma, a PR is automatically opened with the updated token file. Your CI/CD runs Style Dictionary to transform tokens and ships updated CSS variables.
Option 2: Figma REST API
// Fetch Variables from Figma API
const response = await fetch(
`https://api.figma.com/v1/files/${FILE_KEY}/variables/local`,
{ headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN } }
);
const { variables, variableCollections } = await response.json();
// Transform to W3C token format
const tokens = transformFigmaVariables(variables, variableCollections);
// Write to token files, run Style Dictionary
fs.writeFileSync('tokens/figma-output.json', JSON.stringify(tokens, null, 2));
execSync('style-dictionary build');
Option 3: Figma Dev Mode (Built-in)
In Dev Mode, hovering a layer shows its resolved variable values alongside the CSS. Developers can copy variable names directly and use them in code. No plugin required — but this is a manual process, not an automated pipeline.
Variables in Prototypes: The Underrated Superpower
Variables make Figma prototypes dramatically more realistic without the complexity of component variants.
Form validation: A boolean variable form/hasError controls the visibility of error states across an entire form. One interaction toggles the variable; all error labels appear simultaneously. No 16 variant combinations.
Theme preview: Add a Semantic mode selector to your prototype start screen. Clicking "Dark" sets the Semantic collection mode — the entire prototype switches theme live, in the browser, in front of stakeholders.
Dynamic content: String variable user/name bound to text layers. One interaction changes the variable; "Hello, User" becomes "Hello, David" throughout the prototype.
Counter/cart logic: Number variables track quantity, cart total, step progress. Variables increment on click. Real interactive logic without code.
Conclusion
Figma Variables aren't a nice-to-have — they're the foundation of a professional design workflow in 2026. Collections map to token tiers. Modes replace duplicate frames. Number variables enforce spacing consistency. And a proper sync pipeline means designers change a value in Figma and it ships to production without a single Slack message. The teams using Variables at this depth are shipping faster, with fewer design/development discrepancies, and with significantly less rework. Start with one collection, one semantic layer, one dark mode. The rest follows naturally.
