Themes
A theme is a named combination of token sets. Themes are how one document carries several brands, a light and a dark mode, and a compact and comfortable density — without duplicating the whole token tree.
Creating a theme
Themes tab → add theme.
| Field | Notes |
|---|---|
| Group | Optional. Themes in the same group are mutually exclusive — brand, mode, density |
| Theme name | The display name within the group |
| Active | Whether the theme is on immediately |
| Token sets | Every detected set, each with a three-state selector |
Save requires a name and at least one set set to Enabled.
The saved theme’s full name is <group> / <name> — a theme named Dark in group
mode is stored as mode / Dark.
The three set states
| State | The set’s tokens are… | Use it for |
|---|---|---|
| Enabled | Visible — they show in the panel, export, and sync | The sets this theme actually contributes |
| Reference | Resolvable but not output — other tokens can point at them, they do not appear themselves | Primitive palettes that semantic tokens alias |
| Disabled | Ignored entirely | The other brand’s or mode’s sets |
The distinction between Enabled and Reference is what keeps an export clean.
A raw palette of 200 primitives should be Reference, so semantic.color.*
can resolve against it while the exported document contains only the semantic
layer.
Groups and exclusivity
Only one theme per group can be active. Activating Dark in the mode group
automatically deactivates Light.
Groups are independent, so these combine freely:
brand: Acme ● Globex ○mode: Light ○ Dark ●density: Compact ○ Comfortable ●That is one active theme per axis, three active themes in total, resolving into a single token snapshot.
If you leave the group field blank, the group is inferred from a name written as
"Group / Name".
Switching themes
Two places:
- Themes tab — a switch per theme, grouped by group name, with a
<enabled sets> - <token count>summary - Theme selector in the Tokens panel header — a dropdown with a checkbox per theme, plus a badge showing how many are active
Toggling a theme pushes the newly resolved token snapshot to Figma after a short debounce, so the panel and any theme-driven preview stay in step.
Managing themes
Right-click a theme: Edit, Duplicate, Delete (with confirmation).
Resolution order
When several enabled sets define the same token name, the winner is decided by set prefix, in this priority:
| Priority | Prefix | Rationale |
|---|---|---|
| 1 | brand. | Brand overrides everything |
| 2 | mode. | Mode overrides base values |
| 3 | anything else | Component and semantic layers |
| 4 | global | The base layer everything falls back to |
Naming your sets with these prefixes therefore does real work — it is not just convention.
There is additional handling for a group literally named mode with themes
recognised as light and dark.
The $themes.json file
Themes are stored and exchanged in a $themes.json file, in the shape Tokens
Studio uses, so themes survive a round trip through export, a repository, and
import.
On export, each theme’s set states are written under selectedTokenSets with a
tokens/ prefix on each key.
On import, DAES accepts a $themes array, a themes array, or a bare array. In
a folder import, a file named themes.json or $themes.json is detected
automatically.
Imported themes arrive inactive
Themes are never auto-activated on import. After importing you switch on the combination you want. This prevents an import from silently changing what every token in the document resolves to.
A fourth state, source, is accepted on import for Tokens Studio compatibility
and is treated like Reference.