docs(audit): apply per-cluster judgment fixes across living docs
Resolve audit findings: correct WorkerEnvelope proto/route/metric/session facts; rewrite auth (ZB.MOM.WW.Auth migration), dashboard (ZB.MOM.WW.Theme), and StyleGuide (foreign-project copy-paste); document alarm subsystem, Ldap options, and gateway alarm broker; fix client CLI flags and package paths.
This commit is contained in:
Joseph Doherty
@@ -8,8 +8,12 @@ operations-focused projects.
|
||||
|
||||
The dashboard is an operational interface, not a landing page. It prioritizes
|
||||
fast scanning, low visual noise, and stable layouts while live data changes.
|
||||
The design uses Bootstrap for common behavior and a small local stylesheet for
|
||||
project identity, spacing, and status presentation.
|
||||
The layout chrome, status presentation, and design tokens come from the shared
|
||||
`ZB.MOM.WW.Theme` kit (the technical-light design system). Bootstrap supplies
|
||||
common widget behavior, and a small local stylesheet (`wwwroot/css/site.css`)
|
||||
wires the dashboard's own class names and Bootstrap widgets onto the kit's
|
||||
tokens. The local sheet contains no hard-coded colors; every color, font, and
|
||||
surface resolves to a theme token.
|
||||
|
||||
Use this style for applications where users repeatedly check system state,
|
||||
compare rows, inspect details, and diagnose faults. Avoid promotional layouts,
|
||||
@@ -25,7 +29,7 @@ The interface uses a quiet, work-focused visual system:
|
||||
- White cards and sections carry the actual operational content.
|
||||
- Borders define structure more often than shadows.
|
||||
- Accent color is reserved for metric values and important numeric signals.
|
||||
- Bootstrap status badges provide state color without custom status art.
|
||||
- The kit's `StatusPill` provides state color without custom status art.
|
||||
- Tables remain compact and responsive so long identifiers and timestamps stay
|
||||
readable.
|
||||
|
||||
@@ -34,93 +38,113 @@ and dense enough for repeated use.
|
||||
|
||||
## Layout Structure
|
||||
|
||||
Every page follows the same structure:
|
||||
The application chassis is the kit's `ThemeShell` component (a vertical side
|
||||
rail plus a content area), not a horizontal top navbar. `MainLayout.razor` is a
|
||||
thin wrapper that delegates the rail chassis — brand block, hamburger toggle,
|
||||
responsive collapse — to `<ThemeShell>` and supplies only the navigation items
|
||||
and a rail footer:
|
||||
|
||||
1. A top navigation bar with the product or service name on the left.
|
||||
2. A full-width `container-fluid` content area.
|
||||
3. A page header with the page title, short context text, and optional status
|
||||
badge.
|
||||
4. Metric cards when a page has top-level numeric state.
|
||||
5. Bordered content sections for tables, details, faults, or empty states.
|
||||
|
||||
The shell does not use a sidebar. A horizontal navigation bar is enough for the
|
||||
current page count and keeps the content width available for tables.
|
||||
|
||||
```html
|
||||
<div class="dashboard-shell">
|
||||
<nav class="navbar navbar-expand-lg bg-body border-bottom dashboard-navbar">
|
||||
<!-- brand, page links, sign-out action -->
|
||||
</nav>
|
||||
<main class="container-fluid dashboard-content">
|
||||
<!-- page header, metric grid, sections -->
|
||||
</main>
|
||||
</div>
|
||||
```razor
|
||||
<ThemeShell Product="MXAccess Gateway" Accent="#2f5fd0">
|
||||
<Nav>
|
||||
<NavRailItem Href="/" Text="Dashboard" Match="NavLinkMatch.All" />
|
||||
<NavRailSection Title="Runtime" Key="runtime">
|
||||
<NavRailItem Href="/sessions" Text="Sessions" />
|
||||
<NavRailItem Href="/workers" Text="Workers" />
|
||||
</NavRailSection>
|
||||
</Nav>
|
||||
<RailFooter><!-- user name + sign-out --></RailFooter>
|
||||
<ChildContent>@Body</ChildContent>
|
||||
</ThemeShell>
|
||||
```
|
||||
|
||||
Within the content area, every page follows the same structure:
|
||||
|
||||
1. A page header with the page title, short context text, and optional status
|
||||
pill.
|
||||
2. Metric cards when a page has top-level numeric state.
|
||||
3. Bordered content sections for tables, details, faults, or empty states.
|
||||
|
||||
The login page uses `LoginLayout.razor` instead — a minimal layout with no rail
|
||||
and no brand block, because the page renders its own centered `<LoginCard>`.
|
||||
|
||||
## Color Tokens
|
||||
|
||||
Use a small token set and let Bootstrap provide the rest. The current dashboard
|
||||
uses these local tokens:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--mxgw-surface: #f7f8fa;
|
||||
--mxgw-border: #d8dee6;
|
||||
--mxgw-ink-muted: #667085;
|
||||
--mxgw-accent: #146c64;
|
||||
}
|
||||
```
|
||||
Colors come from the `ZB.MOM.WW.Theme` kit's `theme.css`. The local
|
||||
`site.css` defines no `:root` custom properties of its own; it references kit
|
||||
tokens by name. The dashboard does not define a `--mxgw-*` token set.
|
||||
|
||||
| Token | Purpose |
|
||||
|-------|---------|
|
||||
| `--mxgw-surface` | Page background behind all content. |
|
||||
| `--mxgw-border` | Borders on cards, tables, sections, and empty states. |
|
||||
| `--mxgw-ink-muted` | Secondary labels, details, and empty-state text. |
|
||||
| `--mxgw-accent` | Metric values and important numeric summaries. |
|
||||
| `var(--card)` | Background of cards, sections, and data tables. |
|
||||
| `var(--rule)`, `var(--rule-strong)` | Hairline and stronger borders. |
|
||||
| `var(--ink)`, `var(--ink-soft)`, `var(--ink-faint)` | Primary, secondary, and muted text. |
|
||||
| `var(--accent)`, `var(--accent-deep)` | Metric values, links, primary buttons, focus rings. |
|
||||
| `var(--mono)` | Monospace family for values, identifiers, and code. |
|
||||
| `var(--ok)`/`--ok-bg`, `var(--warn)`/`--warn-bg`, `var(--bad)`/`--bad-bg`, `var(--idle)`/`--idle-bg` | State colors for chips, alerts, and alarm-state labels. |
|
||||
|
||||
Keep the palette small. Add new colors only when they encode state or improve
|
||||
readability. Prefer Bootstrap badge classes for states such as ready, closing,
|
||||
closed, and faulted.
|
||||
Keep the palette small and let the kit own it. Add new colors only when they
|
||||
encode state or improve readability, and resolve them to a kit token rather than
|
||||
a literal hex value. Use the kit's `StatusPill` for states such as ready,
|
||||
closing, idle, and faulted.
|
||||
|
||||
## Typography
|
||||
|
||||
Typography stays compact and consistent:
|
||||
|
||||
- Page headings use `1.35rem`, weight `650`, and normal letter spacing.
|
||||
- Section headings use the same size as page headings when they introduce a
|
||||
table or details group.
|
||||
- Metric labels use uppercase text at `.78rem` and weight `650`.
|
||||
- Metric values use `1.7rem`, weight `700`, and the accent color.
|
||||
- Page headings (`.dashboard-page-header h1`) use `1.15rem`, weight `600`, and a
|
||||
slight letter spacing.
|
||||
- Section headings (`.section-heading h2`) use a small uppercase eyebrow:
|
||||
`.74rem`, weight `600`, muted ink.
|
||||
- Metric labels (`.agg-label`) use uppercase text at `.68rem` and weight `600`,
|
||||
muted ink.
|
||||
- Metric values (`.agg-value`) use `1.5rem`, weight `600`, the monospace family,
|
||||
tabular numerics, and primary ink (`var(--ink)`).
|
||||
- Body and table text inherit Bootstrap defaults for readability.
|
||||
|
||||
Do not scale text with viewport width. Long values use `overflow-wrap:
|
||||
anywhere` so session IDs, paths, and fault messages do not break the layout.
|
||||
break-word` (numbers and date tokens stay whole, wrapping only at spaces); a few
|
||||
free-form fields such as `.agg-sub` use `overflow-wrap: anywhere` so session
|
||||
IDs, paths, and fault messages do not break the layout.
|
||||
|
||||
## Spacing And Shape
|
||||
|
||||
The dashboard uses modest spacing:
|
||||
|
||||
- Page content has `1.25rem` padding on desktop and `.75rem` on small screens.
|
||||
- The kit owns the rail and content padding; the local small-screen rule sets
|
||||
`.page` padding to `.85rem`.
|
||||
- Metric grids use `.75rem` gaps.
|
||||
- Content sections start with a top border and `1rem` top padding.
|
||||
- Cards and empty states use Bootstrap's small radius shape, `.375rem`.
|
||||
- Metric cards have no shadow.
|
||||
- Content sections (`.dashboard-section`) and metric cards (`.agg-card`) are
|
||||
fully bordered cards: `var(--card)` fill, a `1px solid var(--rule)` hairline,
|
||||
and `0.9rem` padding for sections.
|
||||
- Cards, sections, and modals use an `8px` radius; smaller widgets such as the
|
||||
empty state use `6px`.
|
||||
- Metric cards have no shadow (`box-shadow: none`); borders define structure.
|
||||
|
||||
This keeps information grouped without turning each section into a decorative
|
||||
panel. Use cards for repeated metric summaries, login forms, and individual
|
||||
items. Use unframed sections with a top border for page-level groups.
|
||||
items. Use bordered sections for page-level groups.
|
||||
|
||||
## Navigation
|
||||
|
||||
Navigation is a Bootstrap responsive navbar. It includes:
|
||||
Navigation lives in the `ThemeShell` side rail. It is built from the kit's
|
||||
`NavRailSection` and `NavRailItem` components: a single home item plus eight
|
||||
page items grouped into three labeled sections.
|
||||
|
||||
- Brand text for the service name.
|
||||
- Short page labels: `Overview`, `Sessions`, `Workers`, `Events`, `Settings`.
|
||||
- Active route styling through `NavLink`.
|
||||
- A right-aligned sign-out button when authentication is enabled.
|
||||
| Section | Items |
|
||||
|---------|-------|
|
||||
| (home) | `Dashboard` (route `/`, `NavLinkMatch.All`) |
|
||||
| Runtime | `Sessions`, `Workers`, `Events`, `Alarms` |
|
||||
| Galaxy | `Repository`, `Browse` |
|
||||
| Admin | `API Keys`, `Settings` |
|
||||
|
||||
Keep navigation labels short. Operational users should be able to predict what
|
||||
each page contains without reading explanatory copy.
|
||||
Section expand/collapse state is owned by the kit (a `<details>` element plus
|
||||
`ThemeScripts`); the layout does not run JS interop for it. The rail footer
|
||||
shows the signed-in user name and a sign-out form (or a sign-in link when
|
||||
unauthenticated).
|
||||
|
||||
Keep navigation labels short and group related pages. Operational users should
|
||||
be able to predict what each page contains without reading explanatory copy.
|
||||
|
||||
## Page Headers
|
||||
|
||||
@@ -128,42 +152,43 @@ Each page starts with a `dashboard-page-header`:
|
||||
|
||||
- The title is the primary anchor.
|
||||
- A single secondary line gives timestamp, row count, or configuration context.
|
||||
- A status badge appears on the right when the page has an overall state.
|
||||
- A status pill appears on the right when the page has an overall state.
|
||||
|
||||
On narrow screens, the header stacks vertically. This prevents long context
|
||||
text or status badges from overlapping the title.
|
||||
text or status pills from overlapping the title.
|
||||
|
||||
```html
|
||||
<div class="dashboard-page-header">
|
||||
<div>
|
||||
<h1>Overview</h1>
|
||||
<h1>Dashboard</h1>
|
||||
<div class="text-secondary">Generated 2026-04-27 17:30:00</div>
|
||||
</div>
|
||||
<span class="badge text-bg-success">Healthy</span>
|
||||
<!-- <StatusBadge Text="Healthy" /> -> kit <StatusPill State="Ok"> -->
|
||||
</div>
|
||||
```
|
||||
|
||||
## Metric Cards
|
||||
|
||||
Metric cards summarize numeric state at the top of overview and diagnostic
|
||||
pages. They use Bootstrap cards with a local `metric-card` class:
|
||||
Metric cards summarize numeric state at the top of the home and diagnostic
|
||||
pages. The `MetricCard` component renders an `.agg-card` with label, value, and
|
||||
optional sub-line:
|
||||
|
||||
- Label: uppercase, muted, compact.
|
||||
- Value: large enough to scan, accent colored, wraps safely.
|
||||
- Detail: optional muted text for version, rate context, or explanatory state.
|
||||
- Label (`.agg-label`): uppercase eyebrow, muted, compact.
|
||||
- Value (`.agg-value`): large monospace number in primary ink, wraps safely.
|
||||
- Sub (`.agg-sub`): optional muted text for version, rate context, or state.
|
||||
|
||||
Use auto-fit CSS grid tracks so the cards fill available width without custom
|
||||
breakpoints:
|
||||
Cards lay out in a `.metric-grid`. Use auto-fill CSS grid tracks so they fill
|
||||
available width without custom breakpoints:
|
||||
|
||||
```css
|
||||
.metric-grid {
|
||||
display: grid;
|
||||
gap: .75rem;
|
||||
grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
|
||||
grid-template-columns: repeat(auto-fill, minmax(11rem, 1fr));
|
||||
}
|
||||
|
||||
.metric-grid.compact {
|
||||
grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
|
||||
grid-template-columns: repeat(auto-fill, minmax(10rem, 1fr));
|
||||
}
|
||||
```
|
||||
|
||||
@@ -188,15 +213,22 @@ entire rows clickable when a single identifier link is clearer.
|
||||
|
||||
## Status Badges
|
||||
|
||||
Status uses Bootstrap badge classes with a small mapping layer:
|
||||
`StatusBadge` is a thin adapter over the kit's `StatusPill`. Call sites pass the
|
||||
literal domain state text (`<StatusBadge Text="Ready" />`); the adapter maps
|
||||
that text to one of the kit's four `StatusState` values, and `StatusPill`
|
||||
renders the chip. There are no Bootstrap `text-bg-*` classes in this layer.
|
||||
|
||||
| State | Badge class |
|
||||
|-------|-------------|
|
||||
| `Ready`, `Healthy` | `text-bg-success` |
|
||||
| `Creating`, `StartingWorker`, `WaitingForPipe`, `InitializingWorker`, `Closing` | `text-bg-info` |
|
||||
| `Closed` | `text-bg-secondary` |
|
||||
| `Faulted` | `text-bg-danger` |
|
||||
| Unknown state | `text-bg-light text-dark border` |
|
||||
| Domain state text | `StatusState` |
|
||||
|-------------------|---------------|
|
||||
| `Ready`, `Healthy`, `Active` | `Ok` |
|
||||
| `Creating`, `StartingWorker`, `WaitingForPipe`, `InitializingWorker`, `Closing`, `Stale`, `Degraded` | `Warn` |
|
||||
| `Faulted`, `Unavailable` | `Bad` |
|
||||
| Any other text (including `Closed`, `Revoked`, `Unknown`) | `Idle` |
|
||||
|
||||
Note the mapping changes from earlier revisions: `Closed` now falls through to
|
||||
`Idle` (rather than its own neutral badge), and `Active`, `Stale`, `Degraded`,
|
||||
and `Unavailable` are explicit cases. The kit owns the chip rendering; only this
|
||||
domain text-to-state vocabulary lives in the app.
|
||||
|
||||
Keep status text literal. Operators benefit from seeing the same state names
|
||||
that appear in logs and APIs.
|
||||
@@ -230,8 +262,8 @@ The dashboard uses one small-screen breakpoint:
|
||||
|
||||
```css
|
||||
@media (max-width: 700px) {
|
||||
.dashboard-content {
|
||||
padding: .75rem;
|
||||
.page {
|
||||
padding: .85rem;
|
||||
}
|
||||
|
||||
.dashboard-page-header {
|
||||
@@ -245,6 +277,9 @@ The dashboard uses one small-screen breakpoint:
|
||||
}
|
||||
```
|
||||
|
||||
A second breakpoint (`max-width: 960px`) collapses the Browse two-pane layout
|
||||
(`.browse-layout`) to a single column.
|
||||
|
||||
Do not hide important columns by default. Use horizontal table scrolling for
|
||||
dense operational data, and reserve column hiding for data that is clearly
|
||||
duplicative.
|
||||
@@ -277,13 +312,14 @@ markup.
|
||||
|
||||
Use this checklist when applying the design to another project:
|
||||
|
||||
- Define four local tokens: surface, border, muted ink, and accent.
|
||||
- Use a Bootstrap top navbar with short route labels.
|
||||
- Keep page content inside a full-width fluid container.
|
||||
- Take colors, fonts, and surfaces from the `ZB.MOM.WW.Theme` kit tokens; do
|
||||
not define a local color token set.
|
||||
- Use the kit's `ThemeShell` side rail with `NavRailSection`/`NavRailItem` and
|
||||
short route labels grouped into sections.
|
||||
- Start every page with the same header structure.
|
||||
- Put primary numeric state in `metric-grid` cards.
|
||||
- Put primary numeric state in `metric-grid` / `agg-card` cards.
|
||||
- Put detailed runtime state in compact responsive tables.
|
||||
- Use status badges mapped from real domain states.
|
||||
- Use `StatusBadge` (kit `StatusPill`) mapped from real domain states.
|
||||
- Use dashed bordered empty states for loading and no-data cases.
|
||||
- Use top-bordered sections for page groups instead of nested cards.
|
||||
- Centralize formatting and redaction outside Razor markup.
|
||||
|
||||
Reference in New Issue
Block a user