Theming

On this page

Every kit component, chart and module comes in light and dark. Colours come from tokens (CSS custom properties) that switch with the mode, so anything you build from tokens switches too. This page covers how the mode is chosen, the tokens, and the type scale.

How the mode is chosen

Where the app runsMode
Inside Performance HubThe user's Performance Hub choice. It switches live when they change it.
A plain browser tabThe operating system's light or dark setting.
Any page with ?phTheme=light or ?phTheme=dark in the addressThat mode, whatever the OS says (useful for testing and screenshots).

The right colours apply before the first paint, before any script runs, so there's no flash of the wrong mode. When the mode changes, the kit sets class="dark" (or light) and data-theme on <html>, and redraws kit charts and maps.

Inside Performance Hub, the host decides the mode: don't show your own light/dark toggle there. If the app also runs standalone and you want a toggle in that case, show it only when phApp.embedded() is false, and switch with phApp.setTheme('light' | 'dark' | 'auto').

phApp.theme();                                  // 'light' or 'dark'
const stop = phApp.onThemeChange((mode) => redrawMyCanvas(mode));

Colour tokens

Colour tokensColour tokens

Figure 1: The main colour tokens

Most colour tokens hold three RGB channel values (for example 0 148 247), so you can add transparency:

.my-panel {
  background: rgb(var(--ph-surface));
  border: 1px solid rgb(var(--ph-grayOutline));
  color: rgb(var(--ph-primary));
}
.my-highlight {
  background: rgb(var(--ph-blue) / 0.08);
}

Never hard-code white, black or hex colours: they look wrong in one of the two modes.

Surfaces

TokenLightDarkUse for
--ph-page#f8fafc#0f1117The page background
--ph-surface#ffffff#0f1117Cards, tables and inputs
--ph-surfaceRaised#ffffff#1a1b1fDialogs, drawers, menus and toasts
--ph-container#f6f8fa#23262eHover fills, table headers, tracks

Text

TokenLightDarkUse for
--ph-primary#30313d#e6e8ecBody text and headings
--ph-secondary#6a7383#9ba3b0Descriptions, labels and hints
--ph-grayDisabled#a3acba#6b7280Placeholders and disabled text

Borders

TokenLightDarkUse for
--ph-grayOutline#ebeef1#2e323cCard and table borders, dividers
--ph-borderLight#e3e8ee#2e323cLight borders
--ph-borderDark#d5dbe1#3a3f4aHover borders
--ph-grayBorder-1#c1c9d2#3a3f4aSwitch track (off)
--ph-grayBorder-2#8792a2#565e6bNeutral status dots

Brand

TokenLightDarkUse for
--ph-blue#0094f7#33a9f8Primary buttons, links, focus, selection
--ph-purple#7c00f7sameAccents
--ph-cyan#0b91aesameAccents
--ph-pink#ff6cb3sameAccents

Status

Status colours come in pairs: -1 for text and icons, -2 for the fill behind them. -3 is a strong fill for dots, bars and danger buttons.

TokenLightDarkUse for
--ph-green-1 / --ph-green-2#006908 / #d7f7c2#34d399 / #142f23Success text / fill
--ph-orange-1 / --ph-orange-2#a82c00 / #f6e6b9#fbbf24 / #382812Warning text / fill
--ph-red-1 / --ph-red-2#b3093c / #ffe7f2#fb7185 / #3d1a23Danger text / fill
--ph-purple-1 / --ph-purple-2#581caf / #ede9fe#c4b5fd / #2b204aPurple badge text / fill
--ph-info-color / --ph-info-bg#005994 / #e5f5ff#38bdf8 / #102a3cInfo text / fill
--ph-green-3, --ph-orange-3, --ph-red-3#00a40d, #f7b835, #e53935sameStatus dots, progress fills, danger buttons

Chart series

Charts, calendar events and map markers take their colours from eight series tokens, in this order:

TokenLightDark
--ph-chart-1#0094f7#33a9f8
--ph-chart-2#7c00f7#a78bfa
--ph-chart-3#0b91ae#22d3ee
--ph-chart-4#ff6cb3#ff8fc4
--ph-chart-5#f7b835#fbbf24
--ph-chart-6#00a40d#34d399
--ph-chart-7#e53935#fb7185
--ph-chart-8#6a7383#9ba3b0

Form inputs

Input tokens are plain hex colours rather than RGB channels: --ph-input-bg (#ffffff / #0e1116), --ph-input-border (#e3e8ee / #2a2f39) and --ph-input-border-hover (#d5dbe1 / #3a4150). Use them as var(--ph-input-bg).

Typography

Type scaleType scale

Figure 2: The type scale

The kit uses Source Sans Pro, served with the kit in regular (400), italic, semibold (600) and bold (700). Code uses the system monospace font.

Element or classSizeWeight
Body text14pxRegular
.ph-page-title (and h1)24px (20px on phones)Bold
h2, .ph-dialog-title18pxBold
.ph-card-title16pxBold
.ph-section-title, h315pxSemibold
Buttons and inputs13pxSemibold (buttons), regular (inputs)
.ph-text-sm13pxRegular
.ph-text-xs12pxRegular
.ph-stat-value26pxBold, tabular figures
code, pre12pxMonospace

.ph-num switches to tabular figures so numbers line up in columns; tables use it for every numeric column.

Shape, spacing and focus

Token or ruleValue
--ph-radius6px: buttons, inputs, badges
--ph-radius-lg8px: cards, tables, dialogs
--ph-control-height30px: buttons and inputs
--ph-shadow-raisedThe shadow under menus, dialogs and toasts (darker in dark mode)
--ph-focus-ringA 3px blue ring on focused controls
Page padding24px (16px on phones)
Space between page sections16px
Card padding24px (16px for --compact)

The keyboard focus outline is always visible (:focus-visible), in blue.

Motion

When the viewer asks their system for reduced motion, the kit turns off its animations: skeleton shimmer, spinners, dialog and toast transitions, chart animations and the live status pulse. You don't need to handle prefers-reduced-motion for kit components.

Printing

Pages print in light mode. Toolbars, buttons, menus, pagination, toasts, dialogs and the page actions are hidden, along with anything marked .ph-no-print. Links to other sites print their address after the link text.

In React and Tailwind

React apps get the same tokens. The Tailwind preset maps them to ph-* classes (bg-ph-surface, text-ph-secondary, border-ph-grayOutline), and the MUI theme uses the same palette. See React.

  • Charts: colouring your own Chart.js charts with the series tokens
  • Reference: every token and class in one place