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 (verified 2026-06-01,
379 lines). Analogous to ../auth/spec/CANONICAL-ROLES.md
for the auth component.
The token block lives in :root (lines 39–77). Components reference these tokens —
no hardcoded hex values appear in component markup or CSS. The only per-app override
is --accent on the ThemeShell root element via the Accent parameter.
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 |
#8b9097 |
Tertiary text, captions, units, nav eyebrow 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 is the only token overridden per-app. Pass it as ThemeShell's
Accent parameter: <ThemeShell Accent="#2f855a"> → emits
style="--accent: #2f855a" on the shell root, scoping the override to that subtree.
Status tokens — foreground
| Token |
Value |
Role |
--ok |
#2f9e44 |
Success / healthy / connected state text + icon color |
--warn |
#e8920c |
Warning / degraded state text + icon color |
--bad |
#e03131 |
Error / faulted / disconnected state text + icon color |
--idle |
#868e96 |
Unknown / offline / neutral state text + icon color |
Status tokens — tinted backgrounds
Pair each with the matching foreground token above (e.g. --ok-bg background with --ok
foreground text). 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 Info status variant (StatusState.Info, chip-info) is defined in layout.css
(not theme.css) and uses --accent-deep foreground on #e7ecfb background.
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 per-app override only. Override
--accent via ThemeShell's Accent
parameter. Do not override other tokens per-app.
- Status is colour, not iconography. The status palette (
--ok, --warn, --bad,
--idle) is the canonical way to communicate state. Use StatusPill for chips; use
.s-* utility classes for inline text.
- Token changes are breaking. Renaming or removing a token requires a SemVer major
bump of
ZB.MOM.WW.Theme and a coordinated update in every consumer app.
Joseph Doherty