Figma variable modes
Learn

Figma variable modes in depth: theming, dark mode and brand switching

Author Avatar
Written by
Jun 22, 2026

Figma's modes system is the design-side equivalent of what CSS custom property overrides and theme switching do in code. A mode is a named variant of a variable collection (Light and Dark, Brand A and Brand B, Compact and Comfortable) that lets you switch the resolved values of every variable in that collection with a single toggle on a frame or component.

Done well, modes are what make a Figma library feel like a real token system rather than a static set of styles. They let designers work in dark mode as naturally as light mode, test multi-brand components without duplicating anything, and hand off a design that maps directly to what engineers will implement.

This article covers how to set modes up, how they resolve, where they break down, and how they connect to the code-side theme switching covered in Article 08 — Theming with design tokens.

The conceptual foundation — why modes operate at the alias tier, how inheritance works, and how to avoid combinatorial complexity — is in Article 06 — Token modes: handling variation in your token system. This article focuses on the Figma-specific mechanics.

Setting up your first mode: light and dark

Light and dark is the most common first mode setup and the best way to understand how Figma's mode system works before adding complexity.

Modes live at the collection level. In the Variables panel, select your semantic collection, click the mode controls at the top, and rename the default mode Light. Add a second mode called Dark.

Your semantic collection now has two columns, one per mode. Each variable in the collection needs a value for each mode:

Collection: 01 Semantic
Modes: Light | Dark

color/surface/default
  Light: {color/neutral/50}     → #FAFAFA
  Dark:  {color/neutral/900}    → #171717

color/text/primary
  Light: {color/neutral/900}    → #171717
  Dark:  {color/neutral/50}     → #FAFAFA

color/action/primary
  Light: {color/blue/500}       → #3B82F6
  Dark:  {color/blue/400}       → #60A5FA

The primitive collection doesn't get modes. color/neutral/50 is always #FAFAFA. The primitive is a fact, not a decision. Modes belong at the semantic tier, where the interpretation of a value changes with context.

To apply a mode in the canvas, select a frame or component and use the variable mode controls in the right panel to switch between Light and Dark. Everything inside that frame that references a semantic variable updates instantly. This is the core mechanic, and the reason why components that reference semantic variables correctly will automatically respond to mode switches, while components that bypass the semantic layer and reference primitives directly won't.

Mode inheritance: how Figma resolves values

Figma resolves the mode for a variable by looking at the nearest ancestor frame that has a mode applied. If a component sits inside a frame with Dark mode set, all variables inside that component resolve to their Dark values, even if the component itself has no mode set.

This inheritance model enables a powerful pattern: you can apply a mode to a section of the page without applying it globally. A dark navigation bar inside a light-mode product, for example:

Page frame (Light mode)
  Main content (inherits Light)
  Navigation frame (Dark mode applied)
    Nav components (resolve to Dark values)

No component logic changes. The mode on the container does all the work.

When no mode is set anywhere in the ancestor chain, Figma falls back to the collection's default mode, typically the first mode defined, which is usually your Light or base theme.

One implication of this: if you're building a component that needs to be mode-agnostic (a component that works correctly regardless of which mode is active on its container) it needs to reference semantic variables, not hardcoded values. A hardcoded #171717 won't respond to the Light mode on its container; a color/text/primary variable will.

Multi-mode setups: combining modes across collections

Modes become more powerful — and more complex — when you need to support multiple independent dimensions of variation simultaneously. The key principle from Article 06 applies in Figma too: keep mode purposes separate across collections.

A common multi-mode setup for a product with light/dark theming and brand switching:

00 Primitives (collection, no modes)
  color/blue/500, color/neutral/50, etc.

01 Color Semantic (collection)
  Modes: Light | Dark | High Contrast
  (resolves color values by theme)

02 Brand Semantic (collection)
  Modes: Brand A | Brand B | Brand C
  (resolves brand-specific overrides: primary color, font family)

03 Density (collection)
  Modes: Default | Compact
  (resolves spacing values by density)

Each collection handles one axis of variation. To show a component in "Brand B, Dark mode, Compact density," you apply three mode settings (one per collection) to the container frame.

This is more work to apply than a single combined mode, but it's far more maintainable. A combined "Brand B Dark Compact" mode would need to be maintained as a single entity; separate axes can be mixed and matched without multiplying your maintenance overhead.

In Figma's canvas, applying multiple modes to the same frame is done through the variable mode controls in the right panel. You'll see each eligible collection listed and can set a mode for each independently.

Using modes for multi-brand switching

Modes are one of the most practical tools for managing multi-brand design in Figma. Rather than maintaining separate libraries or duplicating components, you maintain one component set and switch the brand by changing the active mode on a container.

For two to five brands, the mode-per-collection approach works cleanly. Define a semantic collection with one mode per brand:

01 Brand Color (collection)
  Modes: Brand A | Brand B | Brand C

  color/action/primary
    Brand A: {color/blue/500}    → #3B82F6
    Brand B: {color/coral/500}   → #F97316
    Brand C: {color/green/500}   → #10B981

