Custom Design Systems

What it is

Every Power UI theme is built on the design system: semantic tokens like @bg-primary, @text-secondary and @brand-default, a radius and spacing scale, and a type scale. Visuals refer to tokens rather than fixed colours, which is why one theme works in light and dark mode.

A custom design system is your layer on top. It starts as the Power UI default and stores only what you change, so anything you leave alone keeps following the default (and improves when we improve it). Your design system is saved with the theme, so the theme stays complete wherever it goes: the dashboard, a download, the desktop app or the Power UI MCP.

Getting started

1. Open a theme in the studio and choose Design system in the left sidebar.
2. Give your system a name. Pick a token, say Backgrounds → Primary background, and set its light and dark values.
3. Watch the preview card at the top of the panel and the Power BI preview change as you edit. Switch the preview between Light and Dark to check both.
4. Choose Add token to create tokens of your own, such as a card surface or a KPI colour.
5. Save the theme. To reuse the system in other themes, choose Save to keep it in your library.

Changing built-in tokens

Every built-in token is listed by group: Backgrounds, Text, Borders, Brand, Accent, Success, Warning, Error, Radius, Spacing and the Type scale. A changed token shows an amber dot and its default, and Reset puts it back. Changing @radius-default, or the radius preset it points at, changes the corners of every visual that uses the default radius. The Global section's padding presets follow your @space-2 to @space-5 values.

Your own tokens

Custom tokens can be colours (a light and a dark value), radius, spacing or text sizes. Names start with @ and use lowercase letters, numbers and dashes, like @surface-card. Give them a group and they appear under Your tokens at the top of every colour picker in the studio, ready for backgrounds, borders, fonts and data labels. The AI assistant can use them too.

A few names belong to Power BI and can't be redefined: the data colours (@theme-1…), the structural colours (@foreground, @tableAccent…) and the raw palette steps (@brand-500, @neutral-6).

Linking tokens

Instead of a colour, a token can link to another token. That's how real design systems are built: semantic tokens point at primitives. Link @surface-card to @bg-secondary, and it follows whatever your background becomes. Power UI follows links a few steps deep and refuses a link that loops back on itself.

Links to data colours and structural colours (@foreground, @tableAccent, listed under Structural colors in the link picker) stay live in Power BI. If @brand-default links to @theme-1, the exported theme refers to Power BI's first theme colour rather than a fixed hex, so changing the report's colours later still flows through. Every other token is written into the theme as its colour or number.

Your library and your team

Save keeps the system in your library. In any other theme, pick it from the list at the top of the Design system panel to apply it. Applying copies the system into the theme, so editing one theme never changes another by surprise; choose Update to write your changes back to the library copy, or Save as new to keep both. On a Team plan, Save for your team shares the system with everyone in your organization workspace.

Removing a system from the library never changes the themes that use it: each keeps its own copy.

Import and export

Export JSON downloads the system as a small file you can keep in git, review in a pull request or send to a colleague; Import JSON brings one in. Importing checks every token and tells you about any it skipped. The format is short and readable:

{
  "format": "powerui.design-system",
  "version": 1,
  "name": "Contoso",
  "overrides": {
    "@bg-primary":     { "type": "color", "light": "#FFFDF8", "dark": "#121110" },
    "@brand-default":  { "type": "color", "light": "@theme-1", "dark": "@theme-1" },
    "@radius-default": { "type": "radius", "value": 10 }
  },
  "custom": {
    "@surface-card": {
      "type": "color", "name": "Card surface", "group": "Surfaces",
      "light": "@bg-secondary", "dark": "#1B1A18"
    },
    "@kpi-up":   { "type": "color", "name": "KPI up", "light": "#0A7F3F", "dark": "#3BD47F" },
    "@gap-card": { "type": "spacing", "value": 14 }
  }
}

overrides change built-in tokens; customholds yours, and a custom token can't reuse a built-in name like @bg-primary (put that change under overrides). Colours are a hex (#RRGGBB or #RRGGBBAA) or a token, including the structural colours (@tableAccent). Radius and spacing are in px, text sizes in points, as in Power BI. A missing dark value takes the light one.

Plans

Everyone can build a design system, preview it and save it with their themes, and keep one in the library. Pro and Team keep as many as they like, share them with a team, and import and export them as JSON.