30 KiB
MxAccessGateway UI consistency Implementation Plan
For Codex: REQUIRED SUB-SKILL: Use
executeplanto implement this plan task-by-task.
Goal: Make browsing, dialogs and exception triage accessible while preserving shared Technical-Light chrome and runtime semantics.
Architecture: Keep the .NET dashboard’s existing shared Theme shell and app-owned Galaxy/session state mapping. Adopt G1 assets, pilot native modal behavior locally, then converge repeated visual rules without touching COM worker or wire contracts.
Tech Stack: net10.0 Blazor, Bootstrap CSS, Theme currently 0.5.0, xUnit 2.9.3, framework HtmlRenderer; real browser validation for DOM/focus.
Required testing prerequisite
Complete bUnit standardization and close GB before any task in this chapter, including local fixes and candidate UI pilots. All bUnit snippets below use the post-GB BunitContext / Render / AddAuthorization API; their inherited helpers must be migrated in GB. Preserve framework HtmlRenderer methods and xUnit runner APIs where used. Non-bUnit runtimes retain their existing harnesses, but their UI work also waits for the family gate. Old package pins are discovery baselines, not targets for this chapter.
Execution contract
- Repository:
/Users/dohertj2/Desktop/MxAccessGateway. All source/test paths below are relative to that root; use it as cwd unless a step states otherwise. - Planning date: 2026-11-12. This chapter specifies future work; no implementation or test execution is claimed.
- Read the corresponding
/Users/dohertj2/Desktop/scadaproj/impeccable/MxAccessGateway.md, the shared design-system report, the master plan and applicableAGENTS.mdbefore execution. - Reuse a suitable checkout; inspect
git status --shortand preserve user edits. No new worktree, commit, push, package publication or deployment is performed by authoring this plan. - Dependency gate: complete shared Theme G1 compatibility audit, assign
THEME_VERSION, and verify its artifact before consumer migration.THEME_VERSIONis a placeholder, never a literal package version to publish. - Shared G1 supplies semantic status ink (
--ok-ink:#236f34,--warn-ink:#855000,--bad-ink:#b42121,--idle-ink:#535d66),--ink-faint:#626970, and independent blue--info-ink; product accent never recolors semantic informational notices. - G1 adds
TechField.For,HintId,ErrorId; callers supply input IDs,aria-describedbyandaria-invalid. G1 addsThemeShell.AccentDeep,AccentTint,AccentBorder,AccentFocuswhile preservingAccent. - Shared accent aliases must resolve in shell scope: G1 uses
--accent-tintdirectly or rebinds inherited aliases at.app-shell. Bootstrap.btn-primary/ghost component variables must follow shell accent for normal/hover/active/disabled states. Compare computed states before deleting any consumer override. - G1 also supplies shared focus/busy/reduced-motion and filter/table/dialog recipes.
TechButton.BusyTextis optional; busy addsaria-busy. Caller-owned status/alert text announces outcomes, never secret values or every polling update. - Pilot native dialogs in two consumers before extracting a common dialog component. Do not build a new component package during a first consumer migration.
- Restore/build first and record actual dependency/runtime failures. Complete GB bUnit/parser standardization first. Preserve xUnit, test SDK and Playwright versions unless a specific demonstrated compatibility fix is recorded in GB; do not perform later incidental framework upgrades. Never treat a skipped native/SQL/COM/live test as a pass.
- Each numbered step is one short action. When a step discovers broader product behavior, stop that task at its boundary and update this written plan before expanding implementation scope.
Verified starting point and package migration gate
src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj:18directly pins Theme 0.5.0; Secrets and Secrets.Ui are 0.6.2. Do not alter Secrets references until shared Secrets releaseSECRETS_UI_VERSIONis assigned and its Theme graph agrees withTHEME_VERSION.- Current tests use xUnit and
Microsoft.AspNetCore.Components.Web.HtmlRenderer; this repository does not currently use bUnit. Copy framework renderer setup fromDashboard/SettingsPageTagVisibilityRenderTests.cs; do not paste bUnit APIs here. - Current snapshot pages use one in-process shared feed (
Dashboard/Components/DashboardPageBase.cs), not one SignalR loopback per page. Preserve subscription cancellation and ACL behavior. - Record baseline using
dotnet restore src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj,dotnet list src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj package --include-transitive, and focused dashboard tests. After G1, edit the explicit Theme pin, restore and confirm the resolved graph; compare output before any local CSS deletion. - Blue accent remains
#2f5fd0. No worker executable, alarms protocol, role policy, or gateway option changes belong to this migration.
Findings coverage
| Report finding | Planned task | Primary proof |
|---|---|---|
| MX-01 keyboard/touch subscriptions | MX-01 | Named toggle render + keyboard watch browser flow |
| MX-02 unmanaged overlays | MX-02 | Native dialog render + actual focus/inertness checks |
| MX-03 unnamed browse search | MX-03 | Accessible field + clear/no-match behavior |
| MX-04 equal-weight overview metrics | MX-04 | Fault-first fixture, all counters retained |
| MX-05 copied colors/component rules | MX-05 | Computed token/contrast + before/after views |
| MX-06 hover-only error detail | MX-06 | Safe diagnostic disclosure and retry |
| MX-07 tiny tree controls | MX-07 | Coarse-pointer hit areas and containment |
| MX-08 destination/action vocabulary | MX-08 | Rail/title/heading consistency |
Shared test helper used below
Create src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardMarkup.cs once. Use this complete helper for markup-only contracts; it does not simulate clicks, keyboard focus or JS interop:
using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
namespace ZB.MOM.WW.MxGateway.Tests.Dashboard;
internal static class DashboardMarkup
{
internal static async Task<string> RenderAsync<T>(Dictionary<string, object?> values)
where T : IComponent
{
var services = new ServiceCollection();
services.AddLogging();
await using var provider = services.BuildServiceProvider();
await using var renderer = new HtmlRenderer(provider,
provider.GetRequiredService<ILoggerFactory>());
return await renderer.Dispatcher.InvokeAsync(async () =>
{
var result = await renderer.RenderComponentAsync<T>(
ParameterView.FromDictionary(values));
return result.ToHtmlString();
});
}
}
JS-dependent lifecycle work belongs in OnAfterRenderAsync, which static rendering does not execute. For page tests requiring DI, extend the existing SettingsPage fixture pattern with real service interfaces and inert snapshot feed; do not register null services solely to make rendering pass.
MX-01: Make tree expansion and watching explicit
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor - Create
src/ZB.MOM.WW.MxGateway.Tests/Dashboard/BrowseTreeAccessibilityTests.cs - Create
src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardMarkup.cs
Step 1 — Establish the failing behavior. Add this test to the new xUnit class with imports for the existing shared component, dashboard model and ZB.MOM.WW.GalaxyRepository.Grpc.
[Fact]
public async Task Node_toggle_names_its_object_and_exposes_collapsed_state()
{
var node = new DashboardBrowseNode {
Object = new GalaxyObject { BrowseName = "Pump01" }, HasChildrenHint = true
};
var markup = await DashboardMarkup.RenderAsync<BrowseTreeNodeView>(
new() { ["Node"] = node });
Assert.Contains("Expand Pump01", markup);
Assert.Contains("aria-expanded=" + '"' + "false" + '"', markup);
}
Step 2 — Run the focused check. From the repository root:
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~BrowseTreeAccessibilityTests
Expected before: the collapsed node exposes generic Toggle and lacks aria-expanded; the named/state assertions fail.
Step 3 — Implement in small edits.
- Keep
OnLoadChildrenandOnAddTagcallbacks and lazy rendering unchanged. - Replace label-span click handling with a named expansion button; add stable controls ID and lowercase
aria-expanded. - Expose a real Watch attribute button on each expanded attribute and search hit; call the existing
AddTagAsyncpath exactly once. Keep right-click/double-click only as accelerators. - Add a browser acceptance record
docs/ui-validation/technical-light-browse.mdincluding permitted read-only fixture account/scope and full keyboard sequence.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. In a disposable fixture expand with Enter, Tab to Watch, activate with Space, and assert exactly one subscription row. Repeat on a touch viewport and verify repeated watch does not duplicate subscriptions. Changing/removing tags still obeys existing ACL and cleanup behavior.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "fix: make Galaxy watch workflow keyboard accessible". Do not include generated credentials, runtime data or unrelated edits.
MX-02: Pilot native dialogs with actual focus management
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/ConfirmDialog.razor - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/ApiKeysPage.razor - Create
src/ZB.MOM.WW.MxGateway.Server/wwwroot/js/dashboard-dialog.js - Create
src/ZB.MOM.WW.MxGateway.Tests/Dashboard/ConfirmDialogRenderTests.cs
Step 1 — Establish the failing behavior. Render a requested confirmation. The test below proves that a semantic native modal is emitted; the browser procedure below is the focus/inertness gate, not this markup assertion.
[Fact]
public async Task Requested_confirmation_renders_named_native_dialog()
{
var markup = await DashboardMarkup.RenderAsync<ConfirmDialog>(new() {
["IsOpen"] = true, ["Title"] = "Close session example", ["Message"] = "Clients will disconnect."
});
Assert.Contains("<dialog", markup);
Assert.Contains("aria-labelledby=", markup);
Assert.Contains("Close session example", markup);
Assert.Contains("Cancel", markup);
}
Step 2 — Run the focused check. From the repository root:
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~ConfirmDialogRenderTests
Expected before: there is no <dialog> element; the title and cancel text currently render in a presentation overlay.
Step 3 — Implement in small edits.
- Replace the div/backdrop mechanism with
<dialog @ref=... aria-labelledby=...>; callshowModal()only after interactive render. - Import the local JS module once, capture the invoking element before showModal, and restore focus after close if the trigger still exists.
- Use a real
cancelevent listener with itseventparameter; prevent dismissal while busy and otherwise invoke the safe cancel callback. Do not readwindow.eventor use an event after awaiting a Blazor round trip. - Apply the same local pilot behavior to create-key overlay. Remove duplicate backdrop once native modal is used; keep all policy gates and pending-state ownership.
- Dispose listeners/module and handle circuit disconnect; do not trap Tab manually over native dialog or dispatch a write from JS.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Use a real browser: focus trigger → open → Tab/Shift+Tab cycles in dialog; outside controls cannot receive focus; Escape cancels only when safe; focus returns. During a delayed confirm, Escape cannot issue a second operation. Verify validation feedback and one-time-token handling without capturing plaintext tokens. Record this as consumer pilot 1; extraction waits for OEE pilot 2.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "fix: manage gateway dialog focus and dismissal". Do not include generated credentials, runtime data or unrelated edits.
MX-02 real-browser focus check
Run in the connected browser automation session against a disposable local fixture; page is that session’s Playwright page. First navigate to a session whose safe confirmation trigger is named below; match the actual fixture’s accessible name rather than guessing a production account.
const trigger = page.getByRole('button', {name: 'Close session', exact: true});
await trigger.focus();
await trigger.press('Enter');
const dialog = page.getByRole('dialog');
await dialog.waitFor({state: 'visible'});
if (!(await dialog.evaluate(d => d.contains(document.activeElement))))
throw new Error('Initial focus outside confirmation');
for (let i = 0; i < 24; i++) {
await page.keyboard.press(i % 2 ? 'Shift+Tab' : 'Tab');
if (!(await dialog.evaluate(d => d.contains(document.activeElement))))
throw new Error('Focus escaped confirmation');
}
await page.keyboard.press('Escape');
await dialog.waitFor({state: 'hidden'});
if (!(await trigger.evaluate(e => e === document.activeElement)))
throw new Error('Trigger focus not restored');
This opens then cancels; it sends no close-session request. Repeat on create-key dialog without submitting, then use an isolated delayed fake to prove busy confirm dispatches exactly once. Never run an acceptance write against a live session merely to verify focus.
MX-03: Label and recover browse search
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor - Modify
src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardBrowseServiceTests.cs - Create
src/ZB.MOM.WW.MxGateway.Tests/Dashboard/BrowseSearchAccessibilityTests.cs
Step 1 — Establish the failing behavior. Use the existing BrowseService fake/model setup to render BrowsePage with at least one cached root. Add a field contract test asserting label for="browse-search", input id="browse-search" and non-empty results/no-match text. Keep query/cap tests in DashboardBrowseServiceTests.
Step 2 — Run the focused check. From the repository root:
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~BrowseSearchAccessibilityTests
Expected before: search has only a placeholder and no permanent label/clear action.
Step 3 — Implement in small edits.
- Add persistent “Filter Galaxy attributes” label plus hint/result IDs.
- Set caller-owned
aria-describedbyon input; use the G1 field association recipe if TechField is adopted. - Add Clear search that cancels any obsolete pending query, resets matches and returns focus; display no matches distinctly from no cache.
- Publish a polite count only when the search result changes, not on every live value refresh.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Type a non-match, clear via keyboard, and verify prior tree expansion/subscriptions remain. Rapidly type two different queries; late results must not overwrite the current query. Use existing server cap and indexes, no new full-tree scan.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "fix: label Galaxy search and clarify no-match recovery". Do not include generated credentials, runtime data or unrelated edits.
MX-04: Make overview prioritize faults while preserving counters
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor - Modify
src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css - Create
src/ZB.MOM.WW.MxGateway.Tests/Dashboard/DashboardHomeRenderTests.cs
Step 1 — Establish the failing behavior. Build a snapshot fixture using the existing SettingsPage stub/feed idiom, with one fault, one session and non-zero supporting counters. Assert the fault message and affected-session link render, then assert supporting counters are still reachable in a labeled details element.
Step 2 — Run the focused check. From the repository root:
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~DashboardHomeRenderTests
Expected before: fault context is not linked from an exception-first summary and supporting counters are not a disclosure.
Step 3 — Implement in small edits.
- Render sampled-time/gateway-state context beside the heading.
- Lead the content with actionable recent faults and links to the existing sessions route; preserve server-side visibility filtering.
- Keep sessions/workers/queue context grouped; move lifetime/event/repository-size counters to a labeled supporting-counters disclosure.
- Separate Repository status link (
/galaxy) from Browse attributes (/browse); do not add invented metrics or new polling.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Review a healthy snapshot, mixed fault snapshot and zero-session snapshot side by side at desktop/mobile. Capture the retained counter inventory and confirm the first viewport identifies the fault. Numeric values must match the same snapshot before/after composition.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "refactor: prioritize gateway fault context on overview". Do not include generated credentials, runtime data or unrelated edits.
MX-05: Adopt shared ink and remove duplicated visual rules
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj - Modify
src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor - Create
docs/ui-validation/technical-light-token-migration.md
Step 1 — Establish the failing behavior. This is a CSS/package migration: capture the same fixture screens and computed colors before editing. Do not write a test that merely asserts a CSS declaration exists.
Step 2 — Run the focused check. From the repository root:
dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~Dashboard
Expected before: the baseline contrast check identifies inherited failing status ink and local hardcoded shade islands; builds/tests should already pass.
Step 3 — Implement in small edits.
- Wait for
THEME_VERSION; update Theme pin and resolve the graph including Secrets.Ui. - Map local success/failure notices to semantic ink tokens, not bright status swatches. Info uses independent blue
--info-ink. - Replace repeated zebra/hover/active/tint literals with shared tokens; delete only byte/behavior-equivalent button/field rules after computed-style comparison. Keep browse geometry and domain classes local.
- Retain blue shell accent; if providing the new optional accent family, use G1-approved matching values, not green/blue mixtures.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Run the master computed contrast matrix on local alert/tree/table states; compare hover, focus, disabled, busy and validation states. No extra unit tests for this reversible styling change. Record package graph and screenshots.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "style: adopt shared gateway status ink and tokens". Do not include generated credentials, runtime data or unrelated edits.
MX-06: Expose safe errors and retry without losing context
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor - Update
docs/ui-validation/technical-light-browse.md
Step 1 — Establish the failing behavior. Use an isolated browser fixture whose Pump01 child load fails once with long safe diagnostic text, then succeeds on retry. Record the failing browser flow below. Do not claim static HtmlRenderer can expand the private node state or dispatch callbacks; the existing named-toggle render tests remain regression checks.
Step 2 — Run the focused check. From the repository root:
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~BrowseTreeAccessibilityTests
Expected before: the failure text is abbreviated and the existing loaded/error path lacks a dedicated retry control.
Step 3 — Implement in small edits.
- Render safe short failure summary plus named Retry load; allow retry when LoadState is Error while preserving siblings.
- Expose full safe detail under a native disclosure; continue using the existing redaction boundary and never print secrets/connection strings.
- Use one alert for user-triggered failures and polite recovery status; do not announce every poll.
- Retain watched tags and current search/tree context while retry runs.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Induce child-load failure and recovery; use keyboard and touch to read detail/retry. Verify success does not rebuild the entire tree or clear subscription rows. Confirm repeated failed retries are bounded by existing request behavior, not an added automatic retry loop.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "fix: expose recoverable Galaxy browse errors". Do not include generated credentials, runtime data or unrelated edits.
MX-06 failing recovery browser flow
Run against the isolated once-failing Pump01 browse fixture in the connected Playwright session. The fixture must hold one previously watched sibling tag and log load-attempt counts so retry/recovery can be verified without production dependencies.
await page.getByRole('button', {name: 'Expand Pump01', exact: true}).press('Enter');
const retry = page.getByRole('button', {name: 'Retry loading Pump01', exact: true});
await retry.waitFor({state: 'visible'}); // fails before a retry action exists
await page.getByText('Show diagnostic details for Pump01', {exact: true}).press('Space');
if (!(await page.getByText('Fixture child load failed', {exact: true}).isVisible()))
throw new Error('Diagnostic detail is unavailable without hover');
await retry.press('Enter');
await page.getByRole('button', {name: 'Watch Pump01.PV', exact: true})
.waitFor({state: 'visible'});
The exact names above are the planned accessible contract for this fixture. Assert the sibling subscription count is unchanged and fixture load count increased by exactly one after Retry. Static source/render checks are supplementary; successful recovery requires this actual DOM/callback sequence.
MX-07: Apply shared coarse-pointer and containment rules
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/wwwroot/css/site.css - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Shared/BrowseTreeNodeView.razor - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/BrowsePage.razor - Update
docs/ui-validation/technical-light-browse.md
Step 1 — Establish the failing behavior. Capture tree toggle and subscription remove control bounding boxes at compact desktop and coarse-pointer mobile. Use the same seeded 200-character tag path; no declaration-mirroring unit test.
Step 2 — Run the focused check. From the repository root:
dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj
Expected before: the 1.1rem toggle is below the proposed coarse-pointer 44px target; long-path mobile behavior must be measured.
Step 3 — Implement in small edits.
- Adopt G1 sizing utilities, keeping visible chevrons compact but hit areas ≥44px on coarse pointers.
- Ensure grid children use min-width:0 and long tables/tree scroll inside named regions rather than widening the document.
- Keep remove/watch actions visible or accessible in row detail with full labels; preserve full tag value for copying.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. In browser verify 390px and 200% zoom, Tab into table scroller and reach last columns; inspect document.documentElement.scrollWidth <= innerWidth. Check desktop row density remains usable.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "style: improve gateway browse touch targets and containment". Do not include generated credentials, runtime data or unrelated edits.
MX-08: Normalize destination and action language
Files:
- Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Layout/MainLayout.razor - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/DashboardHome.razor - Modify
src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/Login.razor - Update
docs/ui-validation/technical-light-token-migration.md
Step 1 — Establish the failing behavior. Compare visible rail, h1 and document title in the existing fixture. This copy-only change needs a review checklist rather than a brittle exact-markup unit test.
Step 2 — Run the focused check. From the repository root:
dotnet build src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj
Expected before: the rail says Dashboard while the landing heading says Overview; capitalization differs across sisters.
Step 3 — Implement in small edits.
- Use Overview consistently for the landing destination; use API keys / Sign out / Refresh in family sentence case.
- Keep route URLs, stable NavRailSection keys and runtime status enum text unchanged.
- Review fault and action wording with real session identifiers; do not rename domain contracts or policy constants.
Step 4 — Verify the change. Re-run Step 2; expected after: PASS for the named tests or all stated visual checks. Confirm one active rail item per route, correct document title and current heading. Run existing logout/auth/policy tests and source review for unchanged keys.
Step 5 — Commit. Stage only the listed production/test/evidence files, inspect git diff --cached, then git commit -m "docs: align gateway UI labels with shared vocabulary". Do not include generated credentials, runtime data or unrelated edits.
Cross-cutting state and viewport matrix
| State | Expected contract | Verification |
|---|---|---|
| First load / slow work | Page identity remains; busy action disabled with meaningful busy text; no false successful zero | Delayed fixture and keyboard |
| Healthy | Text label plus status token, sampled time, real scope | Representative fixture |
| Warning / failed dependency | Plain summary, affected scope and recovery; safe detail disclosure | Fault fixture; no raw secret/connection string |
| Refresh fails after success | Keep last good data visibly marked stale; retry does not clear context | Sequential success/failure fake |
| Empty / no matches | Different from loading/failure; clear-filter or next action | Empty source and filtered-to-zero separately |
| Unavailable / unknown | Show unknown/n/a, never substitute numeric zero or Healthy | Null/missing fixture |
| Permission denied | Route and action gates remain server-enforced; nav reflects existing policy | Viewer/Admin/denied accounts |
| Long content | Full identifiers available in detail/copy context; table scroll local | 200-character path and error |
| Keyboard / modal | Visible focus; enter/space activation; real modal inertness and focus restoration | Browser test, not HtmlRenderer |
| Narrow / zoom / motion | 1440×900, 1024×768, 390×844, 200% zoom; reduced motion keeps status feedback | Batched visual pass and at most one confirmation pass |
No runtime timestamps or status values in a mockup are deployment evidence. Keep status domain mapping app-owned. Test color contrast against actual computed backgrounds; screenshots alone do not establish WCAG compliance.
Release, rollback and evidence
- Run
dotnet test src/ZB.MOM.WW.MxGateway.Tests/ZB.MOM.WW.MxGateway.Tests.csproj --filter FullyQualifiedName~Dashboard; then one full project test run if no new failures remain. Record COM/Windows/infrastructure requirements and actual skipped cases; do not disable them to manufacture green results. - Build the Server with the resolved shared package, capture asset/font HTTP 200s in the disposable local browser host and verify browser console has no dialog import or Blazor errors.
- Record an evidence bundle containing dependency graph, commit IDs, viewport captures, measured contrast, keyboard/focus outcomes and state matrix. No actual secrets, token screenshots or operational credentials.
- Follow the repository's existing release process separately. This plan authorizes no deployment and no restart of a live gateway or COM worker. A live gate must use an isolated fixture before an operator-approved environment rollout.
- Roll back by reverting the consumer migration commits and restoring the former explicit Theme pin (currently 0.5.0) plus matching dependency graph. Do not mutate published packages. This UI work has no database migration; if a task introduces one, stop and rescope.
- Removing the native dialog enhancement must restore its previous component version coherently; do not roll back just the JS module while leaving calling markup. Validate browse/watch and session confirmation after rollback.
Done: every finding above is mapped, tests and actual browser outcomes are recorded, shared look/feel agrees with G1, and runtime/permission boundaries are preserved.