UX Journey Maps
Status: v1.0 · Owner: Design Lead + Product Owner · Gate input: G1 Maps the critical end-to-end loops that define the product. Each journey lists the persona, the stages, what the user sees/does, the emotional state, the failure modes we design against, and the screens/phases involved. These journeys are the backbone of the Phase 9 end-to-end QA scenarios (
Phase_9.md§5.2).
Notation per stage: Do (user action) · See (system response) · Feel (emotional state) · Risk (failure mode we design against).
J1 — Technician completes an inspection offline (Tomás) ★ core loop
Persona: Tomás (Technician, mobile) · Phases: P4, P8 · Maps to Phase 9 Scenario C
Start of shift In the plant room (no signal) Back in coverage
───────────── ───────────────────────────── ────────────────
Open app ──▶ Tasks tab ──▶ Pick WO ──▶ Start inspection ──▶ Fill checklist ──▶ Photo + signature ──▶ Submit ──▶ (queued) ──▶ Auto-sync ──▶ Done
| Stage | Do | See | Feel | Risk → design response |
|---|---|---|---|---|
| Arrive | Open PWA from home screen | Bottom nav, Tasks badge with today's count | Oriented | Cold start slow → precached shell, skeletons |
| Triage | Tap Tasks | My queue, sorted priority + location, SLA chips | In control | Wrong sort → default = priority then nearest location |
| Open | Tap a work order | Detail: asset, checklist, sticky Start button | Focused | Buried action → sticky action bar, one primary button |
| Lose signal | (walks into basement) | Subtle "Offline" banner; everything still works | Unbothered | Hidden offline state → explicit, calm banner (not an error) |
| Execute | Complete checklist, add photo, scan QR, sign | Large controls; progress saved per field | Confident | Lost input → autosave each field to IndexedDB |
| Submit | Tap Submit | "Saved on device · will sync when online" badge | Reassured | Silent fail → never claim "done", claim "saved + pending" |
| Reconnect | (returns to coverage) | Toast: "1 inspection synced ✓"; badge clears | Relief | Conflict (server changed) → plain-language merge, default server-wins + manual override |
Design must-haves: explicit offline/queued/synced states (see UX_patterns.md State Matrix); 44px targets; no precision gestures required; sync status always truthful.
J2 — FM Supervisor runs the daily ops rhythm (Mei) ★ core loop
Persona: Mei (FM Supervisor) · Phases: P4, P5, P7 · Maps to Phase 9 Scenario B
Morning glance ──▶ Investigate ──▶ Act ──▶ Approve on the move ──▶ Report
(dashboard) (drill-through) (assign) (mobile inbox) (monthly)
| Stage | Do | See | Feel | Risk → design response |
|---|---|---|---|---|
| Glance | Open landing dashboard | PDCA KPI cards: open WOs by priority, SLA breaches, anomalies, planned:reactive | Informed in 5s | Noise → glanceable hierarchy, big primary number, quiet context |
| Trust | Hover/click a KPI | Provenance + drill straight to underlying records | Confident | Unverifiable KPI → every KPI clickable to its source rows |
| Act | Reassign overdue WOs from the list | Inline assign, escalation chain visible | Efficient | Modal maze → inline action + optimistic update |
| Approve | (on phone, later) Open Inbox | Approvals list; swipe-right approve, swipe-left reject | Unblocked | Buried approvals → bottom-nav Inbox with unread badge + push |
| Tune | Edit dashboard, drag a widget | Palette + inspector with sensible defaults, live preview | Empowered | JSON config → curated form copy, no raw config |
| Report | Run/schedule monthly KPI report | Branded PDF/XLSX, matches dashboard numbers | Trusted | Mismatch report vs dashboard → single KPI service feeds both |
Design must-haves: KPI card = headline number + trend + drill target; dashboard editor usable by non-engineers; report numbers reconcile with dashboard numbers exactly.
J3 — Tenant onboarding & first data (Daniel) ★ first-impression loop
Persona: Daniel (Tenant Admin) · Phases: P2, P3 · Maps to Phase 9 Scenario A
Accept invite ──▶ Brand it ──▶ Add people ──▶ Connect data ──▶ Import ledger ──▶ See telemetry live
(settings) (users/roles) (gateway/MQTT) (Excel wizard) (dashboard)
| Stage | Do | See | Feel | Risk → design response |
|---|---|---|---|---|
| Enter | Accept invite, enroll MFA | Guided onboarding checklist with progress | Welcomed | Maze of settings → single checklist surface with progress |
| Brand | Upload logo, set primary/accent | Live preview of brand theme applied | Ownership | Brand not applied → theme applies < 1 frame, preview instant |
| People | Invite users, assign roles | Role editor with permission checkboxes grouped by module | Secure | Permission confusion → grouped, plain-language permission labels |
| Connect | Create gateway, get credentials | Step-by-step connect guide + health beacon status | Capable | Opaque connect → live "waiting for first beacon…" → "connected ✓" |
| Import | Upload KTC asset ledger (8,180 rows) | Column-map preview, dry-run, top-50 preview, error report | Confident | Opaque bulk fail → row-level errors + downloadable report, no all-or-nothing |
| Payoff | Open default dashboard | Live telemetry flowing within minutes | Delighted | Empty product → seed a starter dashboard from a template |
Design must-haves: onboarding as a guided checklist, not scattered settings; import wizard with preview + dry-run + downloadable errors (Phase_3.md §5.6); a non-empty first dashboard so the tenant never sees a blank product.
J4 — Anomaly to resolution, AI-assisted (Priya → Tomás) ★ differentiator loop
Personas: Priya (NOC) + AI + Tomás · Phases: P3, P6, P7, P8 · Maps to Phase 9 Scenario C
Telemetry breach ──▶ Alert feed ──▶ AI explains ──▶ Workflow creates P2 WO ──▶ Approval ──▶ Technician executes ──▶ KPIs update
(Phase 3) (Phase 5) (Phase 6) (Phase 7) (Phase 7) (Phase 8) (Phase 4/5)
| Stage | Do/Happen | See | Feel | Risk → design response |
|---|---|---|---|---|
| Detect | Chiller temp crosses threshold | Alert appears in War Room feed, high contrast | Alert | Missed alarm → alert feed always-visible, audible/visual escalation |
| Explain | (AI) anomaly explanation | Plain-language cause + last-24h chart + citation | Informed | Black-box AI → reasoning + cited telemetry shown, not just a verdict |
| Automate | Workflow fires | "Workflow X created WO-1234" with run timeline | Trusting | Hidden automation → workflow run is visible + auditable step-by-step |
| Approve | FM approves P2 on mobile | One-tap approve; audit entry written | Unblocked | Lost approval → multi-channel + escalation timer |
| Execute | Tomás does the work (J1) | Offline-capable execution | Effective | (see J1) |
| Close loop | KPIs/MTTR recompute | Dashboard reflects the resolution | Closed | Stale KPIs → recompute on close, dashboard live-updates |
Design must-haves: AI always shows reasoning + citations + the data it used; workflow runs are transparent and auditable; the human approval gate is unmissable; OT control actions require explicit human-in-the-loop (never silent automation).
J5 — Executive asks a question and gets the monthly story (Akiko)
Persona: Akiko (Executive) · Phases: P5, P6 · Maps to Phase 9 Scenario D
Open Exec dashboard ──▶ Read the trend ──▶ Ask AI a plain question ──▶ Get cited answer ──▶ Receive monthly report
| Stage | Do | See | Feel | Risk → design response |
|---|---|---|---|---|
| Glance | Open Executive Summary template | Few big trended numbers + narrative context | Oriented | Operational noise → executive template strips operational detail |
| Ask | "How did reactive work trend this quarter?" (AI chat) | Plain-language answer + chart + citations | Reassured | Hallucination → RAG with citations; "I don't know" beats a guess |
| Receive | Monthly KPI report lands in inbox | Branded PDF, EN or JA per locale | Trusted | Untranslated/ugly report → i18n + brand-themed PDF templates |
Design must-haves: executive template = signal over detail; AI chat tone is calm and cites sources; reports are branded and locale-correct (EN/JA).
J6 — Developer integrates against the API (Sam)
Persona: Sam (Developer) · Phases: P2
Find docs ──▶ Get API key ──▶ "Try it out" ──▶ Generate SDK ──▶ First successful call
| Stage | Do | See | Feel | Risk → design response |
|---|---|---|---|---|
| Discover | Open /api/docs (Scalar) | Themed, searchable API reference + quickstart | Capable | Stale docs → spec is source of truth, CI blocks drift |
| Auth | Admin issues a scoped API key | Key shown once, scopes + rate limit clear | Careful | Key mishandling → "shown once" warning, copy + rotate UX |
| Call | "Try it out" in Scalar | Live response with the key | Confident | Friction → prefilled examples, copy-as-curl/SDK snippet |
| Scale | import { listAssets } from "@gp/atlas-sdk" | Typed hooks, versioned package | Productive | Type drift → SDK generated from same OpenAPI |
Design must-haves: developer portal is a real product surface (themed Scalar + quickstart), not an afterthought; error responses are designed (consistent shape, actionable messages).
Cross-journey UX commitments (apply to all)
- Never a dead end — every stage above has designed loading/empty/error/offline/no-permission states.
- Always truthful about state — "saved", "pending sync", "running", "failed" are never faked or hidden.
- One primary action per screen — the journey's next step is the most prominent control.
- Drill-through everywhere — any number, alert, or status is clickable to its source record.
- Transparency for trust — AI cites, workflows show steps, audit is visible, offline shows sync state.
- Phone-first where the user is mobile (J1, J2-approve, J4-approve) — designed for the phone, enhanced on desktop.