docs: add UI-theme component design
Brainstormed design for normalizing UI theming across the 3 sister apps into a single .NET 10 RCL (ZB.MOM.WW.Theme): canonical side-rail shell + Technical-Light tokens/fonts as static assets + StatusPill/LoginCard/ TechButton-Card-Field, with per-app name/accent/logo. Mirrors the auth component's path-to-shared-code treatment; app adoption tracked as follow-on.
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,203 @@
|
||||
# UI Theme Component — Design
|
||||
|
||||
**Date:** 2026-06-01
|
||||
**Status:** Approved (brainstorming) → ready for writing-plans
|
||||
**Goal:** Normalize UI theming across the three sister apps and realize it as a single
|
||||
shared .NET 10 Razor Class Library, `ZB.MOM.WW.Theme` — mirroring the auth component's
|
||||
"path to shared code" treatment.
|
||||
|
||||
---
|
||||
|
||||
## 1. Motivation (code-verified, 2026-06-01)
|
||||
|
||||
All three sister apps have Blazor SSR + Bootstrap 5 UIs (four surfaces total):
|
||||
|
||||
| App | UI surface(s) | Nav layout today |
|
||||
|---|---|---|
|
||||
| OtOpcUa | `ZB.MOM.WW.OtOpcUa.AdminUI` | **side rail** (`NavSidebar.razor`) |
|
||||
| MxAccessGateway | `ZB.MOM.WW.MxGateway.Server` Dashboard | **top nav bar** |
|
||||
| ScadaBridge | `ZB.MOM.WW.ScadaBridge.Host` + `.CentralUI` (RCL) | own `MainLayout` + `NavMenu` |
|
||||
|
||||
Each ships a hand-copied **`theme.css`** — the "Technical-Light" design system
|
||||
(379 lines: IBM Plex `@font-face`, design tokens `:root { --paper, --card, --ink,
|
||||
--ink-soft, --rule, --accent, --ok, --warn, --bad, --idle }`, status palette,
|
||||
typography). **The three copies are byte-for-byte identical except for three lines** —
|
||||
the font `src:` URL prefix (`fonts/` vs `/fonts/` vs `../fonts/`), a per-app deployment
|
||||
path, not a design difference. IBM Plex `.woff2` fonts are vendored separately into each
|
||||
app's `wwwroot/fonts/`.
|
||||
|
||||
This is the textbook drift situation: a shared design system maintained as three
|
||||
copy-pasted files that have *already* begun to diverge. The split between shared and
|
||||
per-project is unusually clean — see §6.
|
||||
|
||||
Verified paths:
|
||||
- `OtOpcUa/src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/wwwroot/css/theme.css` (+ `site.css`, `fonts/`)
|
||||
- `MxAccessGateway/src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/theme.css` (+ `site.css`, `fonts/`)
|
||||
- `ScadaBridge/src/ZB.MOM.WW.ScadaBridge.CentralUI/wwwroot/css/theme.css` (+ `site.css`, `fonts/`)
|
||||
|
||||
## 2. Decisions (from brainstorming)
|
||||
|
||||
| Decision | Choice |
|
||||
|---|---|
|
||||
| Depth/goal | **Full shared UI kit** — beyond tokens: extract layout shell + components into the RCL |
|
||||
| Layout model | **One canonical layout** — a single side-rail shell; top-bar / menu apps migrate onto it |
|
||||
| Branding | **Name + accent + logo per app** — uniform chassis, per-app identity via parameters |
|
||||
| Kit contents | Canonical shell + tokens + fonts **and** Status indicators **and** Login card **and** Common form controls |
|
||||
| Packaging | **Single RCL `ZB.MOM.WW.Theme`** (Approach A) — one package, one version |
|
||||
|
||||
Packaging alternatives considered and rejected: (B) split CSS/fonts vs components — YAGNI,
|
||||
no tokens-only consumer exists, and splitting later is non-breaking; (C) plain content
|
||||
package, no components — contradicts the "full kit" decision.
|
||||
|
||||
## 3. Architecture
|
||||
|
||||
Two deliverables, same shape as the auth component:
|
||||
|
||||
1. **`components/ui-theme/`** — the normalization docs (spec / design-tokens /
|
||||
shared-contract / per-project current-state / GAPS).
|
||||
2. **`ZB.MOM.WW.Theme/`** — the built RCL, living at `scadaproj/ZB.MOM.WW.Theme/` (its own
|
||||
folder in this repo, exactly like `ZB.MOM.WW.Auth/`).
|
||||
|
||||
**The RCL ships:**
|
||||
- **Static web assets** — the canonical `theme.css` + the IBM Plex `.woff2` files, served at
|
||||
`_content/ZB.MOM.WW.Theme/css/theme.css` and `_content/ZB.MOM.WW.Theme/fonts/…`. This alone
|
||||
kills the copy-paste drift, and fixes the font-path divergence for free: the RCL's
|
||||
static-asset base path makes the `src: url(../fonts/…)` reference canonical and identical
|
||||
for every consumer.
|
||||
- **Razor components** — the canonical side-rail shell + the chosen widgets (§4).
|
||||
|
||||
**Accent/branding mechanism:** `ThemeLayout` renders its root as
|
||||
`<div class="app-shell" style="--accent: @Accent">`, so a per-app accent overrides the
|
||||
`--accent` custom property for that subtree. Product name and logo are parameters.
|
||||
Everything else in Technical-Light stays shared and un-overridable.
|
||||
|
||||
**Adoption is follow-on, per repo** (like auth's GAPS #8). Building the RCL is self-contained
|
||||
in `scadaproj`; apps referencing it, deleting their `theme.css`/fonts/`MainLayout`/login card,
|
||||
and migrating top-bar → rail (MxGateway) is tracked in `GAPS.md`, not done in this repo.
|
||||
|
||||
## 4. Component contract (RCL public API)
|
||||
|
||||
Namespace `ZB.MOM.WW.Theme`. Components are themed purely via CSS custom properties — no
|
||||
hardcoded colors in markup.
|
||||
|
||||
**Static-asset entry point**
|
||||
- `<ThemeHead />` — dropped in `<head>` (App.razor); emits the `<link>` to
|
||||
`_content/ZB.MOM.WW.Theme/css/theme.css`. One line replaces each app's hand-rolled wiring.
|
||||
|
||||
**Layout shell (canonical chassis)**
|
||||
- `ThemeLayout : LayoutComponentBase` — the one side-rail shell.
|
||||
Params: `string Product`, `string? Accent` (overrides `--accent`), `RenderFragment? Logo`,
|
||||
`RenderFragment Nav` (rail nav items), `RenderFragment? RailFooter` (e.g. user/sign-out),
|
||||
`RenderFragment ChildContent` (page body). Renders `BrandBar` in the rail header + the
|
||||
`Nav` slot + a `<main>` body region.
|
||||
- `BrandBar` — logo + product name; standalone, used internally by `ThemeLayout`.
|
||||
- `NavRailItem` — one rail link: `string Href`, `string Text`, `RenderFragment? Icon`,
|
||||
`NavLinkMatch Match`. Active state via Blazor `NavLink`. Apps fill the `Nav` slot with these.
|
||||
|
||||
**Status (highest-value shared widget)**
|
||||
- `StatusPill` — `StatusState State` (`Ok | Warn | Bad | Idle | Info`) + `ChildContent`
|
||||
label. Maps state → the `--ok / --warn / --bad / --idle` tokens. `enum StatusState` public.
|
||||
|
||||
**Auth surface**
|
||||
- `LoginCard` — centered branded card: `string Product`, `RenderFragment? Logo`,
|
||||
`EventCallback<LoginSubmit> OnSubmit`, `string? Error`, `bool Busy`. UI-only — raises
|
||||
`OnSubmit`; **no auth logic** (the app wires it to `ZB.MOM.WW.Auth`).
|
||||
`readonly record struct LoginSubmit(string Username, string Password)`.
|
||||
|
||||
**Common controls (thin themed wrappers over Bootstrap 5)**
|
||||
- `TechButton` — `ButtonVariant Variant` (`Primary | Secondary | Danger | Ghost`),
|
||||
`bool Busy`, `ChildContent`; passes through `type`/`onclick`.
|
||||
- `TechCard` — `string? Title`, `RenderFragment? Header`, `ChildContent`, `RenderFragment? Footer`.
|
||||
- `TechField` — labeled input wrapper: `string Label`, `string? Hint`, `string? Error`,
|
||||
`ChildContent` (the `<input>`/`<select>`).
|
||||
|
||||
**Deliberately NOT included** (YAGNI / stays per-project): data grids, tree views, dropdowns,
|
||||
modals, toasts, page-specific layouts. The kit owns chrome + tokens + the four widgets above —
|
||||
not a general component library.
|
||||
|
||||
**Project shape:** `Microsoft.NET.Sdk.Razor`, `net10.0`, `FrameworkReference
|
||||
Microsoft.AspNetCore.App`; `wwwroot/css/theme.css` + `wwwroot/fonts/*.woff2` as static assets.
|
||||
Tests via **bUnit**; central package management, matching `ZB.MOM.WW.Auth`.
|
||||
|
||||
## 5. Normalization folder layout
|
||||
|
||||
```
|
||||
components/ui-theme/
|
||||
README.md # overview + per-project status table
|
||||
spec/
|
||||
SPEC.md # the ONE normalized target for UI theming
|
||||
DESIGN-TOKENS.md # canonical token reference (analogous to auth CANONICAL-ROLES.md)
|
||||
shared-contract/
|
||||
ZB.MOM.WW.Theme.md # the RCL public API (§4), packaging, consumer matrix
|
||||
current-state/
|
||||
otopcua/CURRENT-STATE.md # code-verified theming today + adoption plan
|
||||
mxaccessgw/CURRENT-STATE.md
|
||||
scadabridge/CURRENT-STATE.md
|
||||
GAPS.md # divergences vs SPEC + adoption backlog
|
||||
```
|
||||
|
||||
**`spec/SPEC.md` sections:** §1 design tokens (Technical-Light palette + type scale; `--accent`
|
||||
is the one per-app override) · §2 typography (IBM Plex Sans 400/600 + Mono 500, vendored woff2,
|
||||
canonical relative font path) · §3 canonical side-rail layout · §4 component contract (the §4
|
||||
surface) · §5 delivery (RCL static assets, `<ThemeHead/>`) · §6 shared vs per-project (see below)
|
||||
· §7 acceptance (what "adopted" means per app).
|
||||
|
||||
**`spec/DESIGN-TOKENS.md`:** enumerates every token (name, value, role) as the lookup reference,
|
||||
the way `CANONICAL-ROLES.md` enumerates roles. The canonical 379-line `theme.css` is the source;
|
||||
this doc is its human-readable index.
|
||||
|
||||
**`shared-contract/ZB.MOM.WW.Theme.md`:** the package API from §4 + the consumer matrix — all
|
||||
three apps consume the single RCL (OtOpcUa `AdminUI`, MxGateway `Server` Dashboard, ScadaBridge
|
||||
`Host` + `CentralUI`); no optional packages, unlike auth.
|
||||
|
||||
**Register** the component in `components/README.md` (new row: *UI Theme — layout / tokens /
|
||||
components → `ZB.MOM.WW.Theme` RCL*) and add it to the root `CLAUDE.md` / `README.md` component
|
||||
tables.
|
||||
|
||||
## 6. Shared vs per-project
|
||||
|
||||
**Shared (extracted into the RCL):** design tokens, IBM Plex fonts, the canonical side-rail
|
||||
shell, and the four widgets (`StatusPill`, `LoginCard`, `TechButton/Card/Field`).
|
||||
|
||||
**Per-project (NOT extracted):** each app's `site.css` residual page layout, its page/route
|
||||
content, and app-specific scoped `.razor.css` (e.g. ScadaBridge's `MultiSelectDropdown`,
|
||||
`TreeView`, `Audit/*`). The kit owns the *chrome and tokens*, not the app's domain screens.
|
||||
|
||||
## 7. Current-state + adoption (per project)
|
||||
|
||||
| Project | Surface(s) | Today | Adoption = delete / change / keep |
|
||||
|---|---|---|---|
|
||||
| **OtOpcUa** | `AdminUI` (side rail) | `theme.css` + IBM Plex fonts; `MainLayout` + `NavSidebar`; login card in `site.css` | **Lowest effort** — already a rail. Delete `theme.css`/fonts, render in `ThemeLayout`, swap login card for `LoginCard`. Keep `site.css` page bits. |
|
||||
| **MxAccessGateway** | `Server` Dashboard (**top bar**) | identical `theme.css`/fonts; top-nav `MainLayout` | **Highest effort/risk** — top-bar → side-rail migration (the "one canonical layout" cost lands here). |
|
||||
| **ScadaBridge** | `Host` + `CentralUI` (own menu) | identical `theme.css`/fonts; `MainLayout` + `NavMenu`; scoped `.razor.css` | Migrate shell to `ThemeLayout`; keep scoped component CSS — stays per-project. |
|
||||
|
||||
**`GAPS.md`** — divergences + prioritized adoption backlog:
|
||||
- *Divergences:* tokens identical today but copy-pasted (drift started on font paths); layouts
|
||||
differ (rail / top-bar / menu); fonts vendored 3×.
|
||||
- *Backlog (priority · effort · risk):* (1) build the RCL [scadaproj]; (2) adopt in OtOpcUa
|
||||
[low risk]; (3) adopt in ScadaBridge [med]; (4) **migrate MxGateway top-bar → rail [high risk
|
||||
— UX change, flagged explicitly]**. Same "adoption is per-repo follow-on" framing as auth's
|
||||
GAPS #8.
|
||||
|
||||
## 8. Testing
|
||||
|
||||
In the RCL, via **bUnit**:
|
||||
- `StatusPill` maps each `StatusState` → the right token class.
|
||||
- `ThemeLayout` emits the `--accent` override when `Accent` set; renders `Product`, `Logo`,
|
||||
`Nav`, and body slots.
|
||||
- `LoginCard` invokes `OnSubmit` with the entered `LoginSubmit`; honors `Busy`/`Error`.
|
||||
- `TechButton` / `TechCard` / `TechField` render variants/slots correctly.
|
||||
- A **packaging test** asserting `theme.css` + the woff2 files ship as
|
||||
`_content/ZB.MOM.WW.Theme/...` static assets (the anti-drift guarantee).
|
||||
- No visual/snapshot regression tests — YAGNI for this pass.
|
||||
|
||||
**Build/test/pack** (from `ZB.MOM.WW.Theme/`): `dotnet build -c Release` · `dotnet test` ·
|
||||
`dotnet pack -c Release -o ./artifacts` → 1 nupkg.
|
||||
|
||||
## 9. Out of scope (this pass)
|
||||
|
||||
- App-side adoption (referencing the RCL, deleting copies, the MxGateway layout migration) —
|
||||
tracked in `GAPS.md` as follow-on, per repo.
|
||||
- A general component library beyond the four widgets.
|
||||
- Dark mode / theme switching (Technical-Light is the only theme today).
|
||||
- Visual regression testing.
|
||||
Reference in New Issue
Block a user