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:

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:

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.

Foundation projects & cross-project inheritance

For organisations with multiple brands or products, Particles supports foundation projects. A foundation project is a shared source of primitive and semantic tokens that other projects in the organisation extend.

Link a project to a foundation via Project → Settings → Foundation. All tokens from the foundation's main branch appear as read-only base tokens in your project. You can override them locally at the project level.

When the foundation publishes a release or merges into main, your project receives a notification. Use the Sync Foundation flow to pull upstream changes — conflicts between foundation updates and your local overrides are resolved with the same per-token diff UI used in token requests.

How developers consume themes

When developers sync tokens via the CLI, the base token set is exported by default. To export a specific theme's overrides merged on top: