SPB Git

Repository Public

DESIGN-SYSTEM.md 10.7 KB

# 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 .panel is 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 when data-theme changes.
  • 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.state events patch the cached node lists in place.
  • Every data view carries a DataStamp. fresh / stale / offline come 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, bottom nav under 720 px.
  • Focus: 2 px ring in --mcc-color-focus-ring with 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/playwright runs 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-…' — no unsafe-inline, not even for style attributes. Consequences: no style attribute 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 any securitypolicyviolation.
  • No dangerouslySetInnerHTML (ESLint react/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 direct localStorage use). 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

  1. Types come from src/api/schema.d.ts (pnpm gen:api); never hand-write an API type.
  2. Fetch with useApiQuery / useApiList, render with QueryBoundary, stamp with DataStamp.
  3. Gate the page with RequirePermission; hide or disable mutations with useSession().can() — the server decides.
  4. Mutations: apiPost/Patch/Put/Delete → toast (useToast + useErrorMessage) → invalidatePaths. Step-up is transparent (the transport prompts for the passkey and replays the request once).
  5. Operator actions go through the shared flow (features/actions/ActionFlow.tsx), never a bespoke call.
  6. Text in both dictionaries; CSS in src/styles/features/<area>.css with tokens only.
Files main
Menu

Theme