How to Use Variables in Figma: A Practical Guide for 2026
Variables are the single biggest upgrade to how we build in Figma since auto layout. They are also where most libraries quietly go wrong: a few hundred colours with no structure, modes added as an afterthought, and developers who still copy hex codes from the inspect panel.
This guide is the setup we use on client projects. It works for a two-screen landing page and for a product with dark mode and three brands.
What a variable is (and what it is not)
A variable stores one reusable value. Figma has four types:
- Color, for fills, strokes, text and effects
- Number, for spacing, radius, sizes, opacity and type metrics
- String, for text content and font names
- Boolean, for true or false values, mostly used to show or hide layers and in prototypes
The difference from styles is simple. A variable holds a single raw value that can change by mode. A style can hold a composite, like a gradient, a full text style or a stack of shadows. You will use both. Variables become the source of truth for values, and styles wrap them where you need composites.
Variables live in collections, and a collection can hold up to 5,000 variables. Inside a collection you organise them in groups, which you can nest. Groups become the slashes in a variable name, like color/text/primary.
Step 1: Build primitives first
Primitives are your raw palette. They have no opinion about where they are used.
Create a collection called Primitives and add:
color/neutral/0tocolor/neutral/950color/brand/50tocolor/brand/900color/red/…,color/green/…and any other hues you needspace/0,space/2,space/4up tospace/96radius/0,radius/4,radius/8,radius/full
Two rules save pain later. Name primitives by what they are, never by what they do (brand/600, not button-blue). And keep this collection to one mode. Primitives do not change between light and dark; what changes is which primitive you point to.
Step 2: Add semantic variables that alias primitives
Semantic variables describe a job: the colour of body text, the background of a card, the border of an input. They do not contain values of their own. They alias a primitive.
Create a second collection called Theme with groups like:
color/bg/canvas,color/bg/surface,color/bg/inversecolor/text/primary,color/text/secondary,color/text/on-brandcolor/border/default,color/border/strongcolor/action/primary,color/action/primary-hovercolor/status/error,color/status/success
To alias, open a value, right-click and choose Create alias, then pick the primitive. When the primitive changes, every semantic variable pointing to it changes too.
Designers should only ever apply semantic variables to layers. If someone fills a card with neutral/50 directly, dark mode will break for that card. This one habit decides whether your theming works.
Step 3: Use modes for themes, not for everything
A mode is an extra column of values in a collection. The classic use is light and dark: in the Theme collection, add a Dark mode next to Light, and point each semantic variable to a different primitive.
color/text/primary aliases neutral/950 in Light and neutral/50 in Dark. Switch a frame’s mode and every layer follows.
Modes also work for:
- Brands: one
Themecollection with a mode per brand, if the brands share structure - Density: a
Spacingcollection with Comfortable and Compact modes - Platforms: type sizes that differ between web and mobile
Check your plan before you design a mode-heavy system. Mode counts per collection depend on the plan: up to 10 on Professional, up to 20 on Organization, and Enterprise can go further with extended collections. If you need dark mode times four brands, that is eight values per variable, and you will want to split the problem into two collections rather than one huge one.
Step 4: Scope every variable
Scoping limits where a variable appears in the pickers. Without it, a designer setting a corner radius sees your 120 colour variables and 40 spacing values, and picks the wrong one.
Set scopes when you create the variable:
- Text colours: Text fill only
- Surface colours: Frame fill and Shape fill
- Border colours: Stroke
- Spacing numbers: Gap and Padding in auto layout
- Radius numbers: Corner radius
It takes ten minutes for a whole collection and removes a class of mistakes forever. Hide primitives from publishing entirely if you can, so people cannot apply them by accident.
Step 5: Add code syntax
Each variable can carry a code name for Web, Android and iOS. Dev Mode shows that name in code snippets instead of a raw value.
Match the names your developers already use. If the codebase has --color-text-primary in CSS, set exactly that as the Web code syntax. It turns handoff from “what colour is this?” into a copy and paste, and it makes design reviews faster because everyone reads the same names.
Step 6: Bind variables in components
Now apply the variables where they matter:
- Auto layout gaps and padding bound to
space/… - Corner radius bound to
radius/… - Fills, strokes and text bound to semantic colours
- Boolean variables for optional elements you want to toggle in prototypes
Test it by switching a component frame to Dark mode. Anything that does not flip is still using a raw value or a primitive. Fix those before publishing.
Step 7: Publish and set rules for change
Publishing variables as a library needs a paid plan. Once published, treat changes like code changes:
- Never rename a published variable without telling the team, because names are what developers reference.
- Add new variables instead of repurposing old ones.
- Write a one-line description on each semantic variable so new designers know when to use it.
- Keep a changelog in the library file.
Common mistakes we fix in client files
- One collection for everything. Primitives, themes and spacing mixed together, with modes that only apply to half the variables. Split them.
- Semantic names that are really primitives.
color/blue-buttonis a primitive with a job description. Name the job:color/action/primary. - Too many semantic tokens. If you have
text/primary,text/mainandtext/default, people will guess. Fewer, clearer names win. - Variables with no scope. Every picker shows everything, and wrong values creep in.
- Hex codes in components. The library looks right in light mode and falls apart the moment someone tests dark mode.
A quick checklist
- Primitives in their own collection, one mode, not applied directly
- Semantic variables alias primitives and carry the modes
- Every variable scoped
- Code syntax matches the codebase
- Components bound to semantic variables only
- Mode count fits your Figma plan
If your library already exists and is a tangle of styles, local colours and half-migrated variables, start with an audit before you add anything. We do this regularly as part of our design system work, and the next step after variables is usually building components that use them well.