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
+20 -7
View File
@@ -6,8 +6,7 @@ human-readable index of the Technical-Light design system. The authoritative sou
for the auth component.
The canonical token block lives in `:root`. Components reference these tokens —
**no hardcoded hex values** appear in component markup or CSS. The only per-app override
is `--accent` on the `ThemeShell` root element via the `Accent` parameter.
**no hardcoded hex values** appear in component markup or CSS. Product overrides are scoped to the `ThemeShell` subtree through the complete accent parameter family. Semantic status/info tokens remain shared.
---
@@ -45,10 +44,23 @@ is `--accent` on the `ThemeShell` root element via the `Accent` parameter.
|---|---|---|
| `--accent` | `#2f5fd0` | Links, sort arrows, primary actions, active nav indicator |
| `--accent-deep` | `#1e3f99` | Hover / pressed accent; raw-value emphasis |
| `--accent-tint` | `#eef2fc` | Selected surface |
| `--accent-border` | `#cdd9f7` | Subtle interactive border |
| `--accent-focus` | `#1e3f99` | Keyboard focus |
| `--on-accent` | `#ffffff` | Primary action label |
| `--active-bg` | `var(--accent-tint)` | Compatibility alias, rebound on `.app-shell` |
> `--accent` is the **only token overridden per-app**. Pass it as `ThemeShell`'s
> `Accent` parameter: `<ThemeShell Accent="#2f855a">` → emits
> `style="--accent: #2f855a"` on the shell root, scoping the override to that subtree.
Use `Accent`, `AccentDeep`, `AccentTint`, `AccentBorder`, and `AccentFocus` together
for a product color family. Existing Accent-only callers still work; omitted values inherit.
Approved caller values must be trusted authored configuration. No inline style is emitted
when all five parameters are absent. Root semantic info stays blue through `--info-ink`.
Bootstrap `.btn-primary` and `.btn-link` bind component variables to this subtree's tokens.
Links and ghost text use the deep accent: green/teal primary colors need white labels
and fall below 4.5:1 as small text on warm paper. See the release decision for values.
Do not duplicate sizing or override group seams. Active links consume `--accent-tint`
directly, avoiding the root custom-property alias resolution trap. Actual hover, pressed,
focus and disabled styles still require the package canary browser checks.
---
@@ -129,8 +141,9 @@ inherit the Technical-Light aesthetic. They are **harmless if Bootstrap is absen
1. **Never hand-pick hex values in feature CSS.** Use the tokens above or the utility
classes (`.s-ok`, `.s-warn`, `.s-bad`, `.s-idle`, `.chip-*`, `.kv .v.*`).
2. **One per-app override only.** Override `--accent` via `ThemeShell`'s `Accent`
parameter. Do not override other tokens per-app.
2. **One complete per-app accent family.** Use the five `ThemeShell` accent parameters.
Keep semantic status/info tokens uniform. Explicit supported dark schemes own their
readable aliases and require separate verification.
3. **Status has text as well as color.** Use semantic inks for labels and values; retain
signal colors for dots/stripes/charts. Use `StatusPill` for labeled chips and `.s-*`
utility classes for inline text. Do not rely on color alone.
@@ -0,0 +1,153 @@
# Shared interaction recipes
These patterns accompany the 1.0.0 Theme candidate. The host owns domain state,
authorization, validation, sorting, filtering and asynchronous outcomes. Examples are
local adapters, not new generic Theme components. Preserve supported SSR login POST,
antiforgery and safe return URL behavior.
## Label a filter and give it a clear action
```razor
<label for="instance-filter" class="form-label">Filter instances</label>
<div class="d-flex gap-2">
<input id="instance-filter" class="form-control" type="search"
@bind="Filter" @bind:event="oninput" aria-controls="instance-results" />
<TechButton Variant="ButtonVariant.Secondary" @onclick="Clear"
disabled="@(Filter.Length == 0)">Clear filter</TechButton>
</div>
<p id="instance-count" role="status">@Visible.Count matching instances</p>
<ul id="instance-results" aria-describedby="instance-count">
@foreach (var name in Visible) { <li @key="name">@name</li> }
</ul>
@code {
private string Filter = "";
private readonly string[] Names = ["Fixture A", "Fixture B"];
private List<string> Visible => Names.Where(n =>
n.Contains(Filter, StringComparison.OrdinalIgnoreCase)).ToList();
private void Clear() => Filter = "";
}
```
The names above are illustrative fixture data. Each actual page filters its displayed
dataset, preserves selection by stable identity, and explains if search covers only
loaded branches. Announce user-requested count changes politely; do not put all polling
values in a live region. Placeholder text supplements a visible label.
## Keep tables semantic and locally scrollable
```razor
<div class="table-wrap" role="region" aria-label="Instance observations" tabindex="0">
<table class="data-table">
<caption>Latest observations, timestamps in UTC</caption>
<thead><tr>
<th scope="col">Instance</th>
<th scope="col" aria-sort="@(_ascending ? "ascending" : "descending")">
<button type="button" @onclick="ToggleSort">Updated (UTC)</button>
</th>
<th scope="col">Details</th>
</tr></thead>
<tbody>
@foreach (var row in Ordered)
{
<tr @key="row.Id">
<th scope="row">@row.Name</th>
<td class="mono">@row.UpdatedUtc.ToString("yyyy-MM-dd HH:mm:ss 'UTC'",
System.Globalization.CultureInfo.InvariantCulture)</td>
<td><button type="button" aria-expanded="@(_expanded.Contains(row.Id) ? "true" : "false")"
aria-controls="@($"detail-{row.Id}")" @onclick="() => Toggle(row.Id)">
@(_expanded.Contains(row.Id) ? "Hide" : "Show") details for @row.Name
</button></td>
</tr>
<tr id="@($"detail-{row.Id}")" hidden="@(!_expanded.Contains(row.Id))">
<td colspan="3">@row.Detail</td>
</tr>
}
</tbody>
</table>
</div>
@code {
private sealed record Observation(int Id, string Name, DateTimeOffset UpdatedUtc, string Detail);
private readonly List<Observation> _rows = [];
private readonly HashSet<int> _expanded = [];
private bool _ascending = true;
private IEnumerable<Observation> Ordered => _ascending
? _rows.OrderBy(r => r.UpdatedUtc).ThenBy(r => r.Id)
: _rows.OrderByDescending(r => r.UpdatedUtc).ThenBy(r => r.Id);
private void ToggleSort() => _ascending = !_ascending;
private void Toggle(int id) { if (!_expanded.Add(id)) _expanded.Remove(id); }
}
```
A sort cursor alone does not sort. Use a real button and update the displayed order;
keep `aria-sort` on the applicable header. Retain precision required by the domain
(BTDB uses seven fractional digits) rather than copying the illustrative format above.
Disclosure is a keyboard-operable button, not a clickable row; its expanded state and
controlled region must agree. TreeTable remains caller-owned and stateless. Give each
scroll region a meaningful name and visible focus; document width stays bounded while
tables scroll inside it. Long identifiers wrap in cells unless precision demands a
horizontal pane. Keep action names contextual and preserve role gates.
## Distinguish empty, failed, pending and stale
- **Initial load:** say what is loading; show a stable layout and skeleton where useful.
- **No data:** explain what the user can create or connect, subject to authorization.
- **No matches:** state that the filter excluded results and provide Clear filter.
- **Failed request:** name the failed operation and a valid Retry action; do not report
success, zero results or healthy status from an absent observation.
- **Stale observation:** retain the last known data, label it stale, show its observed
UTC timestamp and age, and distinguish observation age from current reachability.
- **Pending observation:** display Pending/Unknown explicitly; do not infer Offline.
Render a persistent inline status region for user-initiated operation outcomes. Put a
validation summary near the form and associate errors with their inputs through
TechField's For/HintId/ErrorId contract. Use `aria-invalid` only when invalid. The form
owns focus on the first relevant invalid control after submission. Keep status labels
readable and textual alongside optional signal dots; color alone is insufficient.
Never announce secret values, every background refresh or every connection heartbeat.
## Busy actions and safe confirmation
A busy TechButton shows `BusyText` and `aria-busy`, keeps caller-disabled semantics,
and restores its ordinary label afterward. The host publishes success/failure in its
separate outcome region and keeps recovery available. Preserve focus after completion;
a disabled action is not a replacement for explaining why the user cannot proceed.
Use confirmation only for work that warrants interruption and protected focus. For
ordinary editing prefer inline controls or a dedicated page. Reuse the host's existing
strong dialog implementation; there is no generic Theme modal in this release.
A conforming dialog adapter must:
1. Capture the connected trigger before opening. Associate a visible heading and
description through `aria-labelledby`/`aria-describedby`, and use modal semantics.
2. Mount outside transformed/animated clipping ancestors. Lock background interaction
(inert) and scroll while maintaining an intentional nested-overlay policy.
3. Move focus to the safe action or relevant initial control. Bind a native DOM keydown
listener to the actual event. Tab/Shift+Tab stay within visible, enabled, non-inert
controls; call `preventDefault()` synchronously at boundaries. With no focusable
child, focus the dialog container. Never read `window.event` after async interop.
4. Escape closes only when safe. During irreversible/busy work, follow the operation's
explicit cancellation rules; do not imply that closing cancels server work.
5. Remove listeners/inert/scroll locks on close and disposal. Restore focus once to a
still-connected trigger, or a stable page heading when it disappeared. Do not keep
one global saved element for independently nested dialogs.
6. Verify with real keyboard input: forward/backward boundaries, hidden/disabled
controls, Escape, failed request, busy-close rules and disconnected-trigger fallback.
Native `dialog` is an option after the host/browser suitability check; its presence alone
is not proof of lifecycle correctness. A reusable extraction decision waits for two
successful consumer pilots (G2), with browser contract tests in both host modes.
## Focus, motion and viewport acceptance
Focus must be visibly distinct from selection across all approved accent families,
including scroll regions and custom controls. Preserve stronger specialized focus
rules. Reduced-motion users see `.rise` content in its final state immediately and a
stable connection signal; text still communicates the state. Do not globally force
all animations to 0.01ms.
Verify desktop 1440×900, tablet 1024×768, phone 390×844, actual browser 200% zoom,
keyboard and reduced motion in one bounded inspection round, then one confirmation
round after fixes. Check mobile navigation open and closed, local table scrolling,
reachable actions and the supported dark scheme. Screenshot and token math do not
replace actual computed styles, DOM focus movement and user interactions.
+17 -17
View File
@@ -1,9 +1,9 @@
# UI Theme — normalized target spec
Status: **Draft**. The single design the sister projects converge on. Derived from the
three code-verified current-state docs (`../current-state/`). Goal is *path to shared
code* (`../shared-contract/ZB.MOM.WW.Theme.md`), so each normalized section maps to a
shared library seam.
Status: **Implemented shared system; 1.0.0 accessible candidate in validation**.
Current published version remains 0.5.3 until the release gate closes. Original
current-state documents retain historical evidence. Actual source pins, version policy
and rollout state are in [release decision](../RELEASE-DECISION.md) and the execution ledger.
## 0. Scope
@@ -14,8 +14,7 @@ common controls); delivery via the `ZB.MOM.WW.Theme` RCL.
**Explicitly NOT normalized** (domain-specific — keep per project): each app's `site.css`
residual page layout, route/page content, and app-specific scoped `.razor.css` files.
The kit owns the *chrome and tokens*, not the app's domain screens. Authorization logic
and interactive nav-state persistence (e.g. OtOpcUa's cookie-persisted rail sections)
are also per-project.
remain per-project. Shared nav-section persistence belongs to `ThemeScripts`/`nav-state.js`.
---
@@ -26,9 +25,9 @@ declared on `:root` in `theme.css`. Components carry **no hardcoded hex values**
everything references these tokens. Bootstrap 5 `--bs-*` variables are overridden to
align Bootstrap's defaults with the Technical-Light palette.
The **one per-app override** allowed is `--accent` on the `ThemeShell` root element
(passed via the `Accent` parameter), giving each app a distinct primary color while
sharing all other tokens.
Per-app accents use `Accent`, `AccentDeep`, `AccentTint`, `AccentBorder` and
`AccentFocus` on the shell subtree. Semantic status and informational colors stay
shared. Supported dark schemes require separately verified readable aliases.
See [`DESIGN-TOKENS.md`](DESIGN-TOKENS.md) for the full enumeration.
@@ -36,8 +35,8 @@ See [`DESIGN-TOKENS.md`](DESIGN-TOKENS.md) for the full enumeration.
- **Surface** — `--paper`, `--card`
- **Ink (text)** — `--ink`, `--ink-soft`, `--ink-faint`
- **Structure** — `--rule`, `--rule-strong`
- **Accent** — `--accent`, `--accent-deep`
- **Status** — `--ok`, `--warn`, `--bad`, `--idle` (+ `-bg` variants)
- **Accent** — `--accent`, `--accent-deep`, `--accent-tint`, `--accent-border`, `--accent-focus`, `--on-accent`
- **Status** — signal `--ok`/`--warn`/`--bad`/`--idle`, matching `-ink` text and `-bg` surfaces; independent `--info-ink`/`--info-bg`
- **Typography** — `--sans` (IBM Plex Sans), `--mono` (IBM Plex Mono)
- **Bootstrap overrides** — `--bs-body-bg`, `--bs-body-color`, `--bs-body-font-family`,
`--bs-body-font-size`, `--bs-primary`, `--bs-border-color`, `--bs-emphasis-color`
@@ -109,7 +108,7 @@ no inline colors. One `@using ZB.MOM.WW.Theme` covers every component and enum.
| Component / Type | Key parameters | Notes |
|---|---|---|
| `ThemeShell` | `Product`*, `Accent`, `Logo`, `Nav`, `RailFooter`, `ChildContent` | Canonical side-rail chassis. Not a `LayoutComponentBase` — delegated to from `MainLayout`. `Accent` overrides `--accent` for the shell subtree. |
| `ThemeShell` | `Product`*, `Accent`, `AccentDeep`, `AccentTint`, `AccentBorder`, `AccentFocus`, `ScrollNav`, `Logo`, `Nav`, `RailFooter`, `ChildContent` | Canonical side-rail chassis. Not a `LayoutComponentBase` — delegated to from `MainLayout`. `Accent` overrides `--accent` for the shell subtree. |
| `BrandBar` | `Product`*, `Logo` | Brand glyph + product name; rendered in the rail header inside `ThemeShell`. |
| `NavRailItem` | `Href`*, `Text`*, `Icon`, `Match` | Wraps `<NavLink class="rail-link">`. Active state via Blazor `NavLink`. |
| `NavRailSection` | `Title`*, `Expanded` (default `true`), `ChildContent` | CSS-only `<details>` collapsible group; no JS, works in static SSR. |
@@ -137,20 +136,21 @@ no inline colors. One `@using ZB.MOM.WW.Theme` covers every component and enum.
|---|---|---|
| `StatusPill` | `State`* (`StatusState`), `ChildContent` | Inline chip. `StatusState` enum: `Ok`, `Warn`, `Bad`, `Idle`, `Info`. Maps state → token class (`chip-ok`, …). |
| `LoginCard` | `Product`*, `Action` (default `/auth/login`), `ReturnUrl`, `Error`, `ChildContent` | Static form-POST sign-in card. `ChildContent` for `<AntiforgeryToken/>`. Validate `ReturnUrl` server-side (open-redirect risk). |
| `TechButton` | `Variant` (`ButtonVariant`), `Type`, `Busy`, `ChildContent`, splatted attrs | `ButtonVariant` enum: `Primary`, `Secondary`, `Danger`, `Ghost`. `Busy` disables + shows spinner. |
| `TechButton` | `Variant` (`ButtonVariant`), `Size`, `Class`, `Type`, `Busy`, `BusyText`, `ChildContent`, splatted attrs | `ButtonVariant` enum: `Primary`, `Secondary`, `Danger`, `Ghost`. `Busy` disables + shows a decorative spinner and optional BusyText; exposes aria-busy. Caller owns the outcome region. |
| `TechCard` | `Title`, `Header`, `ChildContent`, `Footer`, `Class` | Panel with optional head/body/footer slots. |
| `TechField` | `Label`*, `Hint`, `Error`, `ChildContent` | Labeled input wrapper with hint text and inline error. |
| `TechField` | `Label`*, `For`, `Hint`, `HintId`, `Error`, `ErrorId`, `ChildContent` | Label/hint/error association wrapper. Caller owns input id, aria-describedby and aria-invalid. |
\* `EditorRequired` parameter.
**Deliberately NOT included** (YAGNI / stays per-project): data grids, tree views,
multi-select dropdowns, modals, toasts, audit components, page-specific layouts.
**Deliberately NOT included** (YAGNI / stays per-project): domain grids/tree data, multi-select dropdowns, modals, toasts, audit components and
page-specific layouts. The existing stateless TreeTable renders caller-owned rows; it
does not own data loading/filtering. Shared interaction recipes apply without a speculative modal API.
---
## 5. Delivery
The RCL ships as the single NuGet package `ZB.MOM.WW.Theme` (`.NET 10`, `Version 0.1.0`).
The RCL ships as the single NuGet package `ZB.MOM.WW.Theme` (`.NET 10`). Published version is 0.5.3; the 1.0.0 candidate waits for package and browser acceptance.
**Static assets** are served at `_content/ZB.MOM.WW.Theme/…` by ASP.NET's static-web-asset
pipeline: