Files
scadaproj/components/ui-theme/spec/DESIGN-TOKENS.md
T

5.6 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. 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 #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 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 — 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 Info status variant (StatusState.Info, chip-info) is defined in layout.css (not theme.css) and uses independent blue --info-ink on --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

  1. 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.*).
  2. One per-app override only. Override --accent via ThemeShell's Accent parameter. Do not override other tokens per-app.
  3. Status has text as well as color. Use semantic inks for labels and values; retain signal colors for dots/stripes/charts. Use StatusPill for labeled chips and .s-* utility classes for inline text. Do not rely on color alone.
  4. 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.