docs(ui): preserve family review and phased execution plan
This commit is contained in:
@@ -0,0 +1,106 @@
|
||||
# ZB.MOM.WW.Overview — fleet visibility
|
||||
|
||||
Reviewed November 12, 2026. Mode: Operate. [Mockup](mockups/Overview.html) · [Shared contract](SHARED-DESIGN-SYSTEM.md).
|
||||
|
||||
## Scope and current identity
|
||||
|
||||
Deeply inspected the single `/` page, `InstanceCard`, `MainLayout`, `App`, and `wwwroot/css/site.css`. Scanned the snapshot/poller boundary and existing dashboard mockup. These cover the application’s complete page/component surface; the [inventory](evidence/source-inventory.json) records the checkout. Source pins Theme **0.5.0** (`src/ZB.MOM.WW.Overview/ZB.MOM.WW.Overview.csproj:28`). Preserve its existing purple accent (`MainLayout.razor:9`), anonymous read-only operation, app/group hierarchy and distinct ready/active/leader signals.
|
||||
|
||||
Paths below are relative to `ZB.MOM.WW.Overview/src/ZB.MOM.WW.Overview/`. This is source inspection; the current deployed dashboard was not browser-tested. The HTML concept is independently rendered review artwork.
|
||||
|
||||
## Findings
|
||||
|
||||
### OV-01 · P1 · Stale information becomes harder to read precisely when needed
|
||||
|
||||
**Evidence:** `wwwroot/css/site.css:57–58` lowers instance body and host opacity to 0.55; `:65–67`, `:75`, and `:79–82` use small faint text. Shared DS-01 already measures faint ink below 4.5:1 before dimming.
|
||||
|
||||
**Impact:** operators investigating stale nodes lose readable last-known values and host identity.
|
||||
|
||||
**Recommendation:** adopt shared accessible ink tokens; keep stale values fully opaque and mark freshness explicitly with “Stale · last successful response …” and a neutral surface treatment. Separate freshness from last known health.
|
||||
|
||||
**Ownership / acceptance:** Theme for token fixes, Overview for opacity/state presentation. Read host/error/freshness at 200% zoom, verify computed contrast, and confirm stale still reads as stale when color is unavailable. Suggested commands: colorize, harden.
|
||||
|
||||
### OV-02 · P1 · Individual check state relies on a colored square
|
||||
|
||||
**Evidence:** `Components/Widgets/InstanceCard.razor:79–82` renders dot class, check name and freeform description without the entry's actual status text. A description need not repeat its state.
|
||||
|
||||
**Impact:** color-independent and screen-reader inspection cannot reliably distinguish a healthy/degraded/unhealthy check from markup alone.
|
||||
|
||||
**Recommendation:** include explicit per-check status text, with decorative dot hidden from assistive technology. Keep the real check description; do not replace it with generic healthy copy.
|
||||
|
||||
**Acceptance:** keyboard/screen-reader users can name each check's status without interpreting a color or inferring from description. Owner: Overview. Suggested commands: harden, clarify.
|
||||
|
||||
### OV-03 · P2 · Pause and connection language imply the wrong state
|
||||
|
||||
**Evidence:** `Components/Pages/Overview.razor:26–31` maps `_paused` to a disconnected connection pill; `:140–151` deliberately stops adopting snapshots while the backend poller continues. No toggle pressed state is supplied.
|
||||
|
||||
**Impact:** a paused view can look like a network outage; operators cannot immediately tell whether collection or only their display is paused.
|
||||
|
||||
**Recommendation:** say “View paused — background polling continues,” retain snapshot age, use neutral rather than failure styling, expose the button's toggle state. Announce pause/resume once in a polite status region, not every five-second tick.
|
||||
|
||||
**Acceptance:** pause freezes adopted values, timestamps keep aging, resume adopts latest snapshot, and announcements clearly describe display behavior. Owner: Overview. Suggested commands: clarify, harden.
|
||||
|
||||
### OV-04 · P2 · Group summary combines stale and unreachable under one label
|
||||
|
||||
**Evidence:** `Components/Pages/Overview.razor:207–212` counts either `Unreachable` or stale as `missing`, then labels that total “unreachable.”
|
||||
|
||||
**Impact:** a healthy last-known node whose view is paused can be reported as unreachable at group level, even though freshness and network state are different signals.
|
||||
|
||||
**Recommendation:** show separate counts for unreachable and stale, and label overlaps clearly; application rollups should communicate whether their data is stale even if the stored worst status was healthy.
|
||||
|
||||
**Acceptance:** paused healthy sample, fresh unreachable sample, stale unreachable sample and mixed group each produce truthful distinct labels without double-counting an overall affected total. Owner: Overview. Suggested commands: clarify, harden.
|
||||
|
||||
### OV-05 · P2 · Full error evidence is hidden in a hover title
|
||||
|
||||
**Evidence:** `Components/Widgets/InstanceCard.razor:65–69` truncates error text to 48 characters and exposes the remainder only through `title`. Check names have `min-width:9.5rem` in flex rows (`site.css:89–92`); descriptions have no explicit narrow-screen stacking rule.
|
||||
|
||||
**Impact:** touch/keyboard users cannot reliably read the complete diagnostic cause; long names/descriptions can crowd narrow cards.
|
||||
|
||||
**Recommendation:** put full error evidence in a native disclosure with wrapping text. Stack check name, text status and description on narrow cards. Avoid putting a tooltip in the critical recovery path.
|
||||
|
||||
**Acceptance:** 390px viewport, 200% zoom and long diagnostic text remain readable; no document-level overflow; disclosures work by keyboard. Owner: Overview. Suggested commands: adapt, harden.
|
||||
|
||||
### OV-06 · P2 · Fleet scale needs an optional exception-focused view
|
||||
|
||||
**Evidence:** `Components/Pages/Overview.razor:46–120` renders six aggregate cards and every application/group/instance, with no filter or compact triage view. `:178–182` shows server-local time without a zone label.
|
||||
|
||||
**Impact:** larger fleets require scanning healthy instances to find problems; users on a different zone may misinterpret “last sweep.” This is a scale recommendation, not a measured performance defect.
|
||||
|
||||
**Recommendation:** retain the full fleet default and offer a labeled “Needs attention” filter, with separate state/freshness columns or a compact list. Keep native check details and raw ready/active evidence. Label the actual zone or use explicit UTC. The mockup illustrates the optional list view; do not remove useful topology cards without validation.
|
||||
|
||||
**Acceptance:** clearing filters always restores the full fleet; absent values read Unknown/Pending, not zero/healthy; changing views preserves group identity and leader/active distinctions. Owner: Overview. Suggested commands: layout, clarify.
|
||||
|
||||
## Preserve
|
||||
|
||||
- Snapshot-driven rendering; pages never probe independently and a local tick keeps freshness aging.
|
||||
- Stale is treated as distinct from a fresh sample; pause does not stop collection.
|
||||
- Active and Akka leader remain separate, with raw cluster evidence available.
|
||||
- MXAccess session counts differ from Historian warm pool depth; a zero warm pool is normal.
|
||||
- Anonymous and read-only is an explicit requirement. Add no login or mutation controls.
|
||||
- External management links already use `rel="noopener"`.
|
||||
|
||||
## Delivery and validation
|
||||
|
||||
1. DS-01, OV-01/02: readable stale values and textual check state.
|
||||
2. OV-03/04/05: truthful pause/rollup language and accessible diagnostics.
|
||||
3. OV-06: optional triage view, time-zone labeling, and supported-package adoption.
|
||||
|
||||
Verify initial pending, empty/not-yet-polled, healthy, degraded, down, unreachable, stale, split-leader evidence, pause/resume, long host names and large fleet behavior. Preserve independent per-target publishing. Measure render cost with realistic fleet size before adding virtualization. Run Impeccable audit and polish after implementation. Runtime accessibility/performance conformance remains unverified.
|
||||
|
||||
## Independent verification
|
||||
|
||||
A second source review checked the complete page/widget markup, the snapshot publication contract, pause/adoption behavior, status/freshness derivation, local CSS, and shared-theme consumption. The six findings are supported by source; no live/runtime result is implied. The snapshot remains immutable per published graph, and remote cluster evidence is HTML-escaped before the deliberate `MarkupString`; preserve both protections.
|
||||
|
||||
The combined [source detector run](evidence/shared-surfaces-detector.json) covered Overview, Secrets UI and Theme once. Its four findings all point to Overview's vendored Bootstrap CSS: generic caret border geometry and collapse width/height transitions. These are library definitions, not evidence of a failing displayed dashboard. No app-authored deterministic warning was emitted; manually verified findings above remain actionable.
|
||||
|
||||
|
||||
## Rendered proposal previews
|
||||
|
||||
These are proposed UI artifacts with illustrative data, not screenshots of the current application. All use the same shared stylesheet. See [verification and limits](VERIFICATION.md).
|
||||
|
||||
### Overview
|
||||
|
||||
[Interactive HTML](mockups/Overview.html) · [Desktop PNG](evidence/Overview-desktop.png) · [Mobile PNG](evidence/Overview-mobile.png)
|
||||
|
||||

|
||||
|
||||
Reference in New Issue
Block a user