lingniu-vehicle-ingest/vehicle-data-platform/docs/design/ui-ux-20260720/WORKPLAN.md

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

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

2. Shared design foundation

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

3. P0 core experience

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

4. P1 query and playback workflows

• Track playback: simplify vehicle selection, source confirmation, playback controls, and empty/result transitions.
• History: align query range, selected vehicles, result tools, and export feedback.
• Mileage: improve date/vehicle scope, comparison-table readability, and mobile horizontal exploration.
• 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

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

6. Final cross-route verification

• Verify every route at 1440 × 900 and 390 × 844.
• Confirm zero accidental horizontal overflow and no clipped primary controls.
• Verify all core filter, selection, detail, pagination, and action paths.
• Audit touch targets, keyboard focus, reduced motion, loading, empty, error, and success states.
• 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.