feat(theme): implement accessible Technical-Light 1.0 contracts
This commit is contained in:
@@ -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.
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user