Skip to main content
Version: Next

Custom Token Sets

A theme's token set is the actual color scheme. Token sets are provided by the frontend as theme dynamic types of the studio-ui bundle. A token set contributed by any bundle automatically becomes selectable as a theme's Token set in the Theme Manager editor.

This makes it possible for a third-party bundle to ship its own studio color scheme and have it managed and branded through the Theme Manager, just like the built-in themes.

How Token Sets Relate to Themes​

  • A token set (theme dynamic type) defines the full set of design tokens that drive the interface. Its id (for example pimcore-dark) is what the theme record stores in its tokenSet field.
  • A theme (managed in the Theme Manager) references a token set and layers branding, imagery and a boot palette on top of it.

The two built-in token sets are:

Token set idShipped byUsed by theme
studio-default-lightstudio-ui corePimcore Light
pimcore-darkBackend Power ToolsPimcore Dark

Registering a Theme Dynamic Type​

Theme dynamic types are registered in the studio-ui frontend through the theme dynamic-type registry. A dynamic type extends DynamicTypeThemeAbstract, exposes a unique id, may declare the token sets it extends (to inherit their tokens), and returns its token overrides from getThemeConfig().

import { injectable } from '@pimcore/studio-ui-bundle/app'
import {
  DynamicTypeThemeAbstract,
  type PimcoreThemeConfig,
  studioThemeIds,
} from '@pimcore/studio-ui-bundle/modules/app'

export const myThemeId = 'my-theme'

@injectable()
export class DynamicTypeThemeMyTheme extends DynamicTypeThemeAbstract {
  id: string = myThemeId
  // Inherit all tokens from the light base and only override what changes.
  extends: string[] = [studioThemeIds.light]

  getThemeConfig (): PimcoreThemeConfig {
    return {
      token: {
        colorPrimary: '#ff6600',
        // ... further token overrides
      },
    }
  }
}

Register the dynamic type from your bundle's studio plugin, the same way the Pimcore Dark theme dynamic type is registered by Backend Power Tools. Once registered, the token set appears in the Theme Manager editor and can be selected for any theme.

Provide a translation key theme-manager.token-set.<token-set-id> so the editor dropdown shows a readable label instead of the raw id.

Gotcha: Do Not Ship a Partial components.Colors Block​

Themes are applied as nested theme providers, where a leaf theme inherits everything it does not override. This inheritance is a shallow merge per key: providing a components.Colors.<X> object replaces the ancestor's whole <X> object instead of merging into it. Several studio-ui consumers read nested Colors tokens without optional chaining, so dropping a sibling key crashes the interface.

Rule: do not ship a partial components.Colors block in a custom token set. Inherit the base's complete Colors and tint the interface through the flat tokens (for example colorFill, colorIcon*) instead.