# ZB.MOM.WW.Theme
Shared Technical-Light UI kit for the ZB.MOM.WW SCADA family: design tokens + IBM Plex
fonts (static web assets) and a canonical side-rail shell + widgets. The kit ships one
.NET 10 Razor Class Library (RCL) with CSS custom-property tokens, the three IBM Plex
woff2 fonts, and side-rail layout CSS — all served from `_content/ZB.MOM.WW.Theme/…` —
plus a set of Blazor SSR components that carry no inline colours and reuse the token
classes. Bootstrap 5 is **not** vendored; each app keeps its own Bootstrap link.
The mobile rail and collapsible sections use native ``/``, so
basic chrome works in static SSR with Bootstrap CSS. `ThemeScripts` also ships the
optional shared `nav-state.js` enhancer for persisted section state; include it once
before `
`. No Bootstrap collapse bundle is required.
## 1.0.1 narrow-grid patch
The canonical card grid keeps its 290px preferred minimum while allowing a card to
shrink to the available column width. This prevents clipping/overflow in narrow
reflow and zoomed layouts. Below 320px effective viewport width, the KPI grid
uses one column so labels and large totals retain their available width. Desktop geometry, colors, fonts and component APIs retain
the 1.0.0 contract. Consumers should adopt one exact patch version together; do not
copy per-application grid fixes or repack the immutable 1.0.0 artifacts.
## Accessible component contracts (1.0.0)
`TechField` associates its existing label, help and error with a caller-owned input.
Use stable unique IDs for repeated fields; the component does not inspect or rewrite
arbitrary child content:
```razor
```
Only reference a hint/error ID when that content exists. The form owns error focus and
announcements. Existing callers can omit the new parameters while migrating.
`TechButton Busy="@Saving" BusyText="Saving changes…"` disables during the operation,
exposes `aria-busy`, and restores its child label afterward. Caller-supplied `disabled`
is still honored, and button type, size and class composition stay intact. Keep a
persistent caller-owned outcome region beside the action:
```razor
Save changes
@SaveOutcome
```
Update `SaveOutcome` on completion/failure with recovery information, never a secret
value or every polling tick. The button spinner is decorative; it is not the live region.
`ThemeShell` accepts the existing `Accent` plus optional `AccentDeep`, `AccentTint`,
`AccentBorder` and `AccentFocus`. Supply the complete authored family for matching
hover, selected, border and keyboard states. Omitted values inherit; supplying none
emits no inline style. Semantic info remains blue and status meanings stay shared.
```razor
...
```
Use `--ok-ink`, `--warn-ink`, `--bad-ink`, `--idle-ink` for small status text;
retain `--ok`, `--warn`, `--bad`, `--idle` for dots/stripes/charts. Primary and ghost
Bootstrap buttons consume the scoped accent family while preserving shared sizing.
Interaction recipes: [`INTERACTION-RECIPES.md`](../components/ui-theme/spec/INTERACTION-RECIPES.md).
Published release acceptance is recorded in the parent Theme 1.0.0 release evidence. Do not repack or replace its immutable artifacts.
## Adopt
1. Reference the NuGet package in your app; keep your own Bootstrap 5 `` in `App.razor`.
2. In `App.razor` `
`, **after** your Bootstrap link, add ``:
```razor
@* Bootstrap — yours, not vendored by the kit *@
```
3. Make your `MainLayout` a thin delegate to `ThemeShell` — `@layout` cannot pass
parameters, so `ThemeShell` is a regular component and `MainLayout` is a 3-line wrapper:
```razor
@* Layouts/MainLayout.razor *@
@inherits LayoutComponentBase
@* session info / sign-out link *@@Body
```
Add `@using ZB.MOM.WW.Theme` to your `_Imports.razor` so all components are available
without per-file usings.
### Login page
Use `` for the sign-in form. The card posts to a server endpoint
(`/auth/login` by default) so `SignInAsync` can run before the response starts.
You **must** inject `` inside the card and **validate `ReturnUrl`
server-side** before redirecting (open-redirect risk):
```razor
```
## Components
| Component | Parameters (key) | Notes |
|---|---|---|
| `ThemeHead` | — | Emits `` tags for `theme.css` and `layout.css`. Place in `` after Bootstrap. |
| `ThemeShell` | `Product`*, `Accent`, `Logo`, `Nav`, `RailFooter`, `ChildContent`, `ScrollNav` | Side-rail chassis. Not a layout — delegated to from `MainLayout`. The shell fills the viewport (`min-height: 100dvh`, `100vh` fallback; 0.5.3) and the lg+ sticky rail is `100dvh` tall, so no consumer needs its own `min-height: 100vh` wrapper. `Accent` overrides `--accent` token. `ScrollNav` (opt-in, default false; 0.5.2) wraps `Nav` in a `.rail-scroll` pane and fills the rail height on lg+ so a long nav scrolls while `RailFooter` stays pinned. |
| `BrandBar` | `Product`*, `Logo` | Brand glyph + product name; rendered inside `ThemeShell`'s rail header. |
| `NavRailItem` | `Href`*, `Text`*, `Icon`, `Match` | Wraps ``. |
| `NavRailSection` | `Title`*, `Expanded` (default `true`), `ChildContent` | CSS-only collapsible `` group; no JS, works in static SSR. |
| `StatusPill` (`StatusState`) | `State`* (`Ok`/`Warn`/`Bad`/`Idle`/`Info`), `ChildContent` | Inline chip. `StatusState` enum is in `ZB.MOM.WW.Theme`. |
| `LoginCard` | `Product`*, `Action` (default `/auth/login`), `ReturnUrl`, `Error`, `ChildContent` | Static form-POST sign-in card. Inject `` via `ChildContent`; validate `ReturnUrl` server-side. |
| `TechButton` (`ButtonVariant`, `ButtonSize`) | `Variant` (`Primary`/`Secondary`/`Danger`/`Ghost`), `Size` (`Default`/`Small`/`Large`), `Class`, `Type`, `Busy`, `ChildContent`, splatted attrs | `Busy` disables the button and shows a spinner. Caller classes are composed with required variant/size classes. |
| `TreeTable` (`ITreeRow`) | `Rows`*, `Head`*, `Row`*, `Label`*, `Collapsed`, `OnToggle` | Stateless preorder tree table. The caller filters visible rows and owns expansion state. |
| `TechCard` | `Title`, `Header`, `ChildContent`, `Footer`, `Class` | Panel with optional head/body/footer slots. |
| `TechField` | `Label`*, `Hint`, `Error`, `ChildContent` | Form field wrapper with label, hint text, and inline error. |
\* `EditorRequired` parameter.
Flat namespace: all components and enums live in `ZB.MOM.WW.Theme`. One `@using` covers everything.
## Static assets
Served at `_content/ZB.MOM.WW.Theme/…` by the ASP.NET static-web-asset pipeline:
| Path | Contents |
|---|---|
| `css/theme.css` | Design tokens (`--accent`, `--ok`, `--warn`, …), typography, utility helpers |
| `css/layout.css` | Side-rail shell layout, collapsible nav, `StatusPill` variants, card/field helpers, Bootstrap `.btn` sizing, shared page/group headers, badges, row actions, info notices, payload blocks and tree-table styles |
**Bootstrap button sizing (new in 0.4.0).** The kit now normalizes `.btn` / `.btn-sm` against its
0.9rem body via `--bs-btn-*` variable overrides, because Bootstrap hard-codes
`--bs-btn-font-size: 1rem`. Several consuming apps had written this same block into their own
stylesheets; **trim the local copy when you bump to 0.4.0** — trim rather than delete, because a
local `.btn` may also carry app-specific *shape* declarations the kit does not ship.
**This is not universal, and checking it takes two greps, not one.** An earlier version of this note
claimed all five consumers carried the block. They do not — and the follow-up correction, that the
missing-block app would therefore be *restyled* by the bump, was also wrong.
| Question | Check |
|---|---|
| Does the app declare its own `.btn` sizing? | `grep bs-btn-font-size`, excluding `lib/bootstrap` |
| Does the app **use** Bootstrap buttons at all? | count `class="…"` values carrying a bare `btn` token |
HistorianGateway answers **no to both** — all 15 of its buttons use the kit's own `.rail-btn` chassis
class — so the kit's `.btn` rule matches nothing there and bumping it changes nothing visible. The
first question alone is misleading in both directions: "no local block" does **not** imply "the kit
now supplies sizing the app was missing."
Size buttons by overriding the `--bs-btn-*` variables, never by redeclaring box properties — the
`.btn-group` seam and radius machinery reads those variables, so a literal `font-size` at equal
specificity silently reduces `.btn-sm` to a padding-only difference.
Rail-footer actions: `class="rail-btn"` is the inline default; add `rail-btn-block`
(`class="rail-btn rail-btn-block"`) for a full-width footer button. Use the modifier rather than
redeclaring `.rail-btn` in an app stylesheet — a local override that sets `width: 100%` overflows
the rail, because the width resolves against the containing block and the inline version's
`0 0.6rem` side margins are then added on top.
| `fonts/ibm-plex-sans-400.woff2` | IBM Plex Sans Regular |
| `fonts/ibm-plex-sans-600.woff2` | IBM Plex Sans SemiBold |
| `fonts/ibm-plex-mono-500.woff2` | IBM Plex Mono Medium |
| `js/nav-state.js` | Optional shared section persistence via `ThemeScripts` |
`theme.css` declares `@font-face` with `url('../fonts/…')` — correct relative path from
`css/` to `fonts/`. (OtOpcUa's original `url('fonts/…')` was a latent 404; the kit fixes it.)
All colours are CSS custom-property tokens declared once in `theme.css`'s `:root` block —
no hardcoded hex appears outside it. Derived border/hover/wash shades (e.g. `--ok-border`,
`--warn-ink`, `--info-bg`, `--hover-bg`, `--active-bg`, `--zebra-bg`) are named tokens too,
so a token-block edit re-themes the whole kit.
## Build
```bash
# from ZB.MOM.WW.Theme/
dotnet build -c Release # TreatWarningsAsErrors — expect 0 warnings
dotnet test # run the current component and static-asset suite
./build/pack.sh # exact version from Directory.Build.props
```
## 0.5.0 migration (published 2026-11-04)
The tested package was published to the shared Gitea feed on 2026-11-04.
An independent feed download exactly matched the reviewed artifact (SHA256
`374511ebaaa15be71024051e896c8e7e59a8951b0d51a990fa48fbe378ac6485`).
The ignitionoee router deployed this package to CR on 2026-11-04; other consumer
rollouts remain separate. It retains the 0.4.2 `.rise` animation
fill-mode fix. The published package is immutable; this source documentation
update does not repack or replace it.
The shell now keeps page content visible when mobile navigation is collapsed.
The outer disclosure's `::details-content` wrapper is dissolved at every width;
an explicit mobile closed-state selector hides only the rail. Author display
rules retain the page for older browsers without `::details-content` support.
The menu remains a native keyboard-accessible disclosure without custom JavaScript.
Mobile pages are constrained to the shell width so wide tables scroll inside their
table wrapper instead of widening the whole document.
The remaining ignitionoee `app.css` rules now ship in `layout.css`: page and section
headers/meta, group headings/meta, count badges, `.notice.info`, `.row-actions`,
**`td.row-actions`**, and `.check-data`. Consumers may delete matching local copies
after adopting this package. The element-qualified row-action selector must remain:
the bare class loses to `.data-table td` regardless of stylesheet load order.
Use `Size="ButtonSize.Small"` or `Size="ButtonSize.Large"` on `TechButton`.
`Class="my-action"` and an attribute dictionary's `class` value are composed with
the required button classes. A lowercase `class` supplied in Razor binds to `Class`
as normal Blazor parameter binding. Supplying both spellings as separate component
parameters is unnecessary; use `Class` plus `AdditionalAttributes` when merging two
sources. Explicit `Busy` and `Type` continue to control the underlying attributes.
Implement `ZB.MOM.WW.Theme.ITreeRow` on a consumer's row model (`Key`, `Depth`,
`HasChildren`). Feed `TreeTable` visible rows in preorder, with each subtree
contiguous after its parent. `Head` supplies all header cells; `Row` supplies cells
after the component's name cell; `Label` supplies the name. `OnToggle` reports the
stable row key, and the caller supplies a new `Collapsed` state and filters `Rows`.
The component never filters or mutates caller state. Indentation supports arbitrary
depth through `--tt-depth`; styles ship once, with no per-instance stylesheet.
Leaf controls preserve label alignment and omit subtree ARIA attributes. Interactive
expand/collapse requires an interactive Blazor host and Bootstrap Icons for chevrons.
The test harness uses bUnit 2.7.2 and directly pins AngleSharp 1.5.2. The patched parser
([GHSA-pgww-w46g-26qg](https://github.com/advisories/GHSA-pgww-w46g-26qg)) is verified
with full render/query/event test suites across the family. These
dependencies belong to the test project; the Theme runtime package gains none.