Files
scadaproj/docs/plans/2026-11-12-scada-ui-consistency.md
T
2026-11-14 02:36:01 -05:00

188 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# SCADA Family UI Consistency Implementation Plan
**Execution complete — November 14, 2026:** all 100 tasks accepted. See the [final G3 acceptance](../../components/ui-theme/validation/cross-project-final/G3.md) and [execution record](2026-11-12-scada-ui-consistency/EXECUTION.md). The plan below preserves its original implementation instructions. VoiceOver is excluded by user instruction; no application deployment is implied.
> **For Codex:** REQUIRED SUB-SKILL: Use `executeplan` to implement this plan task-by-task.
**Goal:** Implement the Impeccable recommendations through one improved Technical-Light theme, shared Secrets UI fixes, and coordinated migrations of every sister web UI.
**Architecture:** First establish one verified bUnit 2.7.2 test baseline across every existing bUnit consumer. The Theme Razor Class Library owns visual foundations and generic interaction contracts; applications retain routes, authorization, data ownership and domain-specific editors. Publish and pilot the shared changes before migrating consumers, using one token/field/focus contract and deliberate product accents. Registry/Perspective receive platform-compatible token/style integration rather than a forced Blazor shell.
**Tech Stack:** .NET 10/Blazor SSR and InteractiveServer, Bootstrap 5, CSS tokens and IBM Plex, bUnit 2.7.2 with existing xUnit v2/v3 runners, HtmlRenderer/browser harnesses, native Ignition Perspective views/styles.
---
**Execution resolution (November 13, 2026): GB and G1 passed. `THEME_VERSION` is
**1.0.0**, published with an independently verified canonical static export. Exact source,
checksums, delivery URLs and bounded pilot acceptance are recorded in
[the 1.0.0 release](../../components/ui-theme/releases/1.0.0.md). `SECRETS_UI_VERSION`
remains unresolved until its separate release gate. Baseline pins below describe the
pre-adoption inventory; current execution progress lives in the task ledger.
## How to use this plan
This plan contains **100 tasks across ten chapters**, mapping all **81 review findings**. This is a planning deliverable, not an implementation, package publication or deployment. Start with Phase 0, standardize all existing bUnit users on 2.7.2 and close GB, then execute the shared Theme chapter and project sequence below. Each chapter includes task IDs, exact target files, test-first behavior changes, expected test results, visual checks, commits, finding traceability and rollback. Commands in those chapters are instructions for the future implementation; they were not run during planning.
- Requirements: [shared design recommendations](../../impeccable/SHARED-DESIGN-SYSTEM.md).
- Evidence and project reports: [review guide](../../impeccable/README.md).
- Visual reference: [13 mockups](../../impeccable/index.html). They illustrate hierarchy with synthetic data; do not port sample counts, names, environment labels or nonfunctional production actions into products.
- Mandatory first phase: [bUnit 2.7.2 standardization](2026-11-12-scada-ui-consistency/BUnit.md) and [seven-project inventory](2026-11-12-scada-ui-consistency/bunit-inventory.json).
- Plan chapters: [folder](2026-11-12-scada-ui-consistency/).
- Revisions: [source baselines](2026-11-12-scada-ui-consistency/source-baselines.json).
- Execution checklist: [task ledger](2026-11-12-scada-ui-consistency/tasks.json). All tasks initially remain planned, not verified.
The existing scadaproj checkout is suitable for this documentation-only work. At implementation time use a suitable checkout/branch per repository and keep unrelated work intact. Do not create sibling source references across repositories or commit one repository's changes from another working directory.
## Fixed design decisions
1. Keep Technical-Light: Plex Sans, Plex Mono for data/code, paper `#f4f4f1`, white working surfaces, fine neutral borders, existing 8px panels, compact rail, consistent controls and status treatment. The plan refines the established identity.
2. Theme is the single authority for shared CSS and components. Do not copy `impeccable/mockups/shared.css` into each application or import mockup-only classes wholesale.
3. Retain source-verified product accents: default blue, Historian green, BTDB teal and Overview purple. Add complete deep/tint/border/focus variants through a shared API; semantic warning/fault/unknown meaning remains uniform.
4. Keep domain distinctions: active ≠ leader; stale ≠ unreachable; accepted deployment ≠ applied configuration; warm pool depth ≠ connections in use; driver eligibility ≠ commissioned/live health; historical write ≠ read query; tombstoned secret ≠ value reveal.
5. Preserve SSR login POST, antiforgery/return-URL validation, current policies, auditing, protocol contracts, lazy loading, precision and cancellation behavior. A visual task must not quietly change these contracts.
6. Make inputs genuinely labeled and errors associated. Name repeated actions with row identity. Keep every task reachable with keyboard and visible focus; dialogs must manage actual focus/inertness, not just ARIA markup.
7. Standardize explicit UTC input semantics where a field says UTC. A `datetime-local` control has no zone; do not call server-local `ToUniversalTime()` and relabel the result. Preserve BTDB's full persisted precision and actual domain parser rules. If local display is kept, label the real zone separately.
8. Keep status text readable, including stale/disabled/help/error states. Fix opacity-based dimming locally after shared inks land. Aim for 44px touch actions while preserving efficient desktop density; assess the separate 24px minimum target/spacing rule accurately.
9. A shared dark-mode expansion is a separate scoped release. Preserve ScadaBridge's existing supported dark mode and provide accessible semantic aliases there; do not remove it or promise all apps support dark mode merely because tokens exist.
10. A native operator layout is appropriate for Perspective. Export the same semantic palette/type/spacing contract into native style resources; do not install a Blazor package in Ignition.
11. Standardize all existing bUnit users on exactly 2.7.2 first, including Theme and ScadaBridge validation plus OtOpcUa preview replacement. Preserve xUnit v2/v3 and non-bUnit harnesses; verify the real parser/Css/Diffing/runtime graph before accepting GB.
## Phase 0: Baseline, branch ownership and release decisions
**Owner:** coordinating engineer plus repository maintainers. **Dependency:** none. **Deliverable:** baseline evidence and one chosen shared contract.
1. Read applicable `AGENTS.md`/repository instructions and the matching report/chapter before editing. Capture `git status --short`, `git rev-parse HEAD`, package pins and existing uncommitted changes per target repo.
2. Compare the actual current source to the [review revision inventory](../../impeccable/evidence/source-inventory.json); do not apply a stale finding to code already fixed. At planning, ScadaBridge moved from `482ac665` to `7e34d7c2` only in Docker image-version stamping; scadaproj moved from `e6a724b` to `d93ca7b` in telemetry/observability. Theme/Secrets/Overview UI source and reviewed ScadaBridge UI source were unchanged by those diffs.
3. Record current unit/component test baselines using the explicit project commands in each chapter. Diagnose infrastructure failures separately; record pre-upgrade test discovery/results before the GB migration. Change bUnit and its necessary test-only compatibility dependencies in that dedicated phase, never disable package audits or perform unrelated dependency upgrades to make UI work pass.
4. Resolve supported browser engines/devices, current color schemes, actual role fixtures and deployment environment overlays. Use synthetic accounts/data for tests; no real secret values in fixtures or screenshots.
5. Assign one owner per repository branch and one owner for Theme. Separate agents may work on separate repositories after shared contracts are agreed. Within scadaproj, Theme/Secrets/Overview package files and shared docs need a single integrator to avoid version conflicts.
6. Resolve the shared release version under the existing token compatibility policy; document the decision. `THEME_VERSION` and `SECRETS_UI_VERSION` in chapters are symbols, not executable package versions. Substitute real versions only after compatibility review/pack validation.
**G0:** inventory/pre-upgrade baseline recorded, active findings reconciled and contracts assigned. G0 permits the dedicated bUnit migration, not Theme/UI implementation. No live environment change is required to complete planning.
## Phase 1: Standardize bUnit before shared-theme work
Execute [BU-01–BU-10](2026-11-12-scada-ui-consistency/BUnit.md). Seven test projects must resolve exact stable **2.7.2** and pass their migrated render/auth/event/async lifecycle suites with an explicitly validated AngleSharp family. Preserve existing runner generations, policy/JSInterop fixtures and test coverage; inspect real restored assets rather than only central version declarations. No bUnit is added to HtmlRenderer/Playwright/native-only projects.
**GB:** every bUnit project, including existing 2.7.2 consumers, is verified; parser compatibility/advisory disposition, test discovery/results and runtime smoke evidence are recorded. Conflicting repository parser comments are unresolved until actual runtime tests prove the graph. A missing required fixture or unacceptable binary/dependency combination leaves GB incomplete. All Theme/UI tasks and candidate pilots depend on GB; even the independent Secrets target-isolation fix waits for it under this updated ordering.
## Dependency order and checkpoints
| Order | Chapter / scope | Depends on | Exit checkpoint |
|---|---|---|---|
| 0 | [bUnit standardization](2026-11-12-scada-ui-consistency/BUnit.md): seven projects, dependency/API migration and runtime verification | G0 | GB: exact 2.7.2 everywhere, accepted graph and passing migrated suites |
| 1 | [Theme](2026-11-12-scada-ui-consistency/Theme.md): semantic inks, field/ARIA API, accent states, busy/focus/motion, interaction recipes | GB | G1: tested, versioned, packaged and piloted Theme plus canonical static export; exact artifacts/version recorded |
| 2 | [Secrets](2026-11-12-scada-ui-consistency/Secrets.md): draft isolation, field associations, modal lifecycle, recovery | GB for target-isolation fix; G1 for visual/field migration | Shared UI package + two-host validation; exact `SECRETS_UI_VERSION` recorded |
| 3 | [Overview](2026-11-12-scada-ui-consistency/Overview.md): first small consumer and read-only visual canary | G1 candidate for local canary; final G1 for released adoption | Readable freshness/check state, truthful rollups, pause/recovery |
| 4 | [ScadaBridge](2026-11-12-scada-ui-consistency/ScadaBridge.md): large interactive pilot | G1 candidate for local canary; final G1/Secrets for released adoption | Modal/drawer access, explicit UTC, truthful count states; light/dark verified |
| 5 | [OtOpcUa](2026-11-12-scada-ui-consistency/OtOpcUa.md) | G1, shared Secrets release where referenced | Labeled forms/trees/dialogs; honest deployment/event states; current route/nav coverage |
| 6 | [MxAccessGateway](2026-11-12-scada-ui-consistency/MxAccessGateway.md) | G1, shared Secrets release where referenced | Keyboard/touch subscription path, managed dialogs, actionable session diagnostics |
| 7 | [HistorianGateway](2026-11-12-scada-ui-consistency/HistorianGateway.md) | G1, shared Secrets release where referenced | Labeled history console; fresh/stale context; reviewed historical write intent |
| 8 | [BTDB](2026-11-12-scada-ui-consistency/BTDB.md) | G1 | Protected drafts, readable teal UI, form/table/tab/JSON-editor recovery |
| 9 | [ignitionoee](2026-11-12-scada-ui-consistency/ignitionoee.md): router, registry, Perspective | G1; platform-compatible export contract | Keyboard job details, unified modal behavior, token parity with native operator views |
| 10 | Cross-family verification and release record | All chapter exits | G3: implemented route/state coverage, no untracked design drift; rollout evidence retained |
**All rows after order 0 require GB. Avoid a gate cycle:** TH-07 uses local package candidates in temporary Overview/ScadaBridge pilot branches, and TH-08 uses the same canonical static export in a limited registry candidate-import pilot. Those candidate checks do not require the full consumer chapters or a previously released G1. G1 closes after candidate tests and representative pilot surfaces pass; consumer chapters then adopt the released immutable package. A local pilot restore/import does not mean the app is deployed. Reviewed version/source must be committed before the final package build; export provenance records that clean build commit, not a later evidence-only commit.
**G2: interaction convergence** occurs after two representative dialog/filter/table implementations meet the shared recipes. Compare ScadaBridge's managed dialog and ignitionoee registry's native dialog before extracting generic behavior. Extract only stable common behavior in a later Theme release; domain editors and state logic remain local. G2 does not block independent repairs or G1's recipe publication.
**Final interaction decision:** G2 interaction comparison is accepted in [G2 evidence](../../components/ui-theme/validation/interaction-pilots/G2.md): ScadaBridge managed overlays and registry native dialogs retain distinct tested lifecycle ownership, with MX/OEE router native pilots providing additional busy/disposal proof. Retain local adapters and the shared recipe; any later extraction requires a separate two-host tested release. G3 is accepted for the implementation candidate; see the final acceptance linked above.
After G1/required shared UI releases, orders 5–9 can run in parallel with separate repo ownership. The table is a safe serial execution order if only one engineer is available. Do not release each application after a different unresolved token/API contract.
## Shared APIs and migration rules
The complete implementations are in the Theme chapter; the following choices are mandatory inputs to every consumer task.
| Area | Consumer obligation |
|---|---|
| Semantic ink | Use `--ok-ink`, `--warn-ink`, `--bad-ink`, `--idle-ink`; use the new readable `--ink-faint`. Existing `--ok/--warn/--bad/--idle` remain signal colors |
| Field | `TechField For`, `HintId`, `ErrorId` plus explicit control `id`, `aria-describedby`, `aria-invalid`; repeated forms need unique stable IDs |
| Accent | Pass existing `Accent` plus `AccentDeep`, `AccentTint`, `AccentBorder`, `AccentFocus` as a coherent product family. Informational blue uses separate `--info-ink` |
| Busy | Optional `BusyText`, `aria-busy`, existing caller-disabled semantics; caller announces outcome once in a persistent region, never plaintext secrets |
| Table | Labeled filters, caption/header semantics, actual button for sort/disclosure, `aria-sort`/`aria-expanded`, internal horizontal scrolling |
| Overlay | Named dialog, safe initial focus, inert background, actual DOM keydown event, visible enabled focusables only, Escape/cancel policy, return focus |
| Time | Labels match parser/time-zone behavior, exact timestamps available, display age separate from health, no server-zone conversion under UTC labels |
| Error | Failure ≠ empty/zero/success. Preserve safe last-known values and their age, preserve drafts, offer an appropriate retry |
**Removing duplicate CSS:** inventory both declarations and matching call sites. Compare against the exact adopted package, then delete only identical rules. Keep app-specific geometry, protocol form layout, topology/editor code and supported-scheme overrides until replaced by equivalent shared behavior.
**Framework compatibility:** GB standardizes all seven current bUnit test projects on 2.7.2 before UI work. Later snippets and fixtures use `BunitContext`, `Render`, `AddAuthorization` and the stable doubles/lifecycle APIs. Retain OtOpcUa xUnit v3 cancellation context and other projects’ xUnit v2; MX/OEE HtmlRenderer and registry Playwright remain unchanged. The exact parser family must pass actual runtime tests. Browser-only focus/layout cannot be established by bUnit/static markup checks.
## Package adoption ledger
Source pins below are review/planning baselines, not deployed versions. Confirm actual transitive resolution before each upgrade and record exact selected versions/hashes after execution.
| Consumer | Baseline | Shared target | Additional checks |
|---|---|---|---|
| Theme source | 0.5.3 | `THEME_VERSION` | Token compatibility policy; retain fonts/static-asset paths |
| Secrets UI source | Theme 0.2.0 dependency; library source currently 0.6.6 | Theme `THEME_VERSION`, library `SECRETS_UI_VERSION` | Restored host graph may already resolve newer Theme; do not downgrade |
| Overview | Theme 0.5.0 | `THEME_VERSION` | Anonymous/read-only; purple accent |
| ScadaBridge | Theme 0.5.3 | `THEME_VERSION`, required Secrets package | Existing local dark palette, sandbox/editor boundaries and audit lifecycle |
| OtOpcUa | Theme 0.5.0 | `THEME_VERSION`, required Secrets package | SSR/interactive routes; raw/UNS trees; driver authoring invariants |
| MxAccessGateway | Theme 0.5.0 | `THEME_VERSION`, required Secrets package | Worker/COM workflow acceptance requires its actual platform |
| HistorianGateway | Theme 0.5.0 | `THEME_VERSION`, required Secrets package | Green accent; `.rail-btn` usage; live historian writes only in approved test target |
| BTDB Manager | Theme 0.4.1 | `THEME_VERSION` | Teal accent; audit/transfer semantics and 7-digit time precision |
| ignitionoee router | Theme 0.5.0 | `THEME_VERSION` | Policy gates, offline/site sync and schedule/data semantics |
| ignitionoee registry | Local token/shell CSS | Versioned canonical static CSS/token export | No blind domain stylesheet deletion; preserve native dialog and editor geometry |
| Perspective operator views | Native view/style JSON | Platform-compatible versioned token/style mapping | Native Ignition resources, no Blazor dependency, existing role/site/offline rules |
Registry deliberately remains on its documented public-NuGet-only dependency policy. G1 therefore includes a versioned static CSS/font/token export generated from the exact reviewed Theme package. Registry vendors verified assets under `registry/src/Registry.Host/wwwroot/shared-theme/` and retains native markup/domain CSS. Perspective initially maps canonical tokens into existing native `props.style` resources; use named style classes only after a Designer-exported fixture proves their resource format. Neither integration becomes a hand-maintained palette fork.
## Test and visual acceptance matrix
Execute the smallest meaningful regression first, make it fail for the specific observed defect, implement the minimal fix, then run the affected project suite. Keep existing tests that protect protocol, audit, authorization, precision and disabled behavior. Do not write unit tests merely restating a margin/color declaration; inspect real rendered styles instead.
| Dimension | Required cases and evidence |
|---|---|
| Viewports | 1440×900 desktop, 1024×768 short desktop, 390×844 phone, actual browser 200% zoom; supported Chromium/Firefox/WebKit engines as agreed at G0 |
| Navigation | Mobile closed/open keeps content visible; long rail scrolls; session/footer reachable; current location truthful; policy-allowed destinations only |
| Keyboard | Tab/Shift+Tab, Enter/Space, Escape where appropriate; sortable headers, row disclosures and tree expanders; focus visible and not clipped |
| Screen reader | Programmatic names/descriptions, exact modal title, validation/recovery, no repeated announcement flood or secret disclosure |
| Color | Computed text contrast ≥4.5:1 for ordinary small text; large text/nontext UI/focus as applicable ≥3:1; stale opacity, theme overrides and every supported scheme |
| Motion | Reduced motion presents final content; state is still textual and immediate |
| State | Initial load, pending, empty, no-match, denied, unavailable, stale/paused, busy, success, validation failure, backend failure, cancellation/conflict |
| Data scale | Long identifiers/error text, deep tree, lazy/unloaded branches, large inventory; scoped horizontal scroll and preserved selection |
| Time | UTC boundaries, server/browser in different zones, daylight-saving edge where local display exists, exact persisted precision, sample age vs latest attempt |
| Safety semantics | Duplicate submission prevented; commit and subsequent reload/audit outcomes kept distinct; no retry of an already committed action; correct row/target identity |
| Operational truth | Protocol/controller/worker failures never painted healthy; unavailable counts are unknown; evidence/eligibility and application/runtime state stay distinct |
For every representative screen save route, commit, viewport, role, scheme, fixture description, screenshot and keyboard/state result. Use synthetic fixture data; redact operational identifiers where the local process requires it. A screenshot proves composition only; it does not prove server authorization or database correctness.
**Representative route coverage:** each chapter's finding-to-task table covers its recommendations, and its route-family inventory drives regression sampling. Extend automated coverage to the real failure paths; the 13 concepts are not the entire route set. The initial active-source inventory discovered 168 route declarations across the indexed checkouts, including aliases and hosted shared pages; route declarations are not equivalent to distinct runtime screens.
## Rollout, rollback and completion
1. Close GB and record exact bUnit/parser versions and migrated suite evidence first. Then finish the shared library/unit/component checks and two local candidate pilots; record G1 and actual immutable package/hash.
2. Ship shared Secrets UI once its target-isolation and interaction tests pass; resolve the consumer graph explicitly rather than assuming source and host pins are equal.
3. For each consumer, commit package adoption separately from domain UX changes where practical. Keep commits small enough to identify a specific regression; preserve pre-upgrade package lock and application artifact.
4. Run the chapter's focused and full checks, compare real screens to the same shared contract, then run @impeccable audit and one bounded @impeccable polish. Re-audit findings rather than treating a detector-empty result as accessibility conformance.
5. Publish/deploy only through the relevant repository's documented release process with the execution session's authorization. This plan does not itself authorize production mutations or live historian/secret operations.
6. Use the existing development environment first, then QA, then each approved target. Clustered deployments follow the application's paired-node/migration procedures; a UI-only plan must not rewrite those procedures. Native Ignition resources require schema validation and Designer/session acceptance.
7. Rollback the whole validated application artifact and its pinned package set. Do not restore only CSS while leaving components expecting a new API. For native styles, keep the prior resource export. A rollback cannot reverse audited data mutations; these changes are designed to require no schema migration.
8. For each gate, record actual test results, screenshots, restored package versions, environment and remaining blockers. Record infrastructure-blocked checks explicitly and leave their tasks incomplete. Do not claim a live pass from offline or mockup tests.
9. Mark G3 complete only after every P1 and agreed P2 task has passed its chapter acceptance, shared DS findings are adopted consistently, optional work has an explicit disposition, and no regression is hidden by local palette/component copies.
## Deferred product choices
These are recommendations requiring evidence or a product decision, not reasons to stop the implementation plan:
- Timed secret auto-hide: implement predictable reveal/hide focus and announcements first; choose exposure timing separately, with warning/extension behavior if required. Do not introduce silent timeouts.
- Overview list/attention mode: keep full-fleet topology as default; add an optional filter/list only with confirmed state/scale semantics.
- Generic modal component: extract after two pilots; use validated local adapters first.
- Full shared dark scheme: preserve current supported dark UI and accessible aliases; separate expansion into a fully tested Theme release.
- Perspective named style-class extraction: first use generated mappings in existing native views; introduce named resources only after a valid Designer-exported fixture establishes their format.
- Virtualization or memoization: measure realistic render/data cost before adding complexity; preserve lazy-loading scope and real state behavior.
## Final execution record
Each chapter's task IDs and coverage table are the source for [tasks.json](2026-11-12-scada-ui-consistency/tasks.json). Update that ledger only after the corresponding evidence exists. Implementation should use @executeplan with a batch review checkpoint after bUnit standardization, shared Theme, shared Secrets, each sister application, and the cross-family release pass. @writeplan produced these documents; no product code was changed by the planning task.
## November14 execution scope clarification
The user explicitly instructed “Don’t do voiceover tests.” VoiceOver testing is
excluded across this execution. Automated accessibility-tree, semantic, keyboard,
contrast and browser checks remain in scope; no human speech-output certification
is claimed. This overrides earlier generic screen-reader wording wherever it
would require VoiceOver testing. Production deployment remains separate.