Jens/MobilityOps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

UX: implement visual product roadmap

Browse Source
This commit is contained in:
NuklearRabbit
2026-08-10 01:05:07 +02:00
parent 13ad2ba6a3
commit f2cdad194c
40 changed files with 1010 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/18-visual-product-roadmap.md
+509
View File
@@ -0,0 +1,509 @@
# MobilityOps visual product roadmap
## Purpose
This roadmap turns the visual audit of the deployed MobilityOps PoC into an
implementation plan. It improves the existing operational workflows without
expanding the locked product scope.
The intended outcome is a platform that:
- lets an operator identify and act on urgent work within thirty seconds;
- remains efficient with the current synthetic data set and larger realistic data sets;
- keeps status, context and primary actions visible on desktop and mobile;
- uses a readable, consistent visual hierarchy;
- communicates integration and knowledge health without contradictory signals;
- preserves the existing domain rules, audit guarantees and graceful degradation.
## Scope guardrails
Included:
- information architecture and visual hierarchy;
- list density, pagination, filtering and responsive presentation;
- dashboard, detail, return, data-quality, knowledge, automation, audit and demo flows;
- accessibility, perceived performance and UI observability;
- regression tests, visual evidence and rollout safeguards.
Excluded:
- new accounting, payments, CRM, inventory, HR or reservation modules;
- maintenance work orders, calendar views or advanced analytics;
- changes to RAGcore or ITWorx MCP Hub repositories;
- autonomous write actions or write-capable MCP tools;
- a redesign of backend domain rules that is not required by the UI work.
## Audit baseline
The audit was performed against the deployed application at desktop, tablet and
mobile widths. The current strengths to preserve are the professional visual
identity, consistent status language, strong login page, semantic page structure,
visible keyboard focus, absence of horizontal overflow and clear return and
data-quality narratives.
The principal improvement signals are:
| Area | Baseline observation | Consequence |
|---|---|---|
| Audit log | Up to 100 expanded event cards; approximately 18,500 px desktop and 20,500 px mobile | Poor scanability and excessive scrolling |
| Vehicle list | All 50 vehicles render at once; approximately 12,000 px on mobile | Operational lookup is slow on small screens |
| Mobile page header | `.page-actions` is hidden below 700 px | Important record status disappears |
| Typography | Many metadata labels and badges are approximately 9–11 px | Readability is weaker than the visual quality suggests |
| Top bar | Search, language, demo controls, disclosure, timezone and operator controls compete for space | High cognitive load and weak prioritisation |
| Knowledge | An operational provider can be shown beside “0 procedures indexed” | Trust signal is ambiguous or contradictory |
| Integration cards | Technical identifiers and small prose dominate the summary | Operational state is harder to scan |
These values are baselines, not permanent acceptance thresholds. Each affected
phase must record a before-and-after measurement.
## Delivery principles
1. Fix operational friction before decorative polish.
2. Prefer progressive disclosure over removing useful evidence.
3. Keep the primary status and next action visible at every viewport.
4. Paginate or virtualise unbounded collections; never solve them only with CSS.
5. Derive every displayed count and state from persisted or external evidence.
6. Preserve URLs, permissions, audit semantics and keyboard operation.
7. Ship each phase as a coherent, independently reversible commit.
8. Validate every phase at 390 px, 768 px and 1440 px.
## Target measures
The roadmap is complete when the following targets are met:
| Measure | Target |
|---|---|
| Initial rows/cards in any operational list | At most 25, unless a documented compact virtualised view is used |
| Mobile status visibility | Primary record status visible on every detail page |
| Horizontal overflow | None at 360 px and above |
| Default text | At least 14 px |
| Secondary metadata | At least 12 px; exceptions require an accessibility justification |
| Touch target | At least 44 by 44 CSS px for primary mobile controls |
| Keyboard access | All actions reachable with visible focus and logical order |
| List navigation | Filter, paging and search state represented in the URL where practical |
| Dashboard comprehension | Primary operational risks and next movements visible without scrolling at 1440 × 900 |
| Browser console | No application errors during the five-minute demo |
| Performance | No avoidable rendering of more than one page of list records |
| Automated acceptance | Existing backend, frontend and Playwright gates remain green |
## Roadmap overview
| Phase | Theme | Priority | Indicative effort | Depends on |
|---|---|---:|---:|---|
| R0 | Baseline and design-system guardrails | P0 | 2–3 days | None |
| R1 | Operational lists and audit log | P0 | 5–7 days | R0 |
| R2 | Responsive shell and readable hierarchy | P0 | 4–6 days | R0 |
| R3 | Dashboard and record-detail efficiency | P1 | 5–7 days | R1, R2 |
| R4 | Guided workflows and decision surfaces | P1 | 5–7 days | R2, R3 |
| R5 | Knowledge, automation and trust signals | P1 | 3–5 days | R2 |
| R6 | Accessibility, performance and release evidence | P0 gate | 4–6 days | R1–R5 |
Indicative total: 28–41 focused engineering days. Phases can span multiple
calendar sprints, but their exit gates should not be split across releases.
## R0 — Baseline and design-system guardrails
### Objective
Create shared UI rules and reproducible measurements before changing individual
pages.
### Work packages
#### R0.1 — Visual regression baseline
- Capture authenticated reference screenshots for the seven principal routes and
the login page at 390 × 844, 768 × 1024 and 1440 × 900.
- Add stable screenshot fixtures using the deterministic seed.
- Mask only genuinely variable timestamps; do not mask operational content.
- Record viewport width, page height, visible item count and horizontal overflow.
#### R0.2 — Typography and spacing tokens
- Replace scattered sub-12 px declarations with named type tokens.
- Establish body, metadata, label, badge, table-header and navigation sizes.
- Define compact and comfortable density variants without duplicating page CSS.
- Preserve the existing petrol/teal palette and status colours.
#### R0.3 — Shared responsive patterns
- Define a mobile page-header contract: title, visible status, primary action and
overflow actions.
- Define reusable compact-list, filter-toolbar, pagination and empty-state patterns.
- Establish 44 px mobile target sizing and a consistent sticky-offset system.
### Acceptance criteria
- Visual baselines exist for all principal routes and viewports.
- No normal operational metadata is smaller than 12 px.
- Shared components document their responsive behaviour.
- Existing Playwright demo and frontend build pass unchanged.
## R1 — Operational lists and audit log
### Objective
Make high-volume operational information scannable and bounded on every device.
### Work packages
#### R1.1 — Audit API pagination and filtering
- Replace the default fixed `limit=100` response with cursor or page-based pagination.
- Add filters for date range, action, actor, entity type, entity reference and
correlation ID.
- Retain stable newest-first ordering and service-token protections.
- Return total or continuation metadata suitable for the selected paging model.
#### R1.2 — Compact audit timeline
- Render 20–25 compact events per page.
- Group correlated events and repetitive scheduled events without hiding their count.
- Move full UUIDs, before/after data and technical metadata into a details drawer.
- Keep human-readable action, actor, target, outcome and timestamp in the main row.
- Preserve direct navigation to related records.
#### R1.3 — Vehicle-list pagination
- Add server-compatible pagination to the vehicle list.
- Preserve status, location, attention and search filters across pages.
- Store filter and page state in the URL.
- Provide a prominent “attention required” view without inventing new metrics.
- Use compact mobile rows rather than full table-to-card expansion for every vehicle.
#### R1.4 — Data-quality queue controls
- Paginate the open issue list.
- Add severity and rule grouping/filtering.
- Add “previous issue” and “next issue” navigation to review pages.
- Keep scan and resolution actions permission-aware.
### Acceptance criteria
- No default list renders more than 25 records.
- Audit and vehicle pages remain below 3,500 px at the tested mobile viewport with
the deterministic seed.
- Paging and filters survive reload, back navigation and direct links.
- Empty, loading, error and end-of-results states are explicit.
- API tests cover invalid cursors/pages, combined filters and authorization.
## R2 — Responsive shell and readable hierarchy
### Objective
Reduce navigation noise and keep essential context visible on small screens.
### Work packages
#### R2.1 — Top-bar simplification
- Keep global search and current operational context primary.
- Move language, timezone and sign-out into the operator menu.
- Combine demo disclosure and demo progress into one compact control.
- Replace the visually empty mobile search field with an explicit search button or
a full-width command surface.
#### R2.2 — Mobile page actions
- Stop hiding the complete page-action region.
- Always show record status next to or below the title.
- Keep one primary action visible and move secondary actions to an accessible menu.
- Verify booking, vehicle, data-quality and automation detail headers independently.
#### R2.3 — Navigation refinement
- Review whether the desktop sidebar should remain available at wider tablet widths.
- Increase mobile navigation label size and touch area.
- Keep four or five primary destinations visible and put lower-frequency destinations
under “More” if six items cannot meet readability targets.
- Preserve current routes and role-based visibility.
#### R2.4 — Typography rollout
- Apply the R0 type tokens to badges, tables, integration cards, timelines, forms and
mobile navigation.
- Rebalance padding where larger text would otherwise increase page height excessively.
- Verify Dutch, French and English labels for clipping and wrapping.
### Acceptance criteria
- Status remains visible on every sampled mobile detail page.
- No essential action is hover-only or hidden solely because of viewport width.
- Top-bar controls fit without clipping at 390, 768 and 1440 px.
- Language changes do not introduce horizontal overflow.
- Touch-target and typography targets are met.
## R3 — Dashboard and record-detail efficiency
### Objective
Put operational decisions above supporting detail and make desktop space work harder.
### Work packages
#### R3.1 — Dashboard hierarchy
- Keep readiness and highest-severity attention items visible in the first viewport.
- Reduce the vertical weight of the demo-scenario panel after the scenario starts.
- Limit the initial attention queue and link to a complete filtered view.
- Balance “movements today” against attention content when only a few movements exist.
- Keep integrations and recent activity available without duplicating status copy.
#### R3.2 — Mobile dashboard summary
- Convert readiness into a compact, horizontally accessible summary or disclosure.
- Show the highest-priority attention items first with an explicit remaining count.
- Surface the next departure and return before secondary integration information.
#### R3.3 — Vehicle-detail workspace
- Replace the sparse overview with a two-column desktop composition.
- Surface current status, location, odometer, next booking and active attention items.
- Keep bookings, inspections, maintenance, quality issues and audit as focused tabs.
- Avoid new maintenance-domain functionality; link only to existing evidence.
#### R3.4 — Booking-detail summary
- Rebalance the facts grid so incomplete final rows do not create large empty bands.
- On mobile, show status and return readiness before secondary booking facts.
- Keep the return form close to the task entry point while retaining validation context.
### Acceptance criteria
- At 1440 × 900 the dashboard exposes readiness, urgent work and today's movement
context without scrolling.
- Sparse states remain intentional and balanced rather than appearing unfinished.
- All values remain derived from persisted data.
- Existing return and status-domain tests remain unchanged and green.
## R4 — Guided workflows and decision surfaces
### Objective
Reduce the distance between evidence and the decision an operator must make.
### Work packages
#### R4.1 — Return flow refinement
- Keep the step indicator visible while completing or reviewing a return.
- Use a compact mobile booking summary above the form.
- Present validation errors next to fields and in a short focusable summary.
- Preserve the post-submit explanation of inspection, vehicle status, quality issue,
queued automation and next-booking risk.
#### R4.2 — Duplicate-customer decision layout
- Use evidence/comparison on the left and a sticky survivor/merge preview on desktop.
- Keep matching fields collapsed by default and differences expanded.
- Keep irreversible-action language and audit preview adjacent to the merge button.
- On mobile, use a deliberate sequence: evidence, differences, survivor, preview,
confirmation.
#### R4.3 — Other data-quality resolutions
- Standardise evidence, proposed resolution, consequence and audit-preview sections.
- Keep resolve, reject and defer actions visually distinct and permission-aware.
- Provide clear success feedback and navigation to the next issue.
#### R4.4 — Guided demo integration
- Reduce competition between the guide and normal navigation.
- Persist progress without obscuring page controls.
- Make “go to this step” land on the relevant element or focused task state.
- Ensure the guide is fully keyboard-operable and usable as a mobile bottom sheet.
### Acceptance criteria
- Primary workflow action is visible or reachable with one obvious interaction.
- A user never needs to scroll past repeated explanatory content to discover the
required decision.
- Focus moves to validation failures and success results appropriately.
- The five-minute demo remains deterministic.
## R5 — Knowledge, automation and trust signals
### Objective
Make external-system health understandable to an operator without exposing irrelevant
technical detail.
### Work packages
#### R5.1 — Knowledge status semantics
- Separate provider availability, indexed-source count and last successful sync.
- Never show “0 indexed” as a healthy equivalent when the value is unknown or stale.
- Label extractive fallback answers honestly while preserving source cards.
- Reduce empty-state height and show a compact explanation of what a cited answer contains.
- Keep suggested questions concise and prioritised.
#### R5.2 — Source and freshness presentation
- Surface source title, version, section and freshness consistently.
- Keep document UUIDs and raw retrieval metadata behind technical details.
- Provide explicit grounded, insufficient-evidence and unavailable states.
#### R5.3 — Integration summary redesign
- Structure each integration around state, last success, affected workflow and next action.
- Move client IDs, raw endpoints and UUIDs to a detail disclosure.
- Remove unnecessary fixed card height, especially at tablet widths.
- Keep genuine mixed states visible without presenting them as contradictions.
#### R5.4 — Workflow evidence table
- Improve status and recency scanning.
- Distinguish “never triggered”, “no evidence yet”, “failed” and “unavailable”.
- Keep retry actions safe, audited and available only where already supported.
### Acceptance criteria
- Knowledge and integration states cannot make mutually contradictory claims.
- An operator can identify the current state and next action within one card scan.
- Technical identifiers do not dominate default views.
- RAGcore, n8n and MCP Hub timeout/unavailable contract tests stay green.
## R6 — Accessibility, performance and release evidence
### Objective
Turn the improvements into a verified, releasable quality baseline.
### Work packages
#### R6.1 — Accessibility review
- Test complete keyboard traversal of login, navigation, filters, return, merge,
knowledge, workflow retry and audit details.
- Verify focus order, focus restoration, dialog labelling and error announcements.
- Run automated accessibility checks on all principal routes.
- Manually verify status is not encoded by colour alone.
- Verify zoom at 200% and 360 px responsive reflow.
#### R6.2 — Rendering and interaction performance
- Measure list rendering before and after pagination.
- Check layout shift and interaction latency on dashboard and long-list routes.
- Ensure drawers, menus and guided-demo panels do not mount large hidden subtrees.
- Test with reduced motion and a throttled CPU profile.
#### R6.3 — Cross-browser and localisation pass
- Verify current Chrome plus one additional Chromium/Firefox-equivalent target where
supported by the test environment.
- Run Dutch, French and English visual checks at all target widths.
- Verify Europe/Brussels date and time rendering.
#### R6.4 — Final automated journey and evidence
- Extend the existing Playwright demo with pagination, mobile status and accessible
details checks.
- Capture final screenshots for all principal pages.
- Add before-and-after measurements and known PoC limitations to final evidence.
- Execute clean-checkout bootstrap, backend tests, lint, typing and frontend build.
### Acceptance criteria
- No critical or serious automated accessibility violations on principal routes.
- All target measures in this document pass.
- `docs/14-testing-and-acceptance.md` passes from a clean checkout.
- `artifacts/evidence/final-summary.md` contains the final commands, counts,
screenshots and limitations.
## Suggested release slices
### Release A — Operational scale
Contains R0 and R1. This release eliminates the most severe scroll and list-density
problems without materially changing workflow structure.
Release gate:
- paginated audit, vehicles and data-quality queues;
- URL-backed filters;
- unchanged audit and authorization semantics;
- visual regression baseline green.
### Release B — Responsive operations
Contains R2 and R3. This release improves navigation, typography, dashboard hierarchy
and detail-page use of space.
Release gate:
- visible mobile statuses and primary actions;
- readable typography and touch targets;
- dashboard first-viewport target met;
- Dutch, French and English responsive checks green.
### Release C — Guided decisions and trust
Contains R4 and R5. This release refines the return, merge, knowledge, automation and
demo-guide experiences.
Release gate:
- decision actions remain near their evidence;
- honest and non-contradictory external health states;
- five-minute demo passes end to end.
### Release D — Quality certification
Contains R6 and only defects found by its gates. It adds no new product scope.
Release gate:
- full clean-checkout acceptance;
- accessibility and performance targets met;
- final evidence updated;
- release tag and deployed revision recorded.
## Implementation sequence and dependencies
```text
R0 shared tokens and baselines
├─ R1 pagination and compact lists ─┐
└─ R2 responsive shell and type ───┼─ R3 dashboard/details ─ R4 workflows
└─ R5 trust surfaces
R1 + R2 + R3 + R4 + R5 ──────────────────────────────── R6 release gate
```
R1 and R2 may be developed in parallel after R0. R3 should consume both shared list
and responsive patterns. R4 depends on the new page-header and detail hierarchy. R5 can
start after R2 but must share its disclosure and status patterns. R6 is a gate, not a
cleanup bucket; defects discovered there return to the owning phase.
## Per-phase engineering checklist
Every phase must include:
1. a short before-state measurement;
2. API and data-contract impact assessment;
3. implementation using shared components where applicable;
4. unit/API tests for changed contracts;
5. Playwright coverage for the changed user journey;
6. manual checks at 390, 768 and 1440 px in all supported languages;
7. accessibility and console check;
8. updated evidence and `PROJECT_STATE.md` entry;
9. one coherent commit after validation passes;
10. deployment verification before starting the next release slice.
## Risks and mitigations
| Risk | Mitigation |
|---|---|
| Pagination changes API consumers | Add pagination metadata without silently changing service-token/MCP response contracts; version only if necessary |
| Compact layouts hide evidence | Use drawers and disclosures, preserving direct access and auditability |
| Larger type increases page height | Combine type changes with density and hierarchy work, never shrink text again |
| Sticky UI covers content on mobile | Use shared top/bottom offsets and test keyboard/zoom states |
| Visual snapshots become brittle | Seed deterministic data and mask only true timestamp volatility |
| External health data is stale | Show last successful evidence and distinguish unknown from healthy |
| Roadmap drifts into new product scope | Check every work package against `docs/01-scope-and-non-goals.md` and `docs/deferred.md` |
## Definition of roadmap completion
This roadmap is complete only when Releases A through D are deployed and verified,
all target measures pass, the original five-minute demo remains green, and the final
evidence records the exact deployed revision. Completing only the visual styling or one
high-priority page does not complete the roadmap.