diff --git a/artifacts/design-validation/stitch/direction-a-control-rail.png b/artifacts/design-validation/stitch/direction-a-control-rail.png new file mode 100644 index 0000000..5002a0e Binary files /dev/null and b/artifacts/design-validation/stitch/direction-a-control-rail.png differ diff --git a/artifacts/design-validation/stitch/direction-a-mobile-dashboard.png b/artifacts/design-validation/stitch/direction-a-mobile-dashboard.png new file mode 100644 index 0000000..4b45e62 Binary files /dev/null and b/artifacts/design-validation/stitch/direction-a-mobile-dashboard.png differ diff --git a/artifacts/design-validation/stitch/direction-a-refinement-1.png b/artifacts/design-validation/stitch/direction-a-refinement-1.png new file mode 100644 index 0000000..cd1ac5f Binary files /dev/null and b/artifacts/design-validation/stitch/direction-a-refinement-1.png differ diff --git a/artifacts/design-validation/stitch/direction-a-refinement-2.png b/artifacts/design-validation/stitch/direction-a-refinement-2.png new file mode 100644 index 0000000..6838884 Binary files /dev/null and b/artifacts/design-validation/stitch/direction-a-refinement-2.png differ diff --git a/artifacts/design-validation/stitch/direction-b-dispatch-ledger.png b/artifacts/design-validation/stitch/direction-b-dispatch-ledger.png new file mode 100644 index 0000000..43a72db Binary files /dev/null and b/artifacts/design-validation/stitch/direction-b-dispatch-ledger.png differ diff --git a/artifacts/design-validation/stitch/direction-b-fleet-registry.png b/artifacts/design-validation/stitch/direction-b-fleet-registry.png new file mode 100644 index 0000000..3a01e7b Binary files /dev/null and b/artifacts/design-validation/stitch/direction-b-fleet-registry.png differ diff --git a/artifacts/design-validation/stitch/direction-c-service-atelier.png b/artifacts/design-validation/stitch/direction-c-service-atelier.png new file mode 100644 index 0000000..7566ae0 Binary files /dev/null and b/artifacts/design-validation/stitch/direction-c-service-atelier.png differ diff --git a/docs/design/current-ux-audit.md b/docs/design/current-ux-audit.md index 7603e45..9506521 100644 --- a/docs/design/current-ux-audit.md +++ b/docs/design/current-ux-audit.md @@ -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. diff --git a/docs/design/design-directions.md b/docs/design/design-directions.md new file mode 100644 index 0000000..0121046 --- /dev/null +++ b/docs/design/design-directions.md @@ -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. diff --git a/docs/design/design-system.md b/docs/design/design-system.md new file mode 100644 index 0000000..91f6e30 --- /dev/null +++ b/docs/design/design-system.md @@ -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. diff --git a/docs/design/stitch-manifest.md b/docs/design/stitch-manifest.md new file mode 100644 index 0000000..7e582f7 --- /dev/null +++ b/docs/design/stitch-manifest.md @@ -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.