6.7 KiB
UI Theme — Design Tokens
Canonical reference for every CSS custom property declared in theme.css. This is the
human-readable index of the Technical-Light design system. The authoritative source is
ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/css/theme.css (updated for the 1.0.0 candidate, November 13, 2026). Analogous to ../auth/spec/CANONICAL-ROLES.md
for the auth component.
The canonical token block lives in :root. Components reference these tokens —
no hardcoded hex values appear in component markup or CSS. Product overrides are scoped to the ThemeShell subtree through the complete accent parameter family. Semantic status/info tokens remain shared.
Surface tokens
| Token | Value | Role |
|---|---|---|
--paper |
#f4f4f1 |
Page background — warm off-white, never pure white |
--card |
#ffffff |
Raised surfaces: cards, panel headers, table heads |
Ink (text) tokens
| Token | Value | Role |
|---|---|---|
--ink |
#1b1d21 |
Primary text |
--ink-soft |
#5a6066 |
Secondary text, form labels |
--ink-faint |
#626970 |
Supporting text, captions, units and navigation labels |
Structure tokens
| Token | Value | Role |
|---|---|---|
--rule |
#e4e4df |
Hairline borders, row dividers |
--rule-strong |
#d2d2cb |
Emphasised hairlines: bar underlines, pill borders |
Accent tokens
| Token | Value | Role |
|---|---|---|
--accent |
#2f5fd0 |
Links, sort arrows, primary actions, active nav indicator |
--accent-deep |
#1e3f99 |
Hover / pressed accent; raw-value emphasis |
--accent-tint |
#eef2fc |
Selected surface |
--accent-border |
#cdd9f7 |
Subtle interactive border |
--accent-focus |
#1e3f99 |
Keyboard focus |
--on-accent |
#ffffff |
Primary action label |
--active-bg |
var(--accent-tint) |
Compatibility alias, rebound on .app-shell |
Use Accent, AccentDeep, AccentTint, AccentBorder, and AccentFocus together
for a product color family. Existing Accent-only callers still work; omitted values inherit.
Approved caller values must be trusted authored configuration. No inline style is emitted
when all five parameters are absent. Root semantic info stays blue through --info-ink.
Bootstrap .btn-primary and .btn-link bind component variables to this subtree's tokens.
Links and ghost text use the deep accent: green/teal primary colors need white labels
and fall below 4.5:1 as small text on warm paper. See the release decision for values.
Do not duplicate sizing or override group seams. Active links consume --accent-tint
directly, avoiding the root custom-property alias resolution trap. Actual hover, pressed,
focus and disabled styles still require the package canary browser checks.
Status tokens — signals and readable text
| Token | Value | Role |
|---|---|---|
--ok |
#2f9e44 |
Success / healthy / connected dots, stripes and charts |
--warn |
#e8920c |
Warning / degraded dots, stripes and charts |
--bad |
#e03131 |
Error / faulted / disconnected dots, stripes and charts |
--idle |
#868e96 |
Unknown / offline / neutral dots, stripes and charts |
Semantic text inks
| Token | Value | Role |
|---|---|---|
--ok-ink |
#236f34 |
Success/connected text |
--warn-ink |
#855000 |
Warning/degraded text |
--bad-ink |
#b42121 |
Fault/error text |
--idle-ink |
#535d66 |
Unknown/idle text |
--info-ink |
#1e3f99 |
Informational blue independent of product accent |
--warn-ink-deep |
#8a5a00 |
Existing deep warning emphasis |
.s-*, .chip-*, connection labels, counts and key/value text use semantic inks.
Dots retain the original saturated signal colors. Status labels remain textual; color
supplements their meaning. Normal-size text requires at least 4.5:1 on its actual surface.
Consumer opacity and local overrides must be checked in the browser as well as token math.
Status tokens — tinted backgrounds
Pair each with the matching readable ink (e.g. --ok-bg background with --ok-ink
foreground text). Keep saturated signal tokens for non-text indicators. Used by .chip-ok, .chip-warn, .chip-bad, .chip-idle classes.
| Token | Value | Role |
|---|---|---|
--ok-bg |
#e9f6ec |
Success tinted background |
--warn-bg |
#fdf1dd |
Warning tinted background |
--bad-bg |
#fceaea |
Error tinted background |
--idle-bg |
#eef0f2 |
Idle/neutral tinted background |
The
Infostatus variant (StatusState.Info,chip-info) is defined inlayout.css(nottheme.css) and uses independent blue--info-inkon--info-bg(#e7ecfb).
Typography tokens
| Token | Value | Role |
|---|---|---|
--mono |
'IBM Plex Mono', ui-monospace, 'Cascadia Mono', Consolas, monospace |
Monospaced stack — numeric / code values; tabular figures via font-variant-numeric: tabular-nums |
--sans |
'IBM Plex Sans', system-ui, -apple-system, 'Segoe UI', sans-serif |
UI body text stack — all prose, labels, nav |
IBM Plex fonts are vendored (three .woff2 in wwwroot/fonts/) — graceful system-font
fallback operates if the fonts are unreachable.
Bootstrap 5 override tokens
These tokens override Bootstrap 5's --bs-* custom properties so Bootstrap components
inherit the Technical-Light aesthetic. They are harmless if Bootstrap is absent.
| Token | Value | Role |
|---|---|---|
--bs-body-bg |
var(--paper) |
Bootstrap body background → paper |
--bs-body-color |
var(--ink) |
Bootstrap body text → primary ink |
--bs-body-font-family |
var(--sans) |
Bootstrap body font → IBM Plex Sans |
--bs-body-font-size |
0.9rem |
Bootstrap body size — slightly compact |
--bs-primary |
var(--accent) |
Bootstrap primary color → accent |
--bs-border-color |
var(--rule) |
Bootstrap border → hairline rule |
--bs-emphasis-color |
var(--ink) |
Bootstrap emphasis text → primary ink |
Usage rules
- Never hand-pick hex values in feature CSS. Use the tokens above or the utility
classes (
.s-ok,.s-warn,.s-bad,.s-idle,.chip-*,.kv .v.*). - One complete per-app accent family. Use the five
ThemeShellaccent parameters. Keep semantic status/info tokens uniform. Explicit supported dark schemes own their readable aliases and require separate verification. - Status has text as well as color. Use semantic inks for labels and values; retain
signal colors for dots/stripes/charts. Use
StatusPillfor labeled chips and.s-*utility classes for inline text. Do not rely on color alone. - Token changes are breaking. Renaming or removing a token requires a SemVer major
bump of
ZB.MOM.WW.Themeand a coordinated update in every consumer app.