Files
scadaproj/components/ui-theme/spec/SPEC.md
T

11 KiB

UI Theme — normalized target spec

Status: Implemented shared system; 1.0.0 published and G1 accepted. Published 1.0.0 passed G1; broader consumer rollout and G2/G3 remain tracked separately. 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 -ink text and -bg surfaces; 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 1.0.0 with independently verified 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:

  1. Add <PackageReference Include="ZB.MOM.WW.Theme"> in the app.
  2. In App.razor <head>, after Bootstrap: <ThemeHead />.
  3. Replace MainLayout with the thin-delegation pattern (§3/§4).
  4. Add @using ZB.MOM.WW.Theme to _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:

  1. ZB.MOM.WW.Theme NuGet package referenced; ZB.MOM.WW.Theme in _Imports.razor.
  2. <ThemeHead /> in App.razor <head> (after Bootstrap); per-app theme.css copy and IBM Plex .woff2 files deleted from wwwroot/.
  3. MainLayout replaced with the thin-delegation pattern wrapping <ThemeShell>.
  4. Nav rebuilt with NavRailItem / NavRailSection.
  5. Local StatusBadge / StatusChip component deleted; replaced by <StatusPill>.
  6. Login form replaced with <LoginCard> (static form POST preserved; <AntiforgeryToken/> inside ChildContent; ReturnUrl validated server-side).
  7. Per-app site.css page-layout residual kept; scoped .razor.css files kept unchanged.