Files
scadaproj/impeccable/SHARED-DESIGN-SYSTEM.md
T

11 KiB
Raw Blame History

One Technical-Light family

Review date: November 12, 2026. Mode: Operate. This is a recommendation package and a set of proposed visual artifacts, not an implementation or a production acceptance report.

Direction

Keep the established visual identity: IBM Plex Sans, IBM Plex Mono for identifiers and measurements, warm paper, white working surfaces, fine neutral rules, compact rectangular status chips, a 220px desktop rail, and restrained product accents. Improve the system once, then apply it consistently. Do not give each project a new layout, font, card treatment, or status palette.

The current source in ZB.MOM.WW.Theme is the visual authority. Its Directory.Build.props:7 declares 0.5.3. Consumer versions differ; a version declared in a checkout is not evidence of what is deployed. The old components/ui-theme/README.md “not started” matrix and the shared-contract document's 0.2.0 description are historical evidence, not the present adoption state.

Common contract

Element Family rule Allowed local variation
Shell ThemeShell, one main landmark, a persistent current location, native mobile nav disclosure Product name, role-aware route groups, optional pinned session footer
Accent Existing approved product accent; supply matching deep/hover/focus/tint tokens Preserve Historian green, Overview purple, and any source-verified product accent; no per-page palette
Typography Plex Sans; 14–15px working text; 24–26px page heading in proposals; 18px section heading; mono only for data Domain code/editor font and data density
Surfaces Paper #f4f4f1, card white, neutral border; existing 8px panel radius Specialized topology/editor canvas
Spacing 4, 8, 12, 16, 24, 32px; close related controls, separate tasks Dense desktop tables can use smaller row padding with adequate targets
Page header One h1, short scope/context, freshness where relevant, one primary action Read-only surfaces need no primary action
Actions Shared primary, secondary, danger, ghost treatments; explicit busy/disabled/error states Domain command names and policy rules
Data Labeled filters above data, scoped scrolling, real headers, sort state, stable identity Tree/table/editor presentation appropriate to task
Forms Programmatic label, hint/error association, required state, field-local recovery Protocol-specific editors remain local
Status One semantic palette plus plain state text; separate quality, role, transport, freshness Domain vocabulary stays accurate: pooled ≠ in use, active ≠ leader, disabled ≠ failed
Time Explicit zone and timestamp semantics, relative age plus exact time where useful UTC export, local operational display, or an explicit zone selector
Dialogs Accessible name, initial focus, modal isolation, Escape/cancel where safe, focus return Domain-specific confirmation text and authorization
Responsive Rail collapses below 992px; content remains visible; details stack; wide grids scroll inside their container A complex desktop editor may offer a clearly scoped mobile summary
Touch Aim for 44px touch actions; retain efficient desktop density 24px minimum target/spacing rule must be assessed separately from the 44px design target
Motion Useful state feedback; no repeating entrance choreography; reduced-motion alternatives No requirement to add motion to operational screens

All mockups share one stylesheet and vendored Plex assets. Proposed darkened status inks are intentionally shown in every concept. They are candidates for new semantic foreground tokens, not instructions to repurpose every existing dot/chart token. Mockups simplify domain data to make the recommended hierarchy reviewable. New filters, detail panes, and state selectors are explicitly proposals; they are not claims about existing functionality.

Shared findings and implementation recommendations

DS-01 · P1 · Small status and supporting text need accessible foreground tokens

Evidence: ZB.MOM.WW.Theme/src/ZB.MOM.WW.Theme/wwwroot/css/theme.css:45, :54–57, :76, :187–200, :210–215. Existing small chip text pairs measure 3.09:1 (OK), 3.74:1 (warning), 3.89:1 (bad), 2.91:1 (idle). Faint ink is 3.21:1 on white and 2.92:1 on paper. These ordinary small text treatments fall below a 4.5:1 target. See reproducible pair calculations. This is a token-pair calculation; runtime overlays, opacity, and app overrides need separate verification.

Impact: table labels, state chips, host names, and freshness metadata become difficult to read, especially on industrial displays and stale/dimmed content.

Recommendation: add dedicated status text tokens, preserving brighter colors for dots where appropriate. Proposed foregrounds: OK #236f34, warning #855000, bad #b42121, idle #535d66; secondary/faint text #626970. On existing matching backgrounds these measure 5.55, 5.98, 5.69, 5.88, and at least 5.05 respectively. Audit green/purple accents independently. Keep textual status distinctions.

Acceptance: every actual small-text foreground/background pair reaches 4.5:1 in both supported schemes and all states; focused control boundaries remain visible; no stale-state opacity reduces essential text below target. Owner: Theme first, then consumer exceptions. Suggested Impeccable commands: colorize, audit.

DS-02 · P1 · TechField does not connect labels or errors to its control

Evidence: Components/TechField.razor:3–7 renders a sibling <label> without for; hint and error have no IDs. ChildContent is outside the label. Callers such as Secrets' SecretEditor.razor:13–43 provide controls without their own accessible names.

