diff --git a/docs/plans/2026-06-01-ui-theme-component-design.md b/docs/plans/2026-06-01-ui-theme-component-design.md
new file mode 100644
index 0000000..52adbf2
--- /dev/null
+++ b/docs/plans/2026-06-01-ui-theme-component-design.md
@@ -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.