diff --git a/docs/03-design/ui-patterns.md b/docs/03-design/ui-patterns.md new file mode 100644 index 0000000..e8026aa --- /dev/null +++ b/docs/03-design/ui-patterns.md @@ -0,0 +1,157 @@ +# UI patterns + +Reusable patterns used across the operator console. + +## Three-layer view identification + +See [ADR-0009](../../decisions/0009-no-redundancia-titulos.md) for the full rationale. + +| Layer | Function | Element | +|---|---|---| +| 1 | Navigation (where am I in the product?) | Active pill in left rail | +| 2 | Mode (what domain is this view in?) | Title strip in topbar (color shifts per domain) | +| 3 | Operational context (what's happening here right now?) | `.ctx-strip` with badge + dynamic data | + +The panel-level `

` "▸ NAME" is **gone**. Don't reintroduce it. + +For multi-zone views (e.g. forensics), inner `

` headers are kept because zones coexist on screen. + +## Compact context strip + +Used at the top of every panel. Pattern: + +```html +
+
+ DYNAMIC INFO HERE + optional info-bearing sub-line, no descriptive prose +
+ +
+``` + +The badge contains **dynamic info** (states, counts, target endpoints, branch/sha). The sub-line is optional and only when it adds info. Never used for descriptive prose explaining what the view does — that's redundant with the rail. + +## Full-screen wizard mode + +Used for first-boot wizard and camera onboarding. The console chrome (rail, topbar, status strip) is hidden when in wizard mode. + +```html + +
+ +
+ +``` + +Activation via `body.classList.add('wizard-on')`. Deactivation reverts to normal console. + +For demos, both wizards have a floating toggle button at the bottom right. In production these don't exist — the wizard appears automatically on first boot, and disappears once provisioning is complete. + +## SCADA-style live diagram (SYNOPSIS) + +The landing view is a hand-tuned SVG diagram of the site's hardware and services. Conventions: + +- **Components** as rectangles with rounded corners (`rx="14"` for major devices, `rx="6"` for small chips). +- **VLANs** as dashed colored halos around groups of components. +- **Service chips** as small rounded rectangles inside their host device, with a status pulse dot on the right edge. +- **Flows** as `stroke-dasharray` lines with `flow-line` animation. Direction arrows via SVG `marker-end`. +- **Gauges** at the bottom: half-circle SVG paths with the value as text below. + +Hand-tuned coordinates for now. If the diagram grows beyond ~10 components, consider migrating to a layout library (e.g., Cytoscape.js) but accept the loss of brand polish. + +## Chat with ghost-text autocomplete + +Forensic and transcript queries use the same pattern: + +```html +
+
+ user typed text + + suggested completion +
+
+
+ TAB ACCEPT + ↵ RUN + ⌘K COMMANDS +
+``` + +Suggestions come from the agent backend, contextual to known cameras / speakers / topics / time ranges. + +## Agent pipeline visualization + +When a query is decomposed into sub-queries, render the pipeline as: + +```html +
+
+ ✓ + nlp.search(topic="contrato Acme") + 94ms +
+ +
+``` + +States: `done` (green check), `run` (running, animated), `pending` (dimmed circle), `fail` (red). + +Communicates "the system is doing work, here's what" and demonstrates the multi-AI fusion. + +## Timeline with markers + +Used for forensics and transcript playback. + +- **X-axis**: time, with sparse axis labels (5-10 ticks). +- **Markers**: vertical lines at hit positions, color-coded by type. +- **Playhead**: distinct color (cyan or warn-cyan), fixed during playback. +- **Swimlanes** (when multiple sources): horizontal bands per source, one row each. + +Click on marker → jump player to that timestamp + scroll transcript/event list to corresponding entry. + +## Player shell + +For both video clips (Blocao) and audio segments (transcript): + +``` +[ play | pause ] [ scrubber with progress overlay ] [ time MM:SS / TOTAL ] +[ controls row: ±5s, prev/next turn, speed, follow playhead, secondary actions ] +[ live caption / metadata bar ] +``` + +The shell is shared; what differs is the visualization above the scrubber (frame for video, waveform for audio). + +## Health test items with expandable detail + +```html +
+ ! +
FPS per camera
expected 15.0 ±10%
+
3/4 IN RANGE
+
+
⚠ WARNING · cam-04 below threshold
+ Body explaining the issue. +
+ Likely cause: ... +
+
+ + +
+
+
+``` + +OK items don't expand (no info to show). Warn/err items expand with detail + suggested actions. + +## When to break a pattern + +Patterns are starting points, not handcuffs. Break a pattern when: + +- The data shape genuinely doesn't fit (e.g., a 1000-row table doesn't belong in a card). +- The user's primary question can't be answered with the standard layout. +- A custom visualization is more memorable for a key moment (SYNOPSIS itself is a "broken pattern" relative to the rest of the console). + +Document any pattern break with an inline code comment and, if it sticks, promote it to a new pattern in this file.