# UI/UX Incremental Work Plan

## Objective

Optimize the existing vehicle platform one verified step at a time until the desktop and mobile experiences form one modern, concise, high-quality product system.

## Working rules

- Preserve business behavior, route structure, permissions, and existing product copy.
- Improve high-frequency tasks before low-frequency administration surfaces.
- Design mobile workflows for touch instead of shrinking desktop layouts.
- Use one shared token foundation for color, typography, spacing, controls, focus, and motion.
- Complete each stage with rendered desktop/mobile evidence, interaction checks, and relevant automated tests.

## Page priority

| Priority | Routes | Primary UX goal |
| --- | --- | --- |
| P0 | Global monitor, vehicle search | Fast fleet awareness and vehicle lookup |
| P1 | Track playback, history, mileage | Clear query setup, result verification, and tool hierarchy |
| P2 | Alerts, access, operations | Efficient exception triage and evidence review |
| P3 | Account management | Safe, understandable administration workflows |

## Execution stages

### 1. Current-state audit

- [x] Confirm all nine application routes.
- [x] Inspect current worktree and preserve unrelated `.codex-audit/` artifacts.
- [x] Identify the three-level style cascade and approximately 42,000 lines of existing CSS as the main regression risk.
- [x] Review existing desktop/mobile route screenshots and the Semi-inspired reference concepts.

### 2. Shared design foundation

- [x] Add shared semantic color, typography, spacing, radius, control, focus, and motion tokens.
- [x] Keep compatibility aliases so existing shared components migrate without behavior changes.
- [x] Add a global 14 px control baseline, visible keyboard focus, text rendering, and reduced-motion behavior.
- [x] Move remaining high-frequency hard-coded values to semantic tokens while each page is touched.

### 3. P0 core experience

- [x] Connect desktop monitor filters, metrics, map, and vehicle rail into one workspace.
- [x] Replace monitor metric gradients with an open white information rail and readable state-colored values.
- [x] Convert desktop vehicle lookup into a connected search, metric, and directory workspace.
- [x] Rebuild mobile vehicle lookup around persistent search, editable scope, three metrics, open rows, and bottom navigation.
- [x] Fix mobile Semi button flex behavior that compressed the search copy.
- [x] Fix mobile metric inheritance that collapsed descriptions and values into one row.

### 4. P1 query and playback workflows

- [x] Track playback: simplify vehicle selection, source confirmation, playback controls, and empty/result transitions.
- [x] History: align query range, selected vehicles, result tools, and export feedback.
- [x] Mileage: improve date/vehicle scope, comparison-table readability, and mobile horizontal exploration.
- [x] Verify all three mobile workbench launchers, open states, accessible names, viewport fit, and 44/48 px touch baselines at 390 × 844.

### 5. P2/P3 governance workflows

- [x] Alerts: strengthen event priority, status actions, filter feedback, and mobile queue scanning.
- [x] Access: simplify coverage-to-difference drill-down and governance actions.
- [x] Operations: clarify health evidence, reconciliation priority, and refresh feedback.
- [x] Users: make customer scope, grants, creation, and destructive actions easier to understand.
- [x] Verify the four evidence/detail sheets open from their mobile rows without changing API, permissions, or mutation behavior.
- [x] Compare each implemented mobile route against its accepted full-page concept.

### 6. Final cross-route verification

- [x] Verify every route at 1440 × 900 and 390 × 844.
- [x] Confirm zero accidental horizontal overflow and no clipped primary controls.
- [x] Verify all core filter, selection, detail, pagination, and action paths.
- [x] Audit touch targets, keyboard focus, reduced motion, loading, empty, error, and success states.
- [x] Run the complete test suite and production build gate.

## Final verification record

- Routes: monitor, vehicles, tracks, history, statistics, alerts, access, operations, and users.
- Desktop viewport: 1440 × 900; all nine routes rendered without horizontal overflow or visible route error states.
- Mobile viewport: 390 × 844; all nine routes rendered at exactly 390 px document width.
- Mobile target audit: no visible button, link, tab, input, combobox, or role-button had both dimensions below 44 px after the final pagination, monitor entry, and track tool corrections.
- Governance interactions: alert evidence, access source evidence, reconciliation evidence/action, and customer authorization details opened successfully.
- Automated tests: 73 files and 377 tests passed.
- Production gate: TypeScript, Vite production build, artifact preparation, and `verify-build` passed with `web_build_gate=ok`.
- Source hygiene: `git diff --check` passed; unrelated `.codex-audit/` artifacts were left untouched.

## Stage acceptance checklist

Every page stage must provide:

1. A direct comparison against its accepted concept or the shared design-system reference.
2. At least five checks covering hierarchy, typography, color, spacing, responsive behavior, icons, or motion.
3. A desktop and mobile browser screenshot at the target viewport.
4. A working core task path with visible state change.
5. Relevant automated tests and a clean `git diff --check`.

Stages 1–6 are complete and verified.