Figma themes run on three ideas: variables, collections and modes. Set them up once and a whole screen switches from light to dark, or from one brand to another, with a single setting. This guide covers the setup, adding themes, applying them and keeping them healthy. New to tokens? Start with Design Tokens, Explained.
In short
- One collection for primitives, one for themed semantic tokens. Each theme is a mode.
- Designs only use semantic variables. Switch a frame, section or page to a mode to change theme.
- Several brands: modes on most plans, extended collections on Enterprise.
How themes work in Figma
- Variable: a stored value, such as a colour or a number, that you apply to designs. It is Figma’s version of a design token.
- Collection: a group of variables, such as “Primitives” or “Theme”.
- Mode: a column of values inside a collection. A “Theme” collection might have Light and Dark modes. Each variable has one value per mode.
Modes depend on your plan:
Plan
Modes per collection
Figma raised the Professional limit from 4 to 10 and set Organization to 20 at Schema 2025. Check the plan comparison before you plan many brands: six brands with light and dark need 12 modes in one collection.
Set up the collections
- Primitives. Create a collection with your full palette and scales, such as
purple/600andspace/4. One mode only. - Hide primitives. In each variable’s Edit variable window, turn on Hide from publishing, so other files do not see raw values. Also clear its scopes, the settings that decide which property menus a variable appears in, so designers do not pick it by accident.
- Theme. Create a second collection for semantic variables such as
text/default,background/surfaceandaction/primary. Add a mode per theme: Light, Dark, High contrast. - Alias. Right-click a value and choose Create alias to point it at a primitive. Light
text/defaultpoints atgrey/900; Dark points atgrey/50. - Scope. Limit each semantic variable to where it belongs: text colours to text fills, backgrounds to frame fills, gaps to spacing.
- Code syntax. Add the developer name for each variable (Web, iOS, Android) under Code syntax, so Dev Mode shows
var(--color-text-default)instead of a colour. - Publish the file as a library.
Keep other dimensions in their own collections, such as density (Comfortable, Compact) or breakpoints. Each collection switches independently. Figma’s variables and collections guide has the exact menus.
Add a new theme
- Open the Theme collection and click New variable mode, or right-click an existing mode and choose Duplicate mode. Figma copies the first column’s values.
- Rename the mode, then change only the aliases that differ. Most stay the same.
- Check contrast for every text and background pair in the new mode before publishing.
- Publish the library and ask teams to accept the update.
Have the values already as JSON? Right-click the mode and choose Import mode. Variables with matching names and types are updated. Figma reads the shared token format here.
Apply themes to designs
- Frames and sections: select it, then in the right sidebar open Apply variable mode and choose a mode for the collection.
- Whole page: deselect everything and set the mode in the Page section of the sidebar.
- Auto: layers default to Auto, which means they use their parent’s mode. Set the mode once at the top and everything inside follows.
- Default mode: the left-most column. Anything not set to a mode uses it.
- Components: string, number and boolean variables can switch component variants when the mode changes, if the values match the variant names. This is how a “Compact” mode can swap buttons to their small variant.
A quick test: put the same screen side by side, set one to Light and one to Dark. Anything that does not change is using a primitive or a raw value.
Multiple brands: modes or extended collections
Approach
Plan
How it works
Best for
With extended collections, each brand keeps every value it does not override and picks up the parent’s changes automatically. Overridden values are shown in blue, and Reset change returns one to the parent. Three things to know:
- You cannot add variables or modes in an extension. Add them to the parent.
- A colour and its opacity count as one override. Change either and the parent’s colour updates stop reaching that variable.
- Moving brand modes into extensions removes the modes already applied to designs. Plan time for designers to reapply them, and run the move on the main file, not a branch.
Keep themes healthy
- Publish often. A “mode conflict” (an information icon in the mode menu) means files are using different versions of the same variable. Publish the library and accept the update in each file. If libraries are chained, update from the source file down.
- Rename carefully. Renaming a variable is safe inside Figma but breaks code that uses the old name. Treat renames like any other release.
- Retire, then delete. Write “Deprecated, use X” in the description first. Delete only when no file uses it.
- Describe everything. One sentence per semantic variable on where to use it. It shows in Dev Mode and helps AI tools pick the right one.
- Audit quarterly. Look for raw values in designs, primitives used directly and near-duplicate variables.
- One owner. Someone approves new variables and modes, or every team adds its own.
From Figma themes to code
- Export. In the Variables panel, right-click a mode and choose Export mode, or right-click the collection to export every mode as JSON in the shared token format.
- Build. Run the files through Style Dictionary or Terrazzo. Typical web output is CSS variables per theme, switched with an attribute such as
data-theme="dark". - Check the round trip. Export, import into a copy and compare. Some community reports describe descriptions or a few variables going missing, so do not assume a perfect round trip.
- Connect your AI tools. Figma’s MCP server gives coding assistants the variables used in a frame, so generated code uses your theme names.
The token format also has a resolver module for themes in code: it combines a base set with the chosen theme, so a build loads only the files that theme needs.
Theme checklist
- Primitives in their own collection, hidden from publishing, no scopes.
- Semantic variables in a Theme collection, one mode per theme, all aliases.
- Scopes set, code syntax added, every semantic variable described.
- Screens switch fully between modes, with nothing left behind.
- Contrast checked in every mode.
- Library published; teams have accepted the update.
- Export runs on every change, and code uses the same names.
DESIGN SYSTEMS
Want themes that switch with one setting?
We can set up Figma variables, modes and brand themes, and connect them to your code.