# 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`](../../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 `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 complete per-app accent family.** Use the five `ThemeShell` accent parameters. Keep semantic status/info tokens uniform. Explicit supported dark schemes own their readable aliases and require separate verification. 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.