Figma Variables: Grouping Primitives with Collections

Why it exists

Design systems need to manage not just component styles, but the raw, primitive values that build them—like a specific gray, a corner radius, or a spacing unit. Variables were created to manage these primitive values systematically, especially across different contexts like light/dark themes or mobile/desktop layouts, making systems more efficient and scalable.

The mental model

Think of variables as raw ingredients, collections as a recipe book, and modes as variations on a recipe. A variable is a single value, like a hex code #FFFFFF or a number 8. A collection groups related variables, like a 'Spacing' system. Modes define different contexts for that collection, like 'Compact' vs. 'Spacious'. When you apply a variable, you're applying a role that can change its value based on the active mode.

How it works

Figma supports four variable types: Color, Number, String, and Boolean. You organize them inside Collections. For example, you can create a 'Theming' collection with two modes: 'Light' and 'Dark'. Inside, you create a Color variable called 'ui-background'. You then set its value to a light color for the 'Light' mode and a dark color for the 'Dark' mode. When you apply this 'ui-background' variable to a frame's fill, changing the frame's mode will automatically switch the color.

When to use it

Use variables to manage a system of design tokens for color, spacing, sizing, and typography. They are essential for building multi-theme designs (like light and dark mode), creating responsive layouts with different values for mobile and desktop, and managing text for localization with string variables.

When not to use it

Do not use a single variable when you need to apply a bundle of different properties at once. For that, use Styles. A style can define a fill color, a stroke, and a drop shadow together. A variable can only control one of those primitive values at a time, such as the fill color OR the shadow's blur radius, but not both simultaneously.

One canonical example

To create a button that adapts to screen size, create a 'Layout' collection with 'Desktop' and 'Mobile' modes. Create a number variable called 'button-padding'. Set its value to 16 for the 'Desktop' mode and 12 for the 'Mobile' mode. Apply this variable to the button's padding. Now, placing the button inside a frame set to 'Mobile' mode will automatically shrink its padding.