Themes
Themes let you maintain multiple brand variants — dark mode, sub-brands, white-label products — within a single project, each overriding only the tokens that differ.
What are themes?#
Every project starts with a base token set — this is what developers pull when they sync from main. A theme is an overlay that changes specific tokens for a particular context, such as a dark colour scheme or a sub-brand's accent colours.
Themes are additive: they only contain the tokens you explicitly override. Everything else inherits from the base. This means a dark theme might override just 15 tokens (backgrounds, text colours, borders) while keeping all spacing, radii, and typography identical.
Creating a theme#
In the Studio, use the Theme Selector dropdown at the top of the token editor. Click + New theme, give it a name (e.g. "Dark", "Brand A"), and optionally pick a parent theme to inherit from.
Theme inheritance#
Themes can extend a parent theme, forming an inheritance chain. The effective value for any token in a theme is resolved by walking the chain:
| Priority | Source | Example |
|---|---|---|
| 1 (highest) | Direct override in this theme | Theme sets color/primary → #8B5CF6 |
| 2 | Inherited from parent theme | Parent theme sets color/background → #1c1b18 |
| 3 (lowest) | Base token value | Base sets color/foreground → #f9f9f7 |
For example, a "Brand A Dark" theme can extend "Dark" — it only needs to override the brand accent colour, while inheriting all dark mode tokens from its parent.
Editing tokens in a theme#
When a theme is active in the Studio, the token form shows two save options:
| Action | What happens |
|---|---|
| Save in [theme name] | Creates or updates a theme override for this token. The base token is untouched. |
| Save in base | Edits the base token value. This affects every theme that does not override it. |
Tokens that are directly overridden in the current theme show an orange badge. Tokens inherited from a parent theme show a gray badge. Tokens with no override at all use the base value.
Live preview#
The live preview panel in the token editor automatically reflects the currently selected theme. Switch themes in the dropdown to instantly see how component variables resolve — no rebuild or refresh needed.
Removing a theme override#
If you want a token to fall back to its base or inherited value, click the reset button next to the override. This removes the theme-level override and reverts to the inherited or base value.
Cross-project themes in multi-level projects#
For organisations with multiple brands or products, Particles supports multi-level projects — a layered Foundation → Brand → Product model, chosen per project (a Business plan capability). A Brand module owns its named themes (Light / Dark, or per-sub-brand variants); any Product that links that brand inherits its themes automatically, on top of the primitives it gets from a linked Foundation. See Token architecture for the full layering model.
A product consumes each module at a pinned release, not its live branch, so upstream theme edits never change your product until you deliberately adopt them. Check for and preview updates from the CLI:
# List linked modules — pinned release vs latest, and updates available particles token-studio modules status # Dry-run diff of a pending module update (added / removed / changed / conflicts) particles token-studio modules preview <refId>
Accepting an update — including any new or changed theme overrides — is a deliberate step in Project → Token modules in the Studio, with the same per-token diff UI used in token requests.
Legacy foundation sync (deprecated). Older organisations may still see a Project → Settings → Foundation link and a foundation sync flow from an earlier, single-tier cross-project inheritance model. It has been superseded by multi-level modules above and should not be used for new projects.
How developers consume themes#
When developers sync tokens via the CLI, the base token set is written to your configured tokens file by default. To generate a specific theme as a separate CSS file, use the theme commands:
| Goal | Command |
|---|---|
| Sync base tokens | particles token-studio sync |
| Generate a theme CSS block | particles theme generate dark --out src/themes/dark.css |
| Generate all themes at once | particles theme generate-all --out-dir src/themes |
Theme CSS files use a [data-theme="name"] selector — activating a theme in the browser is as simple as setting one attribute on any container element.