152 lines
6.7 KiB
Markdown
152 lines
6.7 KiB
Markdown
# 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.
|