Figma Variable Modes for Multi-Context Theming

Why it exists

Design systems need to support multiple contexts like light and dark themes, desktop and mobile densities, or different brand flavors. Before variables and modes, teams duplicated components or libraries for each context, which meant every update had to be copied manually across files. Variable modes were invented to let one source of truth hold multiple values simultaneously and switch between them cleanly without forking the design file.

The mental model

Think of a variable as a contract and a mode as the context in which that contract is fulfilled. In one mode the contract says the background is white; in another mode the same contract says the background is black. The component does not change; only the context around it does. This is similar to CSS custom properties switching under a data-theme attribute, but scoped visually inside Figma.

How it works

You create a variable collection, define variables inside it, and then add modes to that collection. Each variable gets a distinct value per mode. You then apply a mode to a frame, page, or the entire file. Any variable consumed within that scope resolves to the value defined for the active mode. Figma also supports multiple collections, so you can layer a color mode from one collection with a spacing mode from another, creating a matrix of contexts without multiplying components.

When to use it

Use modes for environmental contexts that are broad and persistent across a user session. Three places this shows up: first, color themes like light and dark; second, platform adaptations like iOS versus Android spacing and typography; third, brand white-labeling where the same layout needs different color values for different clients.

When not to use it

Do not use modes for transient interactive states such as hover, pressed, disabled, or error. These are better handled by component variants or boolean properties because they change within a single screen and do not represent a global context. Using modes for micro-interactions creates a combinatorial explosion where every state needs a value in every mode, making the system brittle and slow to edit.

One canonical example

A design system defines a semantic color variable called background-primary. In the light mode it maps to a white hex value, and in the dark mode it maps to a near-black hex value. A designer builds a card component using background-primary for its surface color. When the designer places that card on a light mode dashboard frame, it renders white. When they place it on a dark mode settings frame, it renders black. The card component itself never changes, and the file stays a single source of truth.