Theming
Tokens in extensions
Extensions that draw inside Studio take every color, size and font from the active theme, never from literals. Each kind of extension gets the tokens in its own shape, and all three update the moment the theme changes.
Where extensions stand
The token export described here is built and tested in Studio. Studio's plugin host runs source plugins today; docks, which this page is mostly about, are planned. See Extensions for what's built and what's coming.
The theme changes when someone picks another theme, saves a theme file, or drags a color in Theme Studio. Whatever the cause, your extension follows without a reload.
Web docks: CSS custom properties
Studio injects a sheet before your own CSS. Each token is a custom property named --velum- plus the token's name with its dots turned into dashes. Here is every one, as a web dock sees them under Studio Dark:
:root {
color-scheme: dark;
--velum-color-window: #0c0d0f;
--velum-color-surface: #121316;
--velum-color-surface-raised: #1a1b1f;
--velum-color-surface-card: None;
--velum-color-surface-sunken: #0a0a0c;
--velum-color-surface-overlay: #1e1f24;
--velum-color-hover: rgba(255, 255, 255, 0.045);
--velum-color-pressed: rgba(255, 255, 255, 0.08);
--velum-color-selection: rgba(233, 197, 139, 0.22);
--velum-color-border: rgba(255, 255, 255, 0.07);
--velum-color-border-strong: rgba(255, 255, 255, 0.13);
--velum-color-divider: rgba(255, 255, 255, 0.06);
--velum-color-text: #ededf0;
--velum-color-text-secondary: #a0a0a8;
--velum-color-text-tertiary: #82828b;
--velum-color-text-disabled: #4b4b52;
--velum-color-accent: #e9c58b;
--velum-color-accent-hover: #f1d19d;
--velum-color-accent-pressed: #dab478;
--velum-color-accent-text: #1d1406;
--velum-color-accent-strong: #e9c58b;
--velum-color-live: #d42d25;
--velum-color-live-text: #ffffff;
--velum-color-success: #30d158;
--velum-color-warning: #ff7a00;
--velum-color-warning-text: #1d1406;
--velum-color-danger: #ff453a;
--velum-color-danger-text: #230c09;
--velum-color-focus: rgba(233, 197, 139, 0.72);
--velum-color-preview-backdrop: #08080a;
--velum-color-preview-canvas-edge: rgba(255, 255, 255, 0.1);
--velum-color-preview-selection: #e9c58b;
--velum-color-preview-handle: #ffffff;
--velum-color-preview-guide: #ff3b8b;
--velum-color-preview-grid: rgba(255, 255, 255, 0.1);
--velum-color-scrollbar: rgba(255, 255, 255, 0.14);
--velum-color-scrollbar-hover: rgba(255, 255, 255, 0.26);
--velum-color-tooltip: #2a2b30;
--velum-color-tooltip-text: #f2f2f5;
--velum-font-family: "None", system-ui, sans-serif;
--velum-font-size-body: 13px;
--velum-font-size-small: 12px;
--velum-font-size-caption: 11px;
--velum-font-size-title: 15px;
--velum-font-weight-regular: 400;
--velum-font-weight-medium: 500;
--velum-font-weight-semibold: 600;
--velum-radius-small: 4px;
--velum-radius-control: 6px;
--velum-radius-panel: 10px;
--velum-space-xs: 4px;
--velum-space-s: 8px;
--velum-space-m: 12px;
--velum-space-l: 16px;
--velum-metric-control-height: 28px;
--velum-metric-border: 1px;
--velum-metric-scrollbar: 8px;
--velum-metric-dock-titlebar: 30px;
--velum-metric-preview-min-width: 320px;
--velum-metric-preview-min-height: 180px;
--velum-metric-window-min-width: 0px;
--velum-metric-window-min-height: 0px;
--velum-metric-window-min-width-macos: None;
--velum-metric-window-min-height-macos: None;
--velum-metric-window-min-width-windows: None;
--velum-metric-window-min-height-windows: None;
--velum-metric-window-min-width-linux: None;
--velum-metric-window-min-height-linux: None;
--velum-icon-stroke: 1.75;
}- Colors are CSS colors:
#rrggbbwhen opaque,rgba(r, g, b, a)when not. - Sizes (
font.size.*,radius.*,space.*,metric.*) are inpx. - Font weights and
icon.strokeare plain numbers. color-schemeisdarkorlight, from the theme'sappearance, so form controls and scrollbars the web view draws itself match.
Use them as var(--velum-color-text). When the theme changes, Studio replaces the sheet in place, and anything written with var() follows.
.row { padding: var(--velum-space-s) var(--velum-space-m); color: var(--velum-color-text); }
.row:hover { background: var(--velum-color-hover); }
.row.selected { background: var(--velum-color-selection); }QML docks: VelumTheme
QML docks see a singleton named VelumTheme. Its tokens map has every token by name: colors as QML color, numbers as real, strings as string. Bind to it and your item repaints on every theme change:
Rectangle {
color: VelumTheme.tokens["color.surface"]
radius: VelumTheme.tokens["radius.panel"]
Text {
text: qsTr("Hello")
color: VelumTheme.tokens["color.text"]
font.family: VelumTheme.tokens["font.family"]
font.pixelSize: VelumTheme.tokens["font.size.body"]
}
}It also has id, name, appearance ("dark" or "light"), dark (true unless the theme is light) and revision, which goes up by one on every change.
Native plugins: theme_token
Native (C ABI) plugins get two host calls for whatever they draw themselves, such as a source's placeholder art:
host->theme_token(key, key_len, out, out_cap)copies a token's value into your buffer (NUL-terminated when it fits) and returns its full length in bytes, or -1 if there's no such token. Memory never crosses the boundary: you own the buffer. Call it without_cap0 to ask the length first.host->on_theme_changed(fn, user)callsfn(user)after every theme change, on Studio's UI thread. Stop it with the id it returns.
Values are text: colors as #RRGGBBAA, numbers in plain decimal (sizes in pixels), font.family as written. Reading is safe from any thread.
char accent[16];
int32_t n = host->theme_token("color.accent", 12, accent, sizeof accent); /* "#0A84FFFF" under Studio Dark */
if (n < 0) { /* no such token */ }Rules that keep extensions themeable
- No literal colors or font names in your CSS, QML or drawing code. The only exceptions are
transparent,currentColorand colors inside images. The extension host's load-time linter will report the rest. - Check your dock under both built-in themes, Studio Dark and Studio Light, and a high-contrast one. Theme Studio makes one in a minute: start from an accent color, then push the text colors further.
- Text on a background must pass WCAG AA (4.5:1). Use the same tokens for the same jobs as Studio does (the pairs it checks) and your dock passes whenever the theme does.
The full rules for extensions, beyond tokens, are the design guidelines.

