docs(design): define Stitch-backed product direction

2026-08-02 03:26:54 +02:00
parent f0c0af128e
commit 73e361002d
11 changed files with 221 additions and 5 deletions
@@ -1,8 +1,8 @@
 # MobilityOps current UX audit

-Date: 2026-08-02  
-Audited revision: `dfabb41582e302f45a3de826f85f531bf23dfc8b`  
-Live URL: `http://192.168.10.150:1236`  
+Date: 2026-08-02
+Audited revision: `dfabb41582e302f45a3de826f85f531bf23dfc8b`
+Live URL: `http://192.168.10.150:1236`
 Role used: Operations Manager, deterministic synthetic seed

 ## Executive finding
@@ -110,8 +110,8 @@ varying navigation, density, rhythm, and status representation:
   readiness band and timeline.
 2. **Dispatch Ledger:** editorial typography, ledger-like grouped lists, calmer top
   navigation and strong temporal rhythm.
-3. **Operations Canvas:** adaptive split workspace, spatial fleet/status visualization,
-   contextual side panels and progressive disclosure.
+3. **Service Atelier:** calm editorial service workspace, narrative timelines,
+   humanized exceptions, and progressive disclosure.

 The final choice must favour business credibility and workflow clarity over screenshot
 novelty. No implementation begins until the Stitch comparison and decision are recorded.
