Figma lets you store a color, number, string or boolean once and bind it to design properties and prototype actions. Edit the stored value and every layer using it follows.
Design system teams use variables mainly for light and dark themes. Spacing scales and brand tokens go in there too, and prototypers use them to drive conditional logic.
Some guides still say Starter files cannot use them. They’re out of date. As of October 2026, Figma’s Help Center states that anyone on any plan can create and edit variables. Paid or Education plans are where extra modes per collection come in. Variables in prototypes and publishing to team libraries sit behind the same wall.
What are Figma variables?
Figma’s Help Center describes them as raw values (color, numbers, strings) that change with context, such as light and dark or mobile and desktop. Bind one to a property or a prototype action and a single edit updates every layer that uses the value.
What a variable can bind to depends on its type.
- Color variables go on fills, strokes, gradient stops, shadow effects, color styles and other color variables.
- Numbers cover width and height, spacing, padding and corner radius. Decimals work up to the hundredth place, such as 12.75.
- Strings handle text content, font family and font weight.
- Booleans control layer visibility. True shows the layer and false hides it.
Timing and easing variables exist too, but only for Figma Motion, so the Help Center’s full list runs to six types. Design work and prototypes only touch the four above.
Variables are how Figma stores a design token, meaning a reusable value that keeps design and code in sync. Alias one variable to another and you get the token structure of a design system.
Composite values are the exception. A shadow with several parameters, or a full text definition, still belongs in a style.
Variables also publish to team libraries, and when a value changes in the source file, designs in other files can pick up the update.
Have you seen the latest Figma statistics?
Discover comprehensive Figma statistics including revenue growth, market share, user demographics, and funding data.
Check them out →How to create and apply Figma variables
Creation happens in the variables view. Applying happens in the right sidebar, one property at a time.
- Click Variables in the left navigation bar to open the variables view. In the older interface, press Esc to deselect everything on the canvas, find Local variables in the right sidebar and click Open variables.
- Inside a collection, click + Create variable and pick a type.
- Name the variable. Slashes build groups, so Base/Primary/10 sorts into a Base group.
- Enter a value: a hex code for color, a plain number for spacing.
- Select a layer and open the variable picker on the property you want to bind.
Where the picker lives depends on the type. Color variables show up in the fill and stroke fields. Strings sit in the font family and weight dropdowns, and for a boolean you right-click the visibility icon in the Appearance section.
Number variables bind to padding and gap inside auto layout frames, so a whole spacing scale can live in one collection.
One thing catches people out. Dragging the on-canvas padding or gap handles of an auto layout frame detaches the applied number variable, according to the Help Center.
Change the value in the variables view and leave the handles alone.
How do collections and modes work?
Related variables go into a collection, and inside it each variable carries one value per mode. Switch a frame from Light to Dark and every bound value swaps at once.
Collections and groups
Figma’s own example puts localized text in one collection and spatial values in another.
Groups split a collection further, with text colors in one group and stroke colors in another. A file might end up organized like this:
- Color primitives
- Semantic theme colors
- Spacing and radius
- Localized text
Every variable in a collection shares the same set of modes, which is why one job per collection works best.
Modes for light and dark themes
Each mode holds one value for every variable in the collection. Apply a mode to a frame and every bound layer inside it shows that mode’s value.
- A theme collection might have Light and Dark modes, each holding its own color values.
- A device collection might have Mobile and Desktop modes, each holding its own number values.
The device pattern is what carries breakpoint values for responsive design, which is also where mode caps start to hurt.
Mode limits by plan
As of October 2026, Figma’s plan comparison page lists these caps:
- Professional gets up to 10 modes per collection.
- Organization goes up to 20.
- Enterprise has unlimited modes with extended collections.
- A single collection tops out at 5,000 variables (Figma Help Center).
Older guides still quote 4 modes for Professional and Organization, and 40 for Enterprise. Figma’s Schema 2025 recap confirms the jump from 4 to 10 and 20, announced in late October 2025.
Modes need a paid or Education plan. The Help Center lists Education, Professional, Organization and Enterprise as the plans that can create and use modes, while variables themselves work on any plan, so Starter files stay on one default mode.
If you are weighing the free tier against Professional, modes decide it for any theming work.
How to structure variables with aliases, scopes and naming
Alias primitives into semantic variables, and semantic variables into component variables, so a brand change edits one layer. A variable can only reference another variable of the same type, per the Figma Help Center.
Primitive, semantic and component layers
- Primitives hold a raw value with no meaning attached, such as brand-400 holding #EAEA00.
- Semantic variables carry a role name and alias a primitive, so icon-default might point at brand-400.
- Component variables belong to a single component, like button/primary/background.
Figma’s Help Center walks through the first two layers with exactly that example. If brand-400 changes, icon-default follows as long as it stays bound to it.
Building a design system in Figma starts with the primitive collection, because every other layer aliases into it.
I’d start with two layers. Add the component layer only when a component has to diverge from its shared role, and read Figma components best practices before the layers multiply.
Naming conventions
Name semantic variables by role and primitives by value. The rest is housekeeping.
- Slashes create groups, so color/surface/default nests under color and surface.
- Pick one casing style and use it in every collection.
- Descriptions can carry intent where the name cannot.
- Code syntax holds the platform-specific name, such as a CSS custom property.
Scopes
Scopes limit which properties a variable can be applied to. A color variable can be limited to fills, a number variable to corner radius.
They filter the picker and nothing else. Figma’s REST API documentation notes that a variable can still be bound outside its scopes through the Plugin API.
Set scopes on semantic variables so each one appears only where its role makes sense, for example keeping a spacing variable out of the font size field.
Figma’s documentation is inconsistent on which types support scopes. The Help Center’s variables-versus-styles article still says scoping is fully supported only for number variables. Its create-and-manage article says scoping is available for number, color and string variables, and the REST reference says scopes work only on FLOAT and COLOR yet still lists string scopes such as TEXT_CONTENT and FONT_FAMILY.
Test the type you need in the picker before building a system around it.
Figma variables vs styles: which should you use?
Use variables for single values that change by context, and keep styles for composite values such as gradients and shadows.
| Criterion | Variables | Styles |
|---|---|---|
| Stores | One raw value | A composite of values |
| Can be applied to | Layers, styles, other variables | Layers only |
| Light and dark contexts | Yes, through modes | No |
| Typical use | Color, spacing, radius, strings | Gradients, shadows, text definitions |
Figma’s Help Center states that different contexts, such as light and dark, require variables and variable modes. A style expresses all of its values at once and cannot switch between them.
You can also combine the two. A text style accepts a string variable for font family or weight, and a color style accepts a color variable, so the style stays reusable while the value follows the mode.
A rough rule: one value that changes by context goes in a variable. Several values that travel together go in a style, backed by variables wherever a single property must follow a mode.
How to use variables in prototypes
Prototype interactions change variable values with the Set variable action and branch on them with the Conditional action. Both work on any paid plan, according to the Figma Help Center.
- Set variable writes a new value on a trigger, and the value must match the variable’s type: a quoted string, a number, true or false, or a hex code.
- Conditional runs an if/else check before any action fires, such as showing free shipping only when a cart total passes a threshold.
- Basic math on numbers, joined strings and boolean logic can go into the Set variable and Conditional fields as expressions.
- Set variable mode switches a collection’s mode for the current page on click, which is how a theme toggle works inside a prototype.
A counter shows the pattern. Set itemCount to itemCount + 1 on the plus button, and every text layer bound to that variable updates on each click.
Triggers and flows come first, which how to prototype in Figma covers before variables enter the picture.
Actions run top to bottom, so order matters.
In Figma’s own example, a conditional checking numberVar == 2 navigates to Frame 2 when it sits below a Set variable action that sets numberVar to 2. Swap the two and nothing happens, because the check runs before the value changes.
Invalid expressions get outlined in red, and only supported syntax runs.
How do Figma variables reach developers?
Code syntax names surface in Dev Mode. JSON files move in and out of Figma Design, and plugins convert variables into token files when a build step needs them.
Code syntax in Dev Mode
Code syntax stores one platform-specific name per variable for WEB, ANDROID and iOS. Dev Mode shows that name in its snippets when someone inspects a layer that uses the variable, per Figma’s REST API reference. The Help Center says variable snippets currently cover CSS, SwiftUI and Compose.
On WEB the name might read example-variable-name, while ANDROID and iOS both take exampleVariableName.
Add it from the variable’s edit modal, or set it in bulk through the Plugin API. The Figma Dev Mode guide covers how developers read those snippets.
Naming consistency matters most at developer handoff. A code syntax string that drifts from the codebase sends engineers back to guessing.
JSON import and export
Figma announced JSON import and export of variables inside Figma Design alongside extended collections, and rolled both out from November 2025, according to its release notes.
Import follows the Design Tokens Community Group format, with a few constraints listed in the Help Center.
- Dimension tokens must use px.
- Duration tokens must use s.
- Font family tokens hold a single font name.
- A number token tagged with the com.figma.type boolean extension becomes a boolean, with 0 as false.
The format reached its first stable version, 2025.10, on October 28, 2025 (Design Tokens Community Group).
Plugins and Style Dictionary
Plugins fill the gap when a build pipeline needs more than a hand-exported file.
Variables2json exports color, number, string, boolean and alias variables with aliases resolved, along with text styles, effects and grids. Tokens Bruecke generates Design Tokens JSON, converts Figma’s variable types into token types, and nests multi-mode values under $extensions.
Style Dictionary sits after both. It reads that JSON and emits platform output such as CSS, SCSS or JavaScript.
One failure mode is documented in the Tokens Bruecke README. Aliases to variables from another library export as paths, but the base variables stay out of the file, so Style Dictionary cannot resolve them until both files are merged.
Variables hold single values and styles hold composites, so a complete export has to read both. Variables2json includes text styles, effects and grids next to variables, and Tokens Bruecke can include styles through settings that are off by default.
What does the Variables REST API do, and who can use it?
The Variables REST API reads and writes variables, collections and modes in a file. Only full members of Enterprise organizations get access, and every other account gets a 403.
- GET local variables returns variables created in the file and remote variables used in it.
- GET published variables returns variables published from the file, without modes.
- POST variables handles bulk creates, updates and deletes for variables and collections.
Tokens need file_variables:read to read and file_variables:write to write. Writing also takes edit access to the file and a full seat, and the local endpoint is rate-limited as a Tier 2 endpoint.
To see mode values for a published variable, call GET local variables in the same file.
GitLab’s design system team spiked a one-way sync from token JSON to Figma variables and had to convert hex colors to decimal RGBA first. It concluded the API could not fully sync tokens, because creating aliases to remote variables is not allowed (GitLab UI issue 2526). A Figma forum reply on that limit says the API cannot alias a remote variable that the file does not already use.
That issue was last edited in May 2024, so recheck the current API reference before ruling a sync out.
Outside Enterprise, the Plugin API exposes variables from inside the file through methods such as figma.variables.createVariableCollection and setValueForMode.
Two quirks matter in practice. The valuesByMode property does not resolve aliases (use resolveForConsumer), and importVariableByKeyAsync only loads variables that are already published.
How to manage multi-brand themes with extended collections
Match the method to the plan. Enterprise teams extend a core collection per brand, teams under their mode cap put brands in modes, and teams over it layer collections.
Extended collections
An extended collection sits under a parent collection and inherits every update to variables it has not overridden, so brand values stay local while new tokens flow down (Figma Help Center).
- It’s an Enterprise plan feature only.
- Anyone with can-edit access to a file can extend a collection.
- Extensions can branch across several levels.
Existing brand themes migrate in. Figma’s workflow depends on whether the themes sit in one collection or several.
Modes in a single collection
Each brand becomes a mode. Four brands in light and dark need eight modes, so count before committing.
This fits as long as the brand and theme combinations stay under the mode cap of your plan. It breaks the moment a new brand pushes the count past the cap, which forces a restructure mid-project.
Layered collections without extension
Dow Jones built its Index Design System this way in summer 2025 for a portfolio of 10+ products, before extended collections arrived. Figma announced them on October 28, 2025 and rolled them out in November 2025. The Wall Street Journal’s Opinion sub-theme switches a single token, content/primary, from blue to ochre (Veronica Campana, Medium, May 2026).
The layers stack up like this, with separate platform and light/dark collections on the side:
- Brand foundations libraries holding primitives, disabled by default
- A hidden default collection per brand holding semantic tokens
- A sub-theme collection whose modes alias the default and override only what differs
- One published theme collection with a mode per brand
The price is more collections to maintain, plus a strict naming root, such as prefixing every variable with its collection name, so aliases across collections stay readable.
When do Figma variables fall short?
Variables fall short on composite tokens, units, hidden collections and remote aliases, and they add little to a single-theme file with no code pipeline.
| Limit | Where it bites | Workaround |
|---|---|---|
| No composite types | Shadow and typography tokens | Keep them in styles, export both |
| Unitless numbers | Percent values from token files | Store plain numbers, add units in the build |
| Hide from publishing | JSON export pipelines | Clear all scopes instead |
| Remote aliases | REST API sync | Author aliases in the editor |
Tokens Studio’s documentation flags the unitless rule: its plugin skips percent tokens that should become number variables. GitLab hit the same wall when “12px” line heights had to become plain 12 in the token source.
Dow Jones found that Hide from publishing interferes with JSON export pipelines, so its team cleared every scope on the hidden tokens instead. They vanish from property panels but stay readable by engineering tools.
Export tools hit the collection cap as well. Tokens Studio’s plugin creates variables up to the cap and skips the rest, and it skips modes beyond the plan allowance the same way, so a large token set has to split across collections.
The token format is still moving. The Design Tokens Community Group calls version 2025.10 stable for production, and its own FAQ also lists the spec as still evolving and outside the W3C Standards Track.
A single-theme file with no prototype logic and no code pipeline gets very little out of variables. Styles cover that file, and the setup cost buys almost nothing.
Figma variables FAQ
Do variables replace variants?
Not entirely. Boolean, number and string variables can be applied to variant properties on an instance, so the active variant follows the mode of the parent frame.
The variant set itself still has to exist.
What happens if you delete a variable that other layers still use?
References can survive the deletion. Figma’s REST API flags such a variable as deletedButReferenced, meaning it was removed in the editor while bound values or aliases still point to it.
Check which aliases depend on a primitive before deleting it.
Can you copy variables into another file?
Yes. Select one or more variables in the variables view, right-click, choose Copy, then paste into any collection, including one in a different file.
Hold Cmd (Mac) or Ctrl (Windows) to pick several, and Shift to select a range.
How do you detach a variable from a layer?
For color, string and boolean variables, hover over the variable in the right sidebar and click the Detach variable icon.
Number variables work differently: click into the property field and press Delete or Backspace, per the Figma Help Center. For some properties the Detach variable icon also works.
Can an alias go back to a raw value?
Yes. Hover over the value field of the aliased variable and click Detach alias.
The variable then stops following its source variable.
Where to Start With Figma Variables
Begin with a primitive color collection, then a semantic one carrying Light and Dark modes. Spacing and radius follow as number variables.
- Primitive color collection, one mode
- Semantic collection with Light and Dark modes
- Number variables for spacing and radius
Spacing goes last because it rarely needs modes. Dow Jones kept spacing tokens static across brands, according to the May 2026 write-up by the creator of its Index Design System.
Building semantic tokens before the first screen does slow down visible design work. What you get back is aliases that need no rework when a brand changes.
The order above was verified in October 2026. Mode caps changed in October 2025 and extended collections arrived in November 2025, so recheck Figma’s plan comparison before fixing a structure.
The natural next step is assembling these collections into a full system, which this Figma design system tutorial walks through.
Many of his resources are available on various design marketplaces. Over the years, he's worked with a range of clients and contributed to design publications like Designmodo, WebDesignerDepot, and Speckyboy, Slider Revolution among others.
- How to Insert Image in Figma With Ease - November 3, 2026
- How to Download Figma Files Fast and Free - October 30, 2026
- Figma Keyboard Shortcuts That Will 10x Your Speed - October 25, 2026
