feat(theme): implement accessible Technical-Light 1.0 contracts

This commit is contained in:
Joseph Doherty
2026-11-13 15:49:08 -05:00
parent 8969bee6a9
commit f8469aa837
63 changed files with 3695 additions and 120 deletions
+36 -39
View File
@@ -1,45 +1,42 @@
# UI Theme (layout / tokens / components)
# Shared Technical-Light UI theme
Second normalized component. **Goal: path to shared code** — converge the three sister
projects onto a common "Technical-Light" design system, realized as the `ZB.MOM.WW.Theme`
Razor Class Library.
`ZB.MOM.WW.Theme` is the implemented .NET 10 Razor Class Library for the SCADA
family. It owns canonical tokens, IBM Plex fonts, shell, common controls, shared CSS
and optional nav-state persistence. Applications retain domain pages and behavior.
- The one target: [`spec/SPEC.md`](spec/SPEC.md)
- Design tokens reference: [`spec/DESIGN-TOKENS.md`](spec/DESIGN-TOKENS.md)
- The shared library: [`shared-contract/ZB.MOM.WW.Theme.md`](shared-contract/ZB.MOM.WW.Theme.md)
- Divergences + backlog: [`GAPS.md`](GAPS.md)
- Current state, per project: [`current-state/`](current-state/)
Current published release: **0.5.3**. Accessible coordinated candidate: **1.0.0**, not
published yet. [Release decision](RELEASE-DECISION.md) records version policy, actual
consumer pins and accent families. [GB acceptance](validation/bunit-2.7.2/ACCEPTANCE.md)
records all seven bUnit migrations. Historical current-state reports describe their
original snapshots; they are not current rollout records.
## Why UI theme is a strong candidate
- [Specification](spec/SPEC.md)
- [Canonical tokens](spec/DESIGN-TOKENS.md)
- [Interaction recipes](spec/INTERACTION-RECIPES.md)
- [Component contract](shared-contract/ZB.MOM.WW.Theme.md)
- [Library usage](../../ZB.MOM.WW.Theme/README.md)
- [Execution ledger](../../docs/plans/2026-11-12-scada-ui-consistency/EXECUTION.md)
- [Historical adoption notes](GAPS.md)
All three sister apps share a Blazor SSR + Bootstrap 5 UI stack and each ships a
hand-copied **379-line `theme.css`** (the "Technical-Light" design system: IBM Plex
`@font-face`, `:root` design tokens, status palette, typography helpers). **The three
copies are byte-for-byte identical except for three lines** — the `@font-face` `src:`
URL prefix differs per app deployment convention. IBM Plex `.woff2` fonts are likewise
vendored three times into each app's `wwwroot/fonts/`. This is the textbook drift
situation: a shared design system already beginning to diverge, with a latent font-path
bug in one app (OtOpcUa) that goes unnoticed because browsers fall back to system fonts.
| Consumer | Baseline Theme | Accessible adoption |
|---|---|---|
| ScadaBridge Host/CentralUI | 0.5.3 | Pending exact candidate canary/release |
| OtOpcUa AdminUI | 0.5.0 | Pending G1 |
| MxAccessGateway Server | 0.5.0 | Pending G1 |
| HistorianGateway Server | 0.5.0 | Pending G1 |
| BTDB Manager | 0.4.1 | Pending G1 |
| Overview | 0.5.0 | Pending exact candidate canary/release |
| ignitionoee router | 0.5.0 | Pending G1 |
| ignitionoee registry/Perspective | Native/public-feed graph | Package-derived export/native mapping pending |
## Status by project
Keep one CSS/font authority per application. Use ThemeHead after host Bootstrap and
ThemeScripts once near the end of the body. Preserve compact sizing, rail behavior
and current brand accents; use semantic inks for readable state text. Complete accent
families, labeled field IDs and persistent operation outcomes are documented in the
contracts. Status/info meaning is shared across products. Explicit supported dark
schemes require their own readable aliases and verification.
| Project | Surface | Layout today | Adoption status |
|---|---|---|---|
| **OtOpcUa** | `ZB.MOM.WW.OtOpcUa.AdminUI` | Side rail (`NavSidebar.razor`) + `theme.css` + IBM Plex | Not started |
| **MxAccessGateway** | `ZB.MOM.WW.MxGateway.Server` Dashboard | Sidebar (`nav.sidebar`) + `theme.css` + IBM Plex | Not started |
| **ScadaBridge** | `ZB.MOM.WW.ScadaBridge.Host` + `.CentralUI` (RCL) | Own `MainLayout` + `NavMenu` (`nav.sidebar`) + `theme.css` + IBM Plex | Not started |
See each project's [`current-state/<project>/CURRENT-STATE.md`](current-state/) for the
code-verified detail and its adoption plan.
## Normalized vs. left per-project
**Normalized (extracted into the RCL `ZB.MOM.WW.Theme`):** design tokens + IBM Plex
fonts, the canonical side-rail shell (`ThemeShell` + `BrandBar` + `NavRailItem` +
`NavRailSection`), and the four widgets (`StatusPill`, `LoginCard`, `TechButton`,
`TechCard`, `TechField`). One RCL, one package, one version.
**Left 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.
The 1.0.0 static exporter takes exact validated package bytes and produces CSS/fonts,
raw tokens and provenance hashes for hosts that cannot use a private RCL package.
No registry private-feed dependency is introduced. Domain editors, authentication,
authorization, data loading and protocols remain host responsibilities.