MCC web — design system
The web application of MacLustr Command Center has its own component library (src/ui/), written for this
product. There is no UI framework and no utility-class kit: plain CSS driven by the shared design tokens.
A live gallery of every component is served at /dev/ui when NODE_ENV !== "production" (pnpm dev, then
http://localhost:8730/dev/ui through the Go server).
1. Direction
The precision of an infrastructure cockpit. Graphite canvas, crisp typography, strong hierarchy, sober charts.
- Colour is reserved for state. The interface is neutral (canvas, surface, three text levels, hairlines). The only saturated colours are the state tones and the single accent used for focus, links and the primary action.
- Structure by hairlines and space, not by boxes. Screens are made of titled sections separated by a 1 px
rule (
.section). A bordered.panelis used only when content is a self-contained object (a widget, a table). - Dense but calm. 13 px table text, 38 px rows (30 px compact), tabular numerals everywhere, monospace for identifiers (aliases, ids, hashes, metric names).
- No decoration. No gradients, no shadows except on overlays, no emoji, no illustration.
- Fast micro-interactions. 80–220 ms transitions from the motion tokens; all of them collapse to 0 under
prefers-reduced-motion: reduce.
2. Tokens
Single source: packages/ui-tokens/tokens.json → dist/tokens.css (CSS variables --mcc-*), dist/tokens.ts
(semantic maps) and Tokens.swift for the Apple clients. node packages/ui-tokens/build.mjs regenerates the
outputs and fails when a text or state colour does not reach WCAG AA on the three backgrounds;
pnpm build runs it with --check.
Rules enforced in this app:
- CSS uses only
var(--mcc-…)for colour, spacing, radius, type and motion. ESLint rejects hex colour literals in TS/TSX (no-restricted-syntax). - Canvas drawing (charts) reads the token values at draw time with
getComputedStyle, and redraws whendata-themechanges. - A missing token is added to
tokens.json, never hard-coded. Tokens added for this app:qr.light/qr.dark(a QR code must stay dark-on-light in both themes to be scannable).
Themes: dark is the default; light is :root[data-theme="light"]. The choice is a UI preference kept in the
non-sensitive cookie mcc_theme, applied by the server render (no flash, no inline script).
State tones
One class per tone sets two custom properties (--tone, --tone-bg) that components consume:
tone-ok, tone-warning, tone-critical, tone-info, tone-stale, tone-offline, tone-maintenance,
tone-neutral. src/ui/states.ts maps API enums to tones from the generated semantic map, so the web and Apple
clients agree (freshnessTone, severityTone, serviceTone, actionTone, jobTone, alertTone, …).
State is never colour alone: every tone has its own icon shape (check-circle, triangle, octagon, clock,
slashed circle, wrench…) and a text label. Badge and StateDot always render the three together.
3. Components (src/ui)
| Component | File | Notes |
|---|---|---|
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). |
Badge, StateDot, Count, Tag, Kbd, Mono |
core.tsx |
state presentation: tone + icon + text. |
Tooltip |
core.tsx |
CSS-only; focusable makes it a tab stop — wrap disabled controls with it so the reason is reachable by keyboard. |
CopyButton |
core.tsx |
confirms through a polite live region. |
KeyValue, Stat |
core.tsx |
description lists; large figure with context. |
Skeleton, SkeletonRows |
core.tsx |
loading placeholders with role="status". |
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. |
Combobox |
Combobox.tsx |
WAI-ARIA 1.2 editable combobox with list autocomplete; multiple adds removable chips. |
Dialog, Drawer, ConfirmDialog |
overlay.tsx |
native <dialog>.showModal(): focus trap, inert background, Esc and focus restore come from the platform. Dangerous confirmations focus Cancel. |
Menu |
overlay.tsx |
menu-button pattern: arrows, Home/End, Esc restores focus. |
Tabs, TabPanel |
overlay.tsx |
roving tabindex, arrow keys. |
ToastProvider, useToast |
Toast.tsx |
polite region for results, assertive region for failures (which stay until dismissed). |
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). |
Sparkline, Meter |
viz.tsx |
SVG; gaps break the line; Meter is role="meter" and always shows its textual value. |
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). |
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. |
QueryBoundary |
data.tsx |
standard rendering of a query: skeleton → error state → data; a failed refetch keeps the last data under a stale banner. |
DataStamp, FreshnessBadge |
data.tsx |
timestamp + freshness shown on every data view. |
Unmeasured, MetricValueView, Observed |
data.tsx |
a value that cannot be measured is rendered as its availability state with the reason — never 0, never blank. |
LoadMore |
data.tsx |
cursor pagination. |
DateTimeRangePicker |
extras.tsx |
1 h / 24 h / 7 d / 30 d presets + custom range in the browser zone (zone shown). |
SchemaForm |
extras.tsx |
form generated from a JSON Schema (lib/schemaForm.ts), used by the action flow and job submission. |
LogView |
extras.tsx |
bounded output viewer, text nodes only, search with highlighted matches, copy. |
Linkified |
extras.tsx |
plain text with preserved line breaks and auto-linked http(s) URLs (rel="noopener noreferrer nofollow"); never parses HTML. |
QrCode |
extras.tsx |
drawn locally from lib/qr.ts (own encoder, byte mode, level M, versions 1–10). |
Icon |
Icon.tsx |
own 24 px stroke set; always aria-hidden. |
CommandPalette |
shell/CommandPalette.tsx |
⌘K / Ctrl+K; GET /search results + navigation and commands; combobox pattern. |
Layout helpers (styles/base.css): .page, .page-head, .section, .section-head, .panel, .row,
.row-wrap, .row-between, .stack, .cols-2/3/auto, .toolbar, .muted, .faint, .caps, .mono,
.num, .truncate, .sr-only.
4. Data, freshness and honesty
- Server state lives in TanStack Query. Keys are
[path, {path, query}], so the realtime layer invalidates by path prefix (shell/realtime.tsx).node.stateevents patch the cached node lists in place. - Every data view carries a
DataStamp.fresh/stale/offlinecome from the server. - 501 and 503 are first-class states, rendered by
ErrorState; nothing is ever mocked client-side. - The top bar shows the connection indicator: live / reconnecting / offline since hh:mm:ss.
5. Accessibility (WCAG 2.2 AA)
- Landmarks: skip link,
aside+nav(main navigation),header,main#main, bottomnavunder 720 px. - Focus: 2 px ring in
--mcc-color-focus-ringwith offset on every interactive element (:focus-visible). - Target size: 24 px minimum everywhere; 44 px on coarse pointers (
@media (pointer: coarse)). - Dialogs: native modal
<dialog>(trap, restore,aria-labelledby/aria-describedby). - Live regions: toasts, connection indicator, copy confirmation, action state, chart cursor.
- Tables: caption, column headers,
aria-sort; charts: summary + table fallback. - Motion: tokens collapse to 0 ms and animations are disabled under
prefers-reduced-motion. - Automated checks:
@axe-core/playwrightruns in the e2e suite on the main screens (WCAG 2.0/2.1/2.2 A + AA tags).
6. Security constraints that shape components
- CSP (
src/proxy.ts):script-src 'self' 'nonce-…' 'strict-dynamic',style-src 'self' 'nonce-…'— nounsafe-inline, not even for style attributes. Consequences: nostyleattribute in server-rendered markup; geometry is expressed with classes, SVG attributes, or set through the CSSOM on the client (which CSP allows). uPlot only uses the CSSOM. The e2e suite fails on anysecuritypolicyviolation. - No
dangerouslySetInnerHTML(ESLintreact/no-danger). Logs, notes and server messages are text nodes. - Web storage holds UI preferences only (
lib/prefs.ts, the single allowed access point; ESLint forbids directlocalStorageuse). The CSRF token lives in memory (api/transport.ts). - Secrets shown once (invitation link, enrollment token) stay in component state and are dropped on close.
7. Internationalisation
French is the reference dictionary (src/i18n/fr), English must have the identical shape (Shape<Dict> — a missing
or extra key is a type error) and a unit test checks key parity, non-empty values and matching placeholders.
t("ns.key", vars) and tn("ns.key", count) only accept existing keys. Numbers, bytes, durations and dates go
through Intl (lib/format.ts); clock times are 24 h HH:mm:ss; audit timestamps are UTC and say so.
8. Adding a screen
- Types come from
src/api/schema.d.ts(pnpm gen:api); never hand-write an API type. - Fetch with
useApiQuery/useApiList, render withQueryBoundary, stamp withDataStamp. - Gate the page with
RequirePermission; hide or disable mutations withuseSession().can()— the server decides. - Mutations:
apiPost/Patch/Put/Delete→ toast (useToast+useErrorMessage) →invalidatePaths. Step-up is transparent (the transport prompts for the passkey and replays the request once). - Operator actions go through the shared flow (
features/actions/ActionFlow.tsx), never a bespoke call. - Text in both dictionaries; CSS in
src/styles/features/<area>.csswith tokens only.