Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 36 ยท Design Systems and Variables

Variables and Modes

Learn Figma variables, collections, modes and aliases to build light and dark themes, spacing scales and responsive values from one source.

Styles let you reuse a color or a text format. Variables go further: they store a value under a name, and the value can change depending on the mode. One button fill variable can be blue in light mode and light blue in dark mode, and every layer bound to it follows when you switch modes. Variables are the foundation of modern theming in Figma.

Figma cannot run on this site. The code is a labelled JavaScript stand-in that models collections, modes and aliases so you can try the resolution rules. It is not Figma's code.

Variable types

Figma variables come in four types:

Type Holds Example uses
Color A color value Brand blue, surface, text
Number A number Spacing 8, radius 12, font size 16, opacity
String Text Button labels, language-specific copy, font family
Boolean True or false Show icon, is logged in, layer visibility

Open the Local variables panel by selecting nothing and clicking the variables icon in the right panel (or from the file menu). Create variables, name them, and set their values.

Collections and modes

A collection groups related variables, for example Color, Spacing or Typography. Each collection has one or more modes. A mode is a column of values: add a second column named "Dark" to the Color collection and enter dark values for each variable.

Variable Light Dark
surface/default #FFFFFF #0F172A
text/primary #0F172A #F8FAFC
accent/default #2563EB #60A5FA

Apply a variable by selecting a layer and, in the fill, stroke, or other numeric field, clicking the Apply variable icon (the small circle), then choosing the variable. To switch a frame between modes, select the frame and use the layer's mode control (the half-filled circle icon) in the right panel, or the Appearance/layer section. All layers inside inherit the mode. You can even show the same screen in light and dark side by side by setting a different mode on each frame.

Aliases

A variable can point to another variable instead of holding a raw value. This is an alias. For example, button/background can alias accent/default. Change accent/default and the button follows. Aliases are how you build layers of meaning, which the next lesson, Design Tokens, develops properly.

Aliases may point into another collection, so a "semantic" collection can reference a "primitive" collection. Each collection can have different modes: the primitive set may have none, while the semantic set has Light and Dark.

flowchart LR
    P["Primitive: blue-500<br/>#2563EB"] --> S["Semantic: accent/default<br/>Light: blue-500, Dark: blue-300"]
    S --> C["Component: button/background"]

Aliases chain values so one edit travels to all dependents.

Resolving a value

When a layer is bound to a variable, Figma finds the value in the current mode, and if it is an alias follows the alias to the next variable in its current mode, until it reaches a raw value. The stand-in does the same.

JS Stand-in: resolve variables with modes and aliases

Press Run (or Ctrl + Enter) to see the console output here.

No output.

button/background has no color of its own. It follows accent/default, which follows a primitive. Changing blue-500 anywhere updates the whole chain.

Variables beyond color

  • Spacing and radius as number variables (space/2 = 8, radius/md = 12) bound to auto layout padding, gap and corner radius.
  • Responsive modes: a collection with modes Mobile, Tablet and Desktop can change font sizes, margins and column counts. Flip the frame's mode to preview each breakpoint.
  • Language modes: a String collection with English and Spanish lets you swap all labels at once. Bind text layers to the string variables.
  • Visibility: a Boolean variable bound to a layer toggles it.

Variables can also be used in prototyping, as seen in Overlays, Scrolling and Conditions.

Scoping

Each variable has scopes that limit where it shows up in pickers. A color variable called text/primary should be scoped to text fills only, so designers do not accidentally use it as a background. Scoping, plus naming with slashes (text/primary, surface/default), keeps the picker tidy and the system hard to misuse. Hide helper primitives from publishing (the "Hide from publishing" option) so library users only see semantic variables.

Detecting problems

The stand-in below detects a classic mistake: an alias loop, where A points to B and B points back to A.

JS Stand-in: catch alias cycles

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Figma itself blocks you from creating a variable alias cycle, but the check is a nice way to understand why.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a mode in a variable collection?

    Each mode holds its own value for every variable in the collection.
  2. 2. Which is NOT a Figma variable type?

    The four types are Color, Number, String and Boolean.
  3. 3. What is an alias?

    An alias references another variable so changes flow through the chain.
  4. 4. How can one frame preview a Mobile layout and another a Desktop layout of the same design?

    Frame-level modes switch variable values for everything inside the frame.

Summary

  • Variables store Color, Number, String or Boolean values and can be bound to properties.
  • Collections hold variables; modes provide alternative values like Light and Dark.
  • Aliases reference other variables, creating layers of meaning.
  • Scoping and naming with slashes keep the picker tidy.
  • Modes can also drive responsive values and languages.

Next: Design Tokens