Recommendation: add a documented For/control-ID contract and stable hint/error IDs; consumers set id, aria-describedby, and aria-invalid. If a component API generates the control, pass those attributes through explicitly. Do not assume a visual label labels arbitrary ChildContent.

Acceptance: clicking each label focuses the input; accessibility tree has the intended name and description; field errors announce once and preserve values. Owner: Theme API + callers. Suggested commands: harden, clarify.

DS-03 · P2 · Define the complete accent family, not only --accent

Evidence: Components/ThemeShell.razor:8 and its AccentStyle expression override only --accent; theme.css:50–51, :83–90, and layout.css:228–235 keep independently defined blue deep/tint values. An app may intentionally use a green or purple brand with blue hover/active states today.

Recommendation: supply a named accent configuration with deep, tint, border, and focus values; preserve existing product hues. Keep information-state blue separate if that is intentional. Avoid duplicating the whole palette in every app stylesheet.

Acceptance: primary buttons, links, active nav, hover and focus form one intentional accent family; status meaning stays unchanged. Owner: Theme; consumer accent selection remains local. Suggested commands: extract, colorize.

DS-04 · P2 · Complete the shared keyboard and state contract

Evidence: Components/TechButton.razor:3–5 disables while busy and hides its spinner from assistive technology but offers no built-in announcement or aria-busy. The CSS has a focused tree twist (layout.css:440) but no kit-wide :focus-visible rule. theme.css:171, :227–228 supplies pulse/reveal animations without a reduced-motion branch. Bootstrap/browser defaults may supply focus for some controls; lack of a kit rule is not proof every control has invisible focus.

Recommendation: define shared focus styling for links, disclosure summaries and controls; support a contextual busy label and appropriately scoped live status. Under reduced motion retain the final visible state and a static “connecting” label. Treat busy, failure, and successful completion as separate outcomes.

Acceptance: keyboard-only traversal through each family screen shows focus; labels communicate pending/completed/error without relying on animation; reduced-motion content is visible immediately; announcements do not repeat every polling tick. Owner: Theme + application state. Suggested commands: harden, animate.

DS-05 · P2 · Standardize interaction recipes before extracting domain widgets

Evidence: Theme owns table styling (theme.css:338–371), but .sortable is a visual cursor treatment; it cannot supply a keyboard button or aria-sort. Theme has no modal component. Multiple independent app overlays and search toolbars were found by project reviews.

Recommendation: first document recipes for a labeled filter bar, scrollable table region, sortable header button, status summary, error/empty state, and accessible confirmation. Extract only proven generic markup and behavior; keep domain trees, pipelines, protocol forms and deployment logic in their repositories. Preserve SSR form POST for LoginCard and interactive-host requirements for TreeTable.

Acceptance: two different consumers can use each recipe with equivalent keyboard/state behavior; sorting is an actual focusable action; opening a modal never leaves focus behind the overlay. Owner: Theme recipes + local adapters. Suggested commands: extract, harden, adapt.

DS-06 · P2 · Govern package adoption and supported color schemes

Evidence: Theme source is 0.5.3, Overview and several consumers pin 0.5.0, while ScadaBridge has 0.5.3 and its own dark tokens. Current Theme has a light :root palette and no complete shared dark contract. Historical adoption documents conflict with newer source documentation.

Recommendation: publish reviewed shared fixes as a new version; record each consumer's installed version, optional accent and scheme support. Treat a family dark theme as an explicit shared deliverable. Until then avoid declaring dark support from one local override. Update the obsolete adoption matrices as a separate documentation task.

Acceptance: all consumer pins and asset paths are verified against the chosen package; desktop/mobile screenshots and focus/state checks pass before rollout; no consumer silently falls back to a second Plex copy or old tokens. Owner: Theme maintainer and each application owner. Suggested commands: document, audit.

  1. Theme: DS-01 and DS-02; review the token/API compatibility policy before versioning. Add meaningful contrast-pair and rendered label-association checks.
  2. Shared UI: Secrets field callers and confirmation behavior; ship once for all hosts.
  3. Each consumer: adopt the chosen package; remove only equivalent copied rules. Preserve app-specific shape, editors and semantic distinctions.
  4. Local P1 work: misleading successful/empty states, modal access, field labels and timestamp interpretation. Project reports identify exact locations.
  5. Local P2 work: filter/table hierarchy, responsive stacking, role-aware navigation, progressive detail.
  6. Validate a representative route from every family at 1440px and 390px, 200% zoom, keyboard, reduced motion, error/empty/loading, and each supported scheme. Then run Impeccable audit and finish with polish.

No live runtime accessibility/performance score is assigned here. Source inspection supports concrete findings but cannot establish complete WCAG conformance, rendered overflow, interaction timing, backend recovery, or performance budgets. Mockup verification is recorded separately and applies only to the review artifacts.