Components reference color/action/primary, and the brand mode determines what it resolves to. Switching a frame from Brand A to Brand B updates every component inside it.

For more than five brands, the collection-level mode approach runs into Figma's plan limits (four modes on non-enterprise plans, 40 on enterprise). Workarounds include using group-based organization within a single mode, maintaining separate semantic collections per brand, or supplementing Figma's native modes with a plugin like Tokens Studio for more complex scenarios.

For brands that share a foundation, the shared primitive layer is what makes this efficient. All brands draw from the same color palette and spacing scale — the brand mode layer only overrides the semantic aliases, not the underlying values. This is the same layering principle covered in Article 07 — Multi-brand, multi-product and white-label token architecture, applied specifically to Figma.

Dark mode in Figma: common mistakes

Figma's dark mode is one of the areas where the gap between a well-structured token system and a poorly structured one becomes most visible.

Using primitives in components. If a component's background is set directly to color/neutral/50 rather than color/surface/default, switching to the Dark mode on a parent frame won't change it. Primitives don't have modes. Every component that bypasses the semantic layer becomes a manual fix when dark mode is applied.

Inverting light mode values instead of designing them. Setting dark mode values by reversing light mode values (swap the lightest neutral for the darkest) produces something that looks technically correct but often feels wrong — shadows become invisible, brand colors feel harsh, depth cues collapse. Dark mode values need to be designed, not calculated. Article 09 — Implementing dark mode with design tokens covers this in depth.

Applying modes at the wrong level. Setting a mode on a deeply nested component rather than on a page-level or section-level frame means the mode doesn't cascade to sibling or parent elements. Modes should generally be applied at the highest relevant container, not on individual components.

Forgetting non-color variables. Dark mode in Figma often focuses entirely on color, but shadow values also need dark mode variants. A dark shadow on a dark background is invisible. If you're using elevation shadows, make sure they have values in the Dark mode of your semantic collection.

Figma's mode limitations and how to work around them

Figma's modes system is powerful but has real constraints worth planning around.

Mode limits by plan. Non-enterprise Figma plans allow a maximum of four modes per collection. Enterprise allows up to 40. If your system needs more than four variants of a given dimension (more than four brands, for example) you'll need to either restructure your collections, upgrade your plan, or use a supplementary tool.

Modes don't cascade across files. If your semantic collection is in a separate Figma library file from the components that consume it, mode changes in the library file don't propagate to the consuming file automatically. For cross-file aliasing to work with modes, all related collections need to be in the same file. This is one of the strongest practical arguments for keeping your variable architecture in a single library file, as covered in Article 14.

No computed or dynamic values. Figma modes store discrete values. You can't define a dark mode value as "the light mode value minus 30% lightness." Every mode value needs to be explicitly defined, which means a token with ten modes needs ten explicitly set values. For large mode matrices, this becomes significant authoring overhead.

Manual mode application. Unlike CSS, which applies a theme to everything that inherits from the root element, Figma modes have to be manually applied to frames in the canvas. For large files with many screens, this can be tedious. A consistent practice of applying modes to the outermost page-level frame, rather than to individual sections, reduces the number of places you need to set modes manually.

How Figma modes map to code-side theme switching

The design-side mode structure should mirror the code-side theme implementation as closely as possible. When a Figma mode switch produces the same visual result as a CSS theme switch, the handoff is unambiguous and testable.

In CSS, theme switching works by overriding custom property values at a class or attribute scope:

css

:root {
  --color-surface-default: #FAFAFA;
  --color-text-primary: #171717;
}

[data-theme="dark"] {
  --color-surface-default: #171717;
  --color-text-primary: #FAFAFA;
}

The Figma mode and the CSS theme are different expressions of the same semantic structure. color/surface/default in Figma and --color-surface-default in CSS should resolve to the same value in each mode. If they don't, there's a discrepancy between design and implementation that needs to be resolved at the token level, not patched component by component.

When tokens are exported from Figma and transformed through the pipeline (covered in Article 17 — Exporting design tokens from Figma), each mode typically becomes a separate output file or a separate section of the CSS output. The mode names from Figma become the theme names in code. Keeping those names consistent — Light/Dark in Figma maps to light/dark in the data attribute — makes the connection between design and implementation explicit.

What comes next

Article 17 — Exporting design tokens from Figma: formats, tools and workflows covers how to get your variables out of Figma and into a format that a transformation pipeline can consume — including native export, Tokens Studio, and the full Figma-to-code workflow.

For the dark mode design decisions that sit behind the Figma implementation, Article 09 — Implementing dark mode with design tokens covers why inversion fails, how to handle elevation, and how to test dark mode properly.

For multi-brand token architecture at the system level — the layering strategy that Figma modes express at the design tool level — Article 07 — Multi-brand, multi-product and white-label token architecture covers the full picture.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post