11 KiB
UI Theme — normalized target spec
Status: Implemented shared system; 1.0.0 accessible candidate in validation. Current published version remains 0.5.3 until the release gate closes. Original current-state documents retain historical evidence. Actual source pins, version policy and rollout state are in release decision and the execution ledger.
0. Scope
Normalized here: the "Technical-Light" design token set; IBM Plex typography;
the canonical side-rail layout shell; the component kit (shell, status pill, login card,
common controls); delivery via the ZB.MOM.WW.Theme RCL.
Explicitly NOT normalized (domain-specific — keep per project): each app's site.css
residual page layout, route/page content, and app-specific scoped .razor.css files.
The kit owns the chrome and tokens, not the app's domain screens. Authorization logic
remain per-project. Shared nav-section persistence belongs to ThemeScripts/nav-state.js.
1. Design tokens
All color, typography, and structural values are expressed as CSS custom properties
declared on :root in theme.css. Components carry no hardcoded hex values —
everything references these tokens. Bootstrap 5 --bs-* variables are overridden to
align Bootstrap's defaults with the Technical-Light palette.
Per-app accents use Accent, AccentDeep, AccentTint, AccentBorder and
AccentFocus on the shell subtree. Semantic status and informational colors stay
shared. Supported dark schemes require separately verified readable aliases.
See DESIGN-TOKENS.md for the full enumeration.
Canonical token groups:
- Surface —
--paper,--card - Ink (text) —
--ink,--ink-soft,--ink-faint - Structure —
--rule,--rule-strong - Accent —
--accent,--accent-deep,--accent-tint,--accent-border,--accent-focus,--on-accent - Status — signal
--ok/--warn/--bad/--idle, matching-inktext and-bgsurfaces; independent--info-ink/--info-bg - Typography —
--sans(IBM Plex Sans),--mono(IBM Plex Mono) - Bootstrap overrides —
--bs-body-bg,--bs-body-color,--bs-body-font-family,--bs-body-font-size,--bs-primary,--bs-border-color,--bs-emphasis-color
2. Typography
IBM Plex is vendored (three .woff2 files in the RCL's wwwroot/fonts/); no CDN
dependency so air-gapped fleet deployments keep working.
| Font | Weight | File |
|---|---|---|
| IBM Plex Sans | 400 (regular) | ibm-plex-sans-400.woff2 |
| IBM Plex Sans | 600 (semibold) | ibm-plex-sans-600.woff2 |
| IBM Plex Mono | 500 (medium) | ibm-plex-mono-500.woff2 |
The @font-face declarations in theme.css use url('../fonts/ibm-plex-*.woff2')
— the correct relative path from css/theme.css to fonts/. This is the canonical
path; per-app copies that use url('fonts/…') or url('/fonts/…') are incorrect
(OtOpcUa's url('fonts/…') causes a latent 404 silently masked by system-font fallback).
The RCL fixes this permanently for all consumers.
3. Canonical side-rail layout
The one canonical layout is a side rail (not a top nav bar). Layout structure:
┌─────────────────────────────────────────────────┐
│ .app-shell (flex-row on lg+; flex-col on sm) │
│ ┌──────────────────┐ ┌───────────────────────┐ │
│ │ nav.side-rail │ │ main.page │ │
│ │ .brand │ │ (page body / @Body) │ │
│ │ [Nav slot] │ │ │ │
│ │ .rail-foot │ │ │ │
│ └──────────────────┘ └───────────────────────┘ │
└─────────────────────────────────────────────────┘
Rail width / breakpoint: the rail collapses to a hamburger toggle (data-bs-toggle=collapse)
below Bootstrap's lg breakpoint. Above lg, it is always visible.
ThemeShell is a component, not a layout. @layout in Blazor cannot accept
parameters. Each app therefore keeps a thin 3-line MainLayout : LayoutComponentBase
that delegates to <ThemeShell> with its per-app Product, Accent, Nav, and
RailFooter values (see §4 and ../shared-contract/ZB.MOM.WW.Theme.md).
Nav sections within the rail are CSS-only collapsibles (<details open>). Apps that need
interactive expand-state persistence (e.g. OtOpcUa's cookie-persisted nav) may keep a
bespoke interactive NavSection; the RCL's NavRailSection works without JS and is
compatible with static Blazor SSR.
4. Component contract
Namespace: ZB.MOM.WW.Theme. All components are themed via CSS custom properties —
no inline colors. One @using ZB.MOM.WW.Theme covers every component and enum.
Static-asset entry point
| Component | Description |
|---|---|
ThemeHead |
Emits <link> tags for theme.css and layout.css. Drop in <head> after Bootstrap. |
Layout shell
| Component / Type | Key parameters | Notes |
|---|---|---|
ThemeShell |
Product*, Accent, AccentDeep, AccentTint, AccentBorder, AccentFocus, ScrollNav, Logo, Nav, RailFooter, ChildContent |
Canonical side-rail chassis. Not a LayoutComponentBase — delegated to from MainLayout. Accent overrides --accent for the shell subtree. |
BrandBar |
Product*, Logo |
Brand glyph + product name; rendered in the rail header inside ThemeShell. |
NavRailItem |
Href, Text, Icon, Match |
Wraps <NavLink class="rail-link">. Active state via Blazor NavLink. |
NavRailSection |
Title*, Expanded (default true), ChildContent |
CSS-only <details> collapsible group; no JS, works in static SSR. |
Thin-MainLayout delegation pattern (required; see §3):
@* Components/Layout/MainLayout.razor *@
@inherits LayoutComponentBase
<ThemeShell Product="OtOpcUa" Accent="#2f5fd0">
<Nav>
<NavRailSection Title="Navigation">
<NavRailItem Href="/" Text="Overview" Match="NavLinkMatch.All" />
<NavRailItem Href="/clusters" Text="Clusters" />
</NavRailSection>
</Nav>
<RailFooter>@* session info / sign-out *@</RailFooter>
<ChildContent>@Body</ChildContent>
</ThemeShell>
Widgets
| Component / Type | Key parameters | Notes |
|---|---|---|
StatusPill |
State* (StatusState), ChildContent |
Inline chip. StatusState enum: Ok, Warn, Bad, Idle, Info. Maps state → token class (chip-ok, …). |
LoginCard |
Product*, Action (default /auth/login), ReturnUrl, Error, ChildContent |
Static form-POST sign-in card. ChildContent for <AntiforgeryToken/>. Validate ReturnUrl server-side (open-redirect risk). |
TechButton |
Variant (ButtonVariant), Size, Class, Type, Busy, BusyText, ChildContent, splatted attrs |
ButtonVariant enum: Primary, Secondary, Danger, Ghost. Busy disables + shows a decorative spinner and optional BusyText; exposes aria-busy. Caller owns the outcome region. |
TechCard |
Title, Header, ChildContent, Footer, Class |
Panel with optional head/body/footer slots. |
TechField |
Label*, For, Hint, HintId, Error, ErrorId, ChildContent |
Label/hint/error association wrapper. Caller owns input id, aria-describedby and aria-invalid. |
* EditorRequired parameter.
Deliberately NOT included (YAGNI / stays per-project): domain grids/tree data, multi-select dropdowns, modals, toasts, audit components and page-specific layouts. The existing stateless TreeTable renders caller-owned rows; it does not own data loading/filtering. Shared interaction recipes apply without a speculative modal API.
5. Delivery
The RCL ships as the single NuGet package ZB.MOM.WW.Theme (.NET 10). Published version is 0.5.3; the 1.0.0 candidate waits for package and browser acceptance.
Static assets are served at _content/ZB.MOM.WW.Theme/… by ASP.NET's static-web-asset
pipeline:
| Asset path | Contents |
|---|---|
_content/ZB.MOM.WW.Theme/css/theme.css |
Design tokens, typography, utility helpers |
_content/ZB.MOM.WW.Theme/css/layout.css |
Side-rail layout, collapsible nav, StatusPill variants, card/field helpers |
_content/ZB.MOM.WW.Theme/fonts/ibm-plex-sans-400.woff2 |
IBM Plex Sans Regular |
_content/ZB.MOM.WW.Theme/fonts/ibm-plex-sans-600.woff2 |
IBM Plex Sans SemiBold |
_content/ZB.MOM.WW.Theme/fonts/ibm-plex-mono-500.woff2 |
IBM Plex Mono Medium |
Bootstrap 5 is not vendored by the kit — each app keeps its own Bootstrap <link>.
Adoption entry points:
- Add
<PackageReference Include="ZB.MOM.WW.Theme">in the app. - In
App.razor<head>, after Bootstrap:<ThemeHead />. - Replace
MainLayoutwith the thin-delegation pattern (§3/§4). - Add
@using ZB.MOM.WW.Themeto_Imports.razor.
6. Shared vs per-project
Shared (extracted into the RCL):
| What | Where in RCL |
|---|---|
Design tokens (--paper, --ink, --accent, --ok, …) |
wwwroot/css/theme.css |
IBM Plex fonts (three .woff2) |
wwwroot/fonts/ |
| Side-rail shell layout CSS | wwwroot/css/layout.css |
Side-rail shell components (ThemeShell, BrandBar, nav components) |
Components/ |
Status chip (StatusPill, StatusState) |
Components/ |
Login card (LoginCard) |
Components/ |
Common controls (TechButton, TechCard, TechField) |
Components/ |
Per-project (NOT extracted):
| What | Rationale |
|---|---|
site.css page layout residual |
App-specific page structure varies (body padding, two-column layouts, etc.) |
| Page / route components | Domain content — not a UI kit concern |
Scoped .razor.css files |
Component-specific overrides stay with the component they scope |
| Authorization / session UI | Depends on per-project auth model (ZB.MOM.WW.Auth) |
| Interactive nav-state persistence | Bespoke (OtOpcUa uses a cookie; ScadaBridge / MxGateway use JS state) |
7. Acceptance
A project is considered adopted when all of the following hold:
ZB.MOM.WW.ThemeNuGet package referenced;ZB.MOM.WW.Themein_Imports.razor.<ThemeHead />inApp.razor<head>(after Bootstrap); per-apptheme.csscopy and IBM Plex.woff2files deleted fromwwwroot/.MainLayoutreplaced with the thin-delegation pattern wrapping<ThemeShell>.- Nav rebuilt with
NavRailItem/NavRailSection. - Local
StatusBadge/StatusChipcomponent deleted; replaced by<StatusPill>. - Login form replaced with
<LoginCard>(static form POST preserved;<AntiforgeryToken/>insideChildContent;ReturnUrlvalidated server-side). - Per-app
site.csspage-layout residual kept; scoped.razor.cssfiles kept unchanged.