@@ -0,0 +1,136 @@
+# MobilityOps design directions
+
+Date: 2026-08-02
+Stitch project: `projects/17018847755558569017`
+
+All directions solve the same twelve-screen product map. The first three columns below
+were authored as complete direction inventories; representative high-fidelity anchors
+were generated through Stitch and stored in `artifacts/design-validation/stitch/`.
+Stitch's multi-screen generation endpoint did not return a reliable screen collection
+for 12-screen requests, so generation was split into smaller, inspectable calls. The
+selected direction was then implemented and captured across every working route.
+
+## Shared twelve-screen product map
+
+| # | Screen | Required job |
+|---|---|---|
+| 01 | Login | Choose a demo role with a clear product promise and trust disclosure. |
+| 02 | Operations dashboard | Scan readiness, today's movements, attention and integration evidence. |
+| 03 | Fleet registry | Find and filter vehicles; spot status and attention quickly. |
+| 04 | Vehicle record | Understand one vehicle's readiness, facts, history and quality state. |
+| 05 | Booking ledger | Search and filter bookings without rendering an unbounded wall of rows. |
+| 06 | Booking return | Capture inspection facts, review consequences, then commit locally. |
+| 07 | Quality workbench | Triage persisted data-quality exceptions by evidence and severity. |
+| 08 | Duplicate review | Compare conflicts, select a survivor and preview the irreversible merge. |
+| 09 | Procedure knowledge | Ask, retrieve, verify evidence and show cited sources. |
+| 10 | Integration control | Show n8n, RAGcore and MCP Hub as connected, degraded or unconfigured. |
+| 11 | Audit trail | Trace actors, actions, correlation IDs and expandable metadata. |
+| 12 | Mobile operations | Preserve priority, context and navigation at 390 px without overflow. |
+
+## Direction A — Control Rail
+
+Purpose: a calm, high-density control centre for operators who move between live state,
+exceptions and record work throughout a shift.
+
+- Deep-petrol persistent rail; mineral-teal active/action state.
+- Off-white canvas and white work surfaces separated by thin rules.
+- Compact readiness bands and table/timeline hybrids instead of KPI-card walls.
+- Inter/system grotesk, 4 px radii, restrained shadows, semantic status dots.
+- Mobile uses a compact top bar, six-item labelled bottom navigation, and stacked work
+  sections with a horizontally scrollable readiness strip.
+
+Twelve-screen treatment:
+
+| Screen | Control Rail treatment |
+|---|---|
+| Login | Split dark story panel and direct role workspace choices. |
+| Dashboard | Readiness band; Attention and movements primary; systems/activity secondary. |
+| Fleet | Search/filter toolbar and compact registry rows with attention rule. |
+| Vehicle | Persistent status header, task tabs and ruled fact/history surfaces. |
+| Bookings | Filtered ledger with client-side pagination and clear rental windows. |
+| Return | Three-step capture/review/result rail with calculated consequence preview. |
+| Quality | Work queue language, severity markers and evidence-first issue rows. |
+| Duplicate | Aligned field comparison with match/difference markers and merge preview. |
+| Knowledge | Retrieval flow, explicit evidence state and primary source cards. |
+| Integrations | Three honest system cards above a retryable outbox ledger. |
+| Audit | Humanized action labels and expandable technical metadata. |
+| Mobile | Bottom navigation, stacked rows with explicit labels, fixed priority order. |
+
+Stitch references:
+
+![Control Rail anchor](../../artifacts/design-validation/stitch/direction-a-control-rail.png)
+
+![Control Rail final refinement](../../artifacts/design-validation/stitch/direction-a-refinement-2.png)
+
+![Control Rail mobile](../../artifacts/design-validation/stitch/direction-a-mobile-dashboard.png)
+
+## Direction B — Dispatch Ledger
+
+Purpose: maximize throughput and repeatable scanning for a dispatch-heavy team.
+
+- Ink-black 48 px header and 64 px rail on a warm-ivory ledger surface.
+- Cobalt actions; amber/vermilion reserved for operational exceptions.
+- 36 px ruled rows, near-square controls, caps labels and almost no elevation.
+- Strongest at dense registry and scheduling work; least forgiving on mobile.
+
+Twelve-screen treatment:
+
+| Screen | Dispatch Ledger treatment |
+|---|---|
+| Login | Minimal logbook cover and compact operator credentials panel. |
+| Dashboard | Aviation-style operational ledger with row groups by urgency. |
+| Fleet | Dense registry, selection checkboxes, batch bar and page counts. |
+| Vehicle | Two-column log sheet with dated maintenance/inspection rows. |
+| Bookings | Time-window ledger grouped by departure/return shift. |
+| Return | Inspection checklist on a ruled form with a signed dispatch summary. |
+| Quality | Exception ledger grouped by severity, rule and age. |
+| Duplicate | Side-by-side identity ledger with explicit canonical-record column. |
+| Knowledge | Query/result folio with citations rendered as reference notes. |
+| Integrations | Systems board with timestamped status rows and delivery attempts. |
+| Audit | Chronological event ledger with technical disclosure rows. |
+| Mobile | Single-column status cards; secondary because ledger density compresses poorly. |
+
+![Dispatch Ledger fleet anchor](../../artifacts/design-validation/stitch/direction-b-fleet-registry.png)
+
+## Direction C — Service Atelier
+
+Purpose: create a reassuring human service workspace for mixed operational and concierge
+teams where narrative context matters as much as data density.
+
+- Pale mineral canvas, forest-green ink, sage active surfaces and clay exceptions.
+- Editorial serif headlines paired with a legible sans-serif for operational values.
+- 10 px surfaces, gentle spacing and functional line illustrations.
+- Strongest at service journeys and knowledge; weaker at high-volume exception scanning.
+
+Twelve-screen treatment:
+
+| Screen | Service Atelier treatment |
+|---|---|
+| Login | Human product narrative and quiet operator choice cards. |
+| Dashboard | Curated timeline, readiness trio, attention atelier and system health. |
+| Fleet | Collection-style rows with vehicle identity and service narrative. |
+| Vehicle | Editorial profile, recent journey and maintenance story. |
+| Bookings | Customer-led service itinerary grouped by day. |
+| Return | Guided hand-back narrative with warm explanation of consequences. |
+| Quality | Review studio with issue context, evidence and suggested next step. |
+| Duplicate | Identity portrait comparison with survivor preview. |
+| Knowledge | Concierge-like question flow grounded by visible source folios. |
+| Integrations | Calm service-health cards with progressive technical detail. |
+| Audit | Human-readable activity journal with expandable references. |
+| Mobile | Single-column narrative timeline and large service actions. |
+
+![Service Atelier anchor](../../artifacts/design-validation/stitch/direction-c-service-atelier.png)
+
+## Decision
+
+Control Rail is selected. It keeps Dispatch Ledger's operational precision without its
+mobile and cognitive-density penalty, while avoiding Service Atelier's tendency to
+soften high-severity triage. Its compact rail, readiness band and disciplined status
+grammar translate directly to the existing route and API model.
+
+Two explicit Stitch refinement passes shaped the implementation:
+
+1. Reordered the page around readiness, Attention and movements; demoted integrations
+   and recent activity to a quieter tier; removed oversized KPIs.
+2. Standardized 44 px targets, visible focus, table headings, compact filters, stronger
+   contrast, active navigation and mobile-safe layout rules.
@@ -0,0 +1,60 @@
+# MobilityOps Control Rail design system
+
+## Product principles
+
+1. **Decisions before decoration.** Readiness, attention and next action lead each page.
+2. **Persisted truth only.** Counts and health claims come from current API responses;
+   unavailable and unconfigured services are stated honestly.
+3. **Evidence before consequence.** Returns and merges preview their impact before the
+   irreversible request; knowledge answers identify evidence sufficiency.
+4. **Dense, never cramped.** Thin rules and compact type replace nested cards, while
+   interactive targets remain at least 40 px (44 px in mobile navigation and key flows).
+
+## Tokens
+
+| Role | Token | Value |
+|---|---|---|
+| Primary structure | `--petrol` | `#0f172a` |
+| Secondary structure | `--petrol-2` | `#15243a` |
+| Primary action | `--teal-dark` | `#0b6f67` |
+| Active highlight | `--teal` | `#0f8f83` |
+| Action tint | `--teal-pale` | `#e7f7f4` |
+| Canvas | `--canvas` | `#f5f7fa` |
+| Surface | `--surface` | `#ffffff` |
+| Divider | `--line` | `#dbe2ea` |
+| Body ink | `--ink` | `#0f172a` |
+| Secondary text | `--muted` | `#657386` |
+| Critical | `--critical` | `#c93636` |
+| Warning | `--warning` | `#b96812` |
+| Success | `--success` | `#17724b` |
+| Keyboard focus | `--focus` | `#14b8a6` |
+| Standard radius | `--radius` | `4px` |
+
+Typography uses Inter when available and a system sans-serif fallback. Page titles are
+28–35 px desktop and 24–26 px mobile; section headings are 16 px; table content is 12 px
+with 10 px uppercase labels. Hierarchy comes from position, weight and rules rather than
+display-sized text.
+
+## Core component grammar
+
+- **Shell:** 224 px desktop rail, 64 px sticky top bar, persistent synthetic-data band.
+- **Mobile shell:** 58 px top bar, off-canvas full navigation and six-item 65 px bottom bar.
+- **Readiness:** horizontal definition-list band; warning and critical values get a
+  semantic underline and text color.
+- **Work panel:** one border, 4 px radius, section header, optional compact controls and
+  ruled content. No nesting for decorative depth.
+- **Status:** text plus dot/shape and semantic foreground/background; color is never the
+  only carrier.
+- **Tables:** explicit headers on desktop; `data-label` term/value rows on mobile.
+- **Feedback:** normalized loading, empty and error surfaces keep page context.
+- **Motion:** 160–280 ms for hover/page entry; removed under `prefers-reduced-motion`.
+
+## Accessibility and responsive rules
+
+- Skip link, named navigation landmarks and one main landmark per authenticated page.
+- 3 px high-contrast `:focus-visible` outline with offset.
+- Form labels remain programmatic; icon-only controls carry accessible names and titles.
+- Desktop tables become labelled row cards below 700 px; no header meaning is lost.
+- The document has no horizontal overflow at 390, 768, 1280 or 1440 px.
+- All status and evidence states include readable text; critical actions are separated
+  from navigation and review precedes commit.
@@ -0,0 +1,20 @@
+# Stitch generation manifest
+
+Project: `projects/17018847755558569017` — MobilityOps Premium Product Design
+
+| Direction/pass | Stitch screen | Local evidence |
+|---|---|---|
+| A — Control Rail dashboard | `eb43638c9b224ef6b56149f8dfd1abf9` | `direction-a-control-rail.png` |
+| A — Fleet state illustration | `2be1f8d02058487c8f6c10d9f4c37479` | referenced in the original anchor |
+| A — Refinement 1 | `a835dcf72fb942809e7a900f7cb4fd4d` | `direction-a-refinement-1.png` |
+| A — Refinement 2 | `49b0e38ed7de4b3fab882af0903a5151` | `direction-a-refinement-2.png` |
+| A — Mobile dashboard | `d378e73e240449abb14f0dd470b9e3c9` | `direction-a-mobile-dashboard.png` |
+| B — Dispatch Ledger fleet | `ed2b4fc5a6cf4d5191886834d1b5d2a9` | `direction-b-fleet-registry.png` |
+| C — Service Atelier dashboard | `8296b1bcb236441e8a1214c5228bbc50` | `direction-c-service-atelier.png` |
+| C — Technical illustration set | `3e742dbad41d4622938fe1848c25f7fe` | included in C output |
+
+The folder `artifacts/design-validation/stitch/` contains the exact downloaded Stitch
+screens used in direction evaluation. Generated HTML assets remain available in the
+Stitch project. The implementation intentionally translates the selected system into
+the repository's existing React, TypeScript and CSS stack instead of importing generated
+markup, preserving application semantics, API behavior and maintainability.