How to set up variable modes in Figma: collections, aliases and theme switching

A variable mode in Figma is an extra column of values on a variable collection. To use modes for light and dark themes, keep your raw palette in a collection with a single mode, create a second collection that aliases it, add a Light and a Dark mode to that second collection, and then switch frames or pages between the two. Before you start, check your plan: Figma's help center lists modes for Education, Professional, Organization and Enterprise plans, so on the free Starter plan you can create variables but not a second mode.

This guide is the hands-on part: which collection gets the modes, how to fill each column, how switching works on frames, pages and components, and what to do about plan limits. For how to name the variables themselves, we keep a separate reference: Light and dark semantic tokens: a naming system that scales.

What a mode actually is

Open the Variables tab and look at any collection. Each row is a variable. Each column after the name is a mode, and each cell holds one value for that variable in that mode. The left-most column is the default mode.

When you apply a variable to a fill, the layer shows whichever value belongs to the mode it's currently in. Nothing about the variable name changes. That's the whole trick: you design once with background/default, and the frame decides whether that means the light or the dark value.

What Figma's plan limits mean for modes

This catches a lot of people halfway through a tutorial, so it goes first.

• Starter (free): Figma's Modes for variables article lists Education, Professional, Organization and Enterprise as the plans that can create and use modes. Starter isn't on that list, and the variable modes row in Figma's plans and features table is empty for Starter. Variables themselves work on any plan.
• Professional: up to 10 modes per collection.
• Organization: up to 20 modes per collection.
• Enterprise: unlimited modes through extended collections.

Starter has a second limit that matters here. The Starter plan overview says there are no team libraries, so you can't publish your collections for other files to use either.

What that means in practice: on Starter, build the single-mode collections now and alias everything properly. When the team moves to Professional, adding the Dark column is a small job instead of a rebuild. I'd avoid the workaround of two separate theme collections, because every variable then has to be edited twice and they drift apart. Our guide to Figma variables on the free plan covers what else works on Starter and how far you can get without modes.

Step 1: a single-mode collection for raw values

Create a collection called Primitives and add your palette as color variables (neutral/50, blue/600 and so on; slashes create groups in the panel). Leave it with one mode.

Why only one? A Figma staff answer on the Figma Forum (May 2026) explains that when you alias across collections and both collections have their own Light and Dark modes, Figma doesn't match those modes by name. The swatch preview in the Variables panel then shows the referenced collection's default mode, so your Dark column looks wrong while you edit it, even though the canvas renders correctly. Their recommendation: one mode on primitives, theme modes only on the collection that aliases them.

While you're here, select all the primitives, right-click, choose Edit variables, and untick every scope in the Scope tab. They stay available for aliasing but disappear from the fill picker.

Step 2: a second collection that gets the modes

Create a collection called Semantic (or Theme; the name matters less than the split). Then:

1. Double-click the first column header and rename it Light.
2. Click New variable mode (it sits just after the last column header). You get a new column pre-filled with the first column's values. Rename it Dark.
3. Add your variables. For the names, use the naming reference; a handful like background/default, text/primary, border/default and action/primary is enough to test the setup.

If you need a third theme later (a second brand, say), right-click a mode header and choose Duplicate mode, then edit the copy.

Step 3: alias in every column

For each variable, right-click the value in the Light column, choose Create alias, and pick a primitive. Then do the same in the Dark column. Two rules I hold to:

• No raw hex in this collection. A typed value in one column is the cell nobody updates during the next rebrand.
• Fill both columns. Because the new mode starts as a copy, a forgotten cell won't look empty. It will quietly show the light value in dark mode. Scan the Dark column once you're done; any value that matches its Light neighbor deserves a second look.

Step 4: switch modes on frames, pages and components

Bind your fills, strokes and text colors to the Semantic variables, never to primitives. Then:

• A frame or any container: select it, open Apply variable mode in the Appearance section of the right sidebar, hover the collection and pick Dark. A tag with the mode name appears next to the layer in the Layers panel.
• A whole page: deselect everything, then use Apply variable mode in the Page section.
• Nested layers: by default they're set to Auto and inherit the mode from their nearest parent that has one set. If nothing above them has a mode, they use the collection's default.
• Components and sections: you can set a mode on a component, a component set, a section or a group, not just frames. A common pattern is a Light and a Dark copy of the same screen side by side, with the mode set only on the two top-level frames.
• Prototypes: Figma has a Set variable mode prototype action, so a toggle in a prototype can flip the theme.

Step 5: decide what the default mode is

The default is the left-most column. You can change it by dragging a column to the left or right-clicking a header and choosing Set as default. Be careful in a file that's already in use: anything set to Auto follows the new default, while layers that were explicitly set to a mode keep it. If your product defaults to dark, it's worth deciding this before you build screens.

Troubleshooting

The swatch preview shows the light color in the Dark column. Your primitives collection probably has modes of its own. Remove them so it has a single mode.

A layer won't change when I switch modes. It's bound to a primitive, a raw hex value, or a variable from a collection that only has one mode. Check the fill in the right sidebar.

An icon next to a mode in the mode menu. That's a mode conflict: layers in the file use an older version of a library variable that doesn't have the newer mode. Publish the library and accept the update in each file in the chain, starting with the file closest to the source.

Deleting a collection by accident. Deleting a collection removes all its variables and disconnects every property that used them. Undo straight away, or restore an earlier version from version history.

Plugins that build the collections and modes for you

If you'd rather start from a generated setup and adjust it, these plugins create primitives, an aliased layer and Light and Dark modes. Claims are from each plugin's own listing, as of October 2026.

Links: Kigen, Semantix, Foundation Studio.

Huekit is our plugin. We built it to generate the setup in this guide: color scales from your brand colors or a preset, saved as Figma variables with Light and Dark modes, with semantic tokens on top and documentation pages in the file. Every variable it creates stays editable. Whichever plugin you try, open the result in the Variables tab and check it against Steps 1 to 3: modes on one collection only, and an alias in every cell.

FAQ

How do I add a mode to a variable collection in Figma?

Open the collection in the Variables tab and click New variable mode next to the last column header. The new mode starts as a copy of the first one, so edit its values afterwards.

Can I use variable modes on Figma's free plan?

No. Figma's help center lists modes for Education, Professional, Organization and Enterprise plans. On Starter you can create variables and aliases, but not a second mode.

How many modes can one collection have?

Up to 10 on Professional and 20 on Organization. Enterprise allows unlimited modes through extended collections.

How do I switch a frame to dark mode in Figma?

Select the frame, click Apply variable mode in the Appearance section of the right sidebar, and pick the Dark mode of your collection. Child layers set to Auto follow it.

Should my primitives collection have light and dark modes?

No. Keep primitives in a single mode and put Light and Dark on the collection that aliases them. Figma doesn't match modes by name across collections, which leads to misleading previews.

What happens when I change the default mode?

Layers set to Auto switch to the new default. Layers that were explicitly set to a mode keep that mode.

Where to start

Open the Variables tab in your current file and count the modes on each collection. If your raw palette has more than one, fix that first. Then add a Dark column to the collection that aliases it, switch one frame, and look for any layer that doesn't change. If you'd rather start from a generated setup, you can try Huekit from the Figma Community, and use our naming reference for the variable names either way.