Repository Public
1# MCC web — design system23The web application of MacLustr Command Center has its own component library (`src/ui/`), written for this4product. There is no UI framework and no utility-class kit: plain CSS driven by the shared design tokens.5A live gallery of every component is served at **`/dev/ui`** when `NODE_ENV !== "production"` (`pnpm dev`, then6`http://localhost:8730/dev/ui` through the Go server).78## 1. Direction910*The precision of an infrastructure cockpit.* Graphite canvas, crisp typography, strong hierarchy, sober charts.1112- **Colour is reserved for state.** The interface is neutral (canvas, surface, three text levels, hairlines). The13 only saturated colours are the state tones and the single accent used for focus, links and the primary action.14- **Structure by hairlines and space, not by boxes.** Screens are made of titled *sections* separated by a 1 px15 rule (`.section`). A bordered `.panel` is used only when content is a self-contained object (a widget, a table).16- **Dense but calm.** 13 px table text, 38 px rows (30 px compact), tabular numerals everywhere, monospace for17 identifiers (aliases, ids, hashes, metric names).18- **No decoration.** No gradients, no shadows except on overlays, no emoji, no illustration.19- **Fast micro-interactions.** 80–220 ms transitions from the motion tokens; all of them collapse to 0 under20 `prefers-reduced-motion: reduce`.2122## 2. Tokens2324Single source: `packages/ui-tokens/tokens.json` → `dist/tokens.css` (CSS variables `--mcc-*`), `dist/tokens.ts`25(semantic maps) and `Tokens.swift` for the Apple clients. `node packages/ui-tokens/build.mjs` regenerates the26outputs and **fails when a text or state colour does not reach WCAG AA** on the three backgrounds;27`pnpm build` runs it with `--check`.2829Rules enforced in this app:3031- CSS uses only `var(--mcc-…)` for colour, spacing, radius, type and motion. ESLint rejects hex colour literals32 in TS/TSX (`no-restricted-syntax`).33- Canvas drawing (charts) reads the token values at draw time with `getComputedStyle`, and redraws when34 `data-theme` changes.35- A missing token is added to `tokens.json`, never hard-coded. Tokens added for this app: `qr.light` / `qr.dark`36 (a QR code must stay dark-on-light in both themes to be scannable).3738Themes: dark is the default; light is `:root[data-theme="light"]`. The choice is a UI preference kept in the39non-sensitive cookie `mcc_theme`, applied by the server render (no flash, no inline script).4041### State tones4243One class per tone sets two custom properties (`--tone`, `--tone-bg`) that components consume:44`tone-ok`, `tone-warning`, `tone-critical`, `tone-info`, `tone-stale`, `tone-offline`, `tone-maintenance`,45`tone-neutral`. `src/ui/states.ts` maps API enums to tones from the generated `semantic` map, so the web and Apple46clients agree (`freshnessTone`, `severityTone`, `serviceTone`, `actionTone`, `jobTone`, `alertTone`, …).4748**State is never colour alone**: every tone has its own icon shape (check-circle, triangle, octagon, clock,49slashed circle, wrench…) and a text label. `Badge` and `StateDot` always render the three together.5051## 3. Components (`src/ui`)5253| Component | File | Notes |54|---|---|---|55| `Button`, `IconButton`, `LinkButton` | `core.tsx` | variants secondary / primary / ghost / danger; sizes sm 28 px, md 34 px, lg 44 px; 44 px minimum on coarse pointers. `IconButton` requires `label` (accessible name + tooltip). |56| `Badge`, `StateDot`, `Count`, `Tag`, `Kbd`, `Mono` | `core.tsx` | state presentation: tone + icon + text. |57| `Tooltip` | `core.tsx` | CSS-only; `focusable` makes it a tab stop — wrap disabled controls with it so the reason is reachable by keyboard. |58| `CopyButton` | `core.tsx` | confirms through a polite live region. |59| `KeyValue`, `Stat` | `core.tsx` | description lists; large figure with context. |60| `Skeleton`, `SkeletonRows` | `core.tsx` | loading placeholders with `role="status"`. |61| `Field`, `TextField`, `TextAreaField`, `SelectField`, `Checkbox`, `Switch`, `Segmented` | `form.tsx` | label / hint / error wiring (`aria-describedby`, `aria-invalid`, `role="alert"`); `Switch` writes its state as text; `Segmented` is a radiogroup with arrow keys. |62| `Combobox` | `Combobox.tsx` | WAI-ARIA 1.2 editable combobox with list autocomplete; `multiple` adds removable chips. |63| `Dialog`, `Drawer`, `ConfirmDialog` | `overlay.tsx` | native `<dialog>.showModal()`: focus trap, inert background, Esc and focus restore come from the platform. Dangerous confirmations focus *Cancel*. |64| `Menu` | `overlay.tsx` | menu-button pattern: arrows, Home/End, Esc restores focus. |65| `Tabs`, `TabPanel` | `overlay.tsx` | roving tabindex, arrow keys. |66| `ToastProvider`, `useToast` | `Toast.tsx` | polite region for results, assertive region for failures (which stay until dismissed). |67| `DataTable` | `Table.tsx` | caption, `scope="col"`, `aria-sort` on sortable headers (button inside the `th`), sticky header, selection column, responsive column hiding, **virtualized above 200 rows** (TanStack Virtual, `aria-rowcount` / `aria-rowindex`). |68| `Sparkline`, `Meter` | `viz.tsx` | SVG; gaps break the line; `Meter` is `role="meter"` and always shows its textual value. |69| `TimeSeriesChart` | `TimeSeriesChart.tsx` | uPlot (canvas) wrapper, imported from its own path so only chart routes load it. Average line + min/max envelope from `[ts, avg, min, max]`, holes drawn as gaps, token colours, several series (node comparison). Accessible: focusable plot, ←/→ (Shift ×10), Home/End move the cursor and the value is announced; a textual summary (last/min/avg/max per series) is always present; **table view toggle** (persisted preference). |70| `EmptyState`, `ErrorState`, `ForbiddenState`, `Banner`, `StaleBanner` | `data.tsx` | global states. `ErrorState` maps an `ApiError`: 501 → "not available yet", 503 → unavailable / emergency stop, 403 → names the missing permission, network, 404, other — with the correlation id and a copy button. |71| `QueryBoundary` | `data.tsx` | standard rendering of a query: skeleton → error state → data; a failed refetch keeps the last data under a stale banner. |72| `DataStamp`, `FreshnessBadge` | `data.tsx` | timestamp + freshness shown on every data view. |73| `Unmeasured`, `MetricValueView`, `Observed` | `data.tsx` | a value that cannot be measured is rendered as its availability state with the reason — never 0, never blank. |74| `LoadMore` | `data.tsx` | cursor pagination. |75| `DateTimeRangePicker` | `extras.tsx` | 1 h / 24 h / 7 d / 30 d presets + custom range in the browser zone (zone shown). |76| `SchemaForm` | `extras.tsx` | form generated from a JSON Schema (`lib/schemaForm.ts`), used by the action flow and job submission. |77| `LogView` | `extras.tsx` | bounded output viewer, **text nodes only**, search with highlighted matches, copy. |78| `Linkified` | `extras.tsx` | plain text with preserved line breaks and auto-linked http(s) URLs (`rel="noopener noreferrer nofollow"`); never parses HTML. |79| `QrCode` | `extras.tsx` | drawn locally from `lib/qr.ts` (own encoder, byte mode, level M, versions 1–10). |80| `Icon` | `Icon.tsx` | own 24 px stroke set; always `aria-hidden`. |81| `CommandPalette` | `shell/CommandPalette.tsx` | ⌘K / Ctrl+K; `GET /search` results + navigation and commands; combobox pattern. |8283Layout helpers (`styles/base.css`): `.page`, `.page-head`, `.section`, `.section-head`, `.panel`, `.row`,84`.row-wrap`, `.row-between`, `.stack`, `.cols-2/3/auto`, `.toolbar`, `.muted`, `.faint`, `.caps`, `.mono`,85`.num`, `.truncate`, `.sr-only`.8687## 4. Data, freshness and honesty8889- Server state lives in TanStack Query. Keys are `[path, {path, query}]`, so the realtime layer invalidates by path90 prefix (`shell/realtime.tsx`). `node.state` events patch the cached node lists in place.91- Every data view carries a `DataStamp`. `fresh` / `stale` / `offline` come from the server.92- 501 and 503 are first-class states, rendered by `ErrorState`; nothing is ever mocked client-side.93- The top bar shows the connection indicator: *live* / *reconnecting* / *offline since hh:mm:ss*.9495## 5. Accessibility (WCAG 2.2 AA)9697- Landmarks: skip link, `aside` + `nav` (main navigation), `header`, `main#main`, bottom `nav` under 720 px.98- Focus: 2 px ring in `--mcc-color-focus-ring` with offset on every interactive element (`:focus-visible`).99- Target size: 24 px minimum everywhere; 44 px on coarse pointers (`@media (pointer: coarse)`).100- Dialogs: native modal `<dialog>` (trap, restore, `aria-labelledby` / `aria-describedby`).101- Live regions: toasts, connection indicator, copy confirmation, action state, chart cursor.102- Tables: caption, column headers, `aria-sort`; charts: summary + table fallback.103- Motion: tokens collapse to 0 ms and animations are disabled under `prefers-reduced-motion`.104- Automated checks: `@axe-core/playwright` runs in the e2e suite on the main screens (WCAG 2.0/2.1/2.2 A + AA tags).105106## 6. Security constraints that shape components107108- **CSP** (`src/proxy.ts`): `script-src 'self' 'nonce-…' 'strict-dynamic'`, `style-src 'self' 'nonce-…'` — **no109 `unsafe-inline`, not even for style attributes.** Consequences: no `style` attribute in server-rendered markup;110 geometry is expressed with classes, SVG attributes, or set through the CSSOM on the client (which CSP allows).111 uPlot only uses the CSSOM. The e2e suite fails on any `securitypolicyviolation`.112- No `dangerouslySetInnerHTML` (ESLint `react/no-danger`). Logs, notes and server messages are text nodes.113- Web storage holds UI preferences only (`lib/prefs.ts`, the single allowed access point; ESLint forbids direct114 `localStorage` use). The CSRF token lives in memory (`api/transport.ts`).115- Secrets shown once (invitation link, enrollment token) stay in component state and are dropped on close.116117## 7. Internationalisation118119French is the reference dictionary (`src/i18n/fr`), English must have the identical shape (`Shape<Dict>` — a missing120or extra key is a type error) and a unit test checks key parity, non-empty values and matching placeholders.121`t("ns.key", vars)` and `tn("ns.key", count)` only accept existing keys. Numbers, bytes, durations and dates go122through `Intl` (`lib/format.ts`); clock times are 24 h `HH:mm:ss`; audit timestamps are UTC and say so.123124## 8. Adding a screen1251261. Types come from `src/api/schema.d.ts` (`pnpm gen:api`); never hand-write an API type.1272. Fetch with `useApiQuery` / `useApiList`, render with `QueryBoundary`, stamp with `DataStamp`.1283. Gate the page with `RequirePermission`; hide or disable mutations with `useSession().can()` — the server decides.1294. Mutations: `apiPost/Patch/Put/Delete` → toast (`useToast` + `useErrorMessage`) → `invalidatePaths`. Step-up is130 transparent (the transport prompts for the passkey and replays the request once).1315. Operator actions go through the shared flow (`features/actions/ActionFlow.tsx`), never a bespoke call.1326. Text in both dictionaries; CSS in `src/styles/features/<area>.css` with tokens only.133