egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: UX design audit cleanup #162

New Issue
Closed
opened 2026-02-13 22:21:41 +00:00 by egullickson · 3 comments
egullickson commented 2026-02-13 22:21:41 +00:00
Owner
Copy Link

Summary

Clean up findings from a comprehensive UX design audit of MotoVaultPro. The audit identified 20 issues across 4 severity levels covering mobile navigation bugs, content display issues, layout improvements, and UI polish items.

Severity Breakdown

Severity Count Sub-Issues
Critical 3 #163, #164, #165
High 5 #166, #167, #168, #169, #170
Medium 6 #171, #172, #173, #174, #175, #176
Minor 5 #177, #178, #179, #180, #181

Sub-Issues (ordered by priority)

Critical

  • #163 - Fix mobile routing - direct URL navigation renders Dashboard instead of correct page
  • #164 - Add Maintenance to mobile bottom-sheet More menu
  • #165 - Fix null model display on Settings vehicle list

High

  • #166 - Enrich Dashboard with meaningful content
  • #167 - Vehicle cards show Year Make Model and hide empty VIN
  • #168 - Fuel Logs default to list view instead of form-first
  • #169 - Add Maintenance page title and remove duplicate vehicle dropdown
  • #170 - FAB button fix overlap with content and bottom nav on mobile

Medium

  • #171 - Standardize empty field display across all views
  • #172 - Improve document card with upload date and file type icon
  • #173 - Remove redundant Stations entry from mobile More menu
  • #174 - Differentiate identical maintenance schedule names
  • #175 - Remove Insurance default bias from Add Document modal
  • #176 - Add desktop sidebar collapse to icon-only mode

Minor

  • #177 - Header greeting use display name instead of email
  • #178 - Remove dashboard auto-refresh footer text
  • #179 - Add call-to-action links in zero-state stats cards
  • #180 - Hide notification bell if non-functional
  • #181 - Differentiate Stations icon from Fuel Logs in bottom nav

Acceptance Criteria

  • All 20 findings addressed per sub-issue acceptance criteria
  • Mobile + Desktop tested for each change
  • No regressions in existing functionality
## Summary Clean up findings from a comprehensive UX design audit of MotoVaultPro. The audit identified 20 issues across 4 severity levels covering mobile navigation bugs, content display issues, layout improvements, and UI polish items. ## Severity Breakdown | Severity | Count | Sub-Issues | |----------|-------|------------| | Critical | 3 | #163, #164, #165 | | High | 5 | #166, #167, #168, #169, #170 | | Medium | 6 | #171, #172, #173, #174, #175, #176 | | Minor | 5 | #177, #178, #179, #180, #181 | ## Sub-Issues (ordered by priority) **Critical** - [ ] #163 - Fix mobile routing - direct URL navigation renders Dashboard instead of correct page - [ ] #164 - Add Maintenance to mobile bottom-sheet More menu - [ ] #165 - Fix null model display on Settings vehicle list **High** - [ ] #166 - Enrich Dashboard with meaningful content - [ ] #167 - Vehicle cards show Year Make Model and hide empty VIN - [ ] #168 - Fuel Logs default to list view instead of form-first - [ ] #169 - Add Maintenance page title and remove duplicate vehicle dropdown - [ ] #170 - FAB button fix overlap with content and bottom nav on mobile **Medium** - [ ] #171 - Standardize empty field display across all views - [ ] #172 - Improve document card with upload date and file type icon - [ ] #173 - Remove redundant Stations entry from mobile More menu - [ ] #174 - Differentiate identical maintenance schedule names - [ ] #175 - Remove Insurance default bias from Add Document modal - [ ] #176 - Add desktop sidebar collapse to icon-only mode **Minor** - [ ] #177 - Header greeting use display name instead of email - [ ] #178 - Remove dashboard auto-refresh footer text - [ ] #179 - Add call-to-action links in zero-state stats cards - [ ] #180 - Hide notification bell if non-functional - [ ] #181 - Differentiate Stations icon from Fuel Logs in bottom nav ## Acceptance Criteria - All 20 findings addressed per sub-issue acceptance criteria - Mobile + Desktop tested for each change - No regressions in existing functionality
egullickson added the
status
ready
type
chore
 labels 2026-02-13 22:21:47 +00:00
egullickson added this to the Sprint 2026-02-02 milestone 2026-02-13 22:21:50 +00:00
egullickson added
status
in-progress
 and removed
status
ready
 labels 2026-02-13 22:30:10 +00:00
egullickson commented 2026-02-13 22:36:38 +00:00
Author
Owner
Copy Link

Plan: UX Design Audit Cleanup (#162)

Phase: Planning | Agent: Orchestrator | Status: AWAITING_REVIEW

Codebase Analysis Summary

Thorough exploration of all affected frontend areas completed. Key architectural findings:

Area Key Files Findings
Mobile Navigation App.tsx, BottomNavigation.tsx, HamburgerDrawer.tsx, navigation.ts Mobile uses Zustand state-based nav, NOT React Router. URLs never sync to mobile screen state.
Dashboard DashboardScreen.tsx, SummaryCards.tsx, QuickActions.tsx, useDashboardData.ts Footer says "2 minutes" (not 7). Data already fetched for vehicles, fuel, maintenance.
Vehicle Display VehicleCard.tsx, VehicleMobileCard.tsx, SettingsPage.tsx, vehicleLabel.ts 7+ locations with inconsistent null handling. Shared utility exists in documents but unused elsewhere.
Fuel Logs FuelLogsPage.tsx, FuelLogForm.tsx, FuelLogsList.tsx Two-column layout: form LEFT, list RIGHT. Form always visible.
Maintenance MaintenancePage.tsx, MaintenanceSchedulesList.tsx No page title. Vehicle dropdown duplicated in page AND forms. Schedules show category only.
Documents DocumentsPage.tsx, DocumentForm.tsx, DocumentCardMetadata.tsx Default type hardcoded to 'insurance'. No upload date or file type icon shown.
Header Layout.tsx, NotificationBell.tsx Greeting already does user?.name || user?.email. Bell IS fully functional with popover + API.
Sidebar Layout.tsx 256px, slides fully off-screen. No icon-only intermediate state.

Key Decisions (No Decision Critic Needed)

  1. Mobile routing (#163): Sync browser URL to Zustand activeScreen on mount/URL change. No architecture rewrite needed.
  2. Dashboard content (#166): Add "Recent Activity" feed using existing useDashboardData hook data (fuel logs + maintenance). Minimal new API work.
  3. Sidebar collapse (#176): Add icon-only mode (64px) as intermediate state via CSS width transition with localStorage persistence.
  4. Notification bell (#180): Bell IS functional -- investigate empty state UX. Show "No notifications" message instead of appearing broken.
  5. Header greeting (#177): Auth0 user.name may not be populated. Use user.given_name or parse first name from user.name.
  6. Vehicle display (#165, #167, #171): Promote existing getVehicleLabel() from documents/utils/ to core/utils/ and use across all 10+ locations.

Milestones (1:1 with Sub-Issues)

Phase 1: Foundation (shared utilities and critical fixes)

Milestone 1 -- #165: Fix null model display on Settings vehicle list

  • Promote getVehicleLabel() from frontend/src/features/documents/utils/vehicleLabel.ts to frontend/src/core/utils/vehicleDisplay.ts
  • Add getVehicleSubtitle() helper for Year Make Model formatting with null safety
  • Replace direct ${year} ${make} ${model} concatenation in:
    • SettingsPage.tsx:378 (desktop)
    • MobileSettingsScreen.tsx:376 (mobile)
    • VehicleAttention.tsx:107 (dashboard)
    • VehicleDetailPage.tsx:376 (detail page)
  • Files: core/utils/vehicleDisplay.ts (new), SettingsPage.tsx, MobileSettingsScreen.tsx, VehicleAttention.tsx, VehicleDetailPage.tsx
  • Test: No null text visible anywhere. Consistent "Unknown Model" fallback.

Milestone 2 -- #163: Fix mobile routing

  • In App.tsx, add useEffect that reads current browser URL path on mount and maps it to the correct MobileScreen value in Zustand store
  • Create route-to-screen mapping: /garage/dashboard -> Dashboard, /garage/vehicles -> Vehicles, /garage/fuel-logs -> Log Fuel, /garage/maintenance -> Maintenance, /garage/documents -> Documents, /garage/stations -> Stations, /garage/settings -> Settings
  • Also sync screen changes back to browser URL via window.history.replaceState() for bookmark support
  • Files: App.tsx, core/store/navigation.ts
  • Test: Direct URL nav on mobile renders correct page. Refresh preserves route. Desktop unaffected.

Milestone 3 -- #164: Add Maintenance to mobile More menu

  • Add { screen: 'Maintenance', label: 'Maintenance', icon: <BuildRoundedIcon /> } to menuItems array in HamburgerDrawer.tsx
  • Place after Documents for logical grouping
  • Files: HamburgerDrawer.tsx
  • Test: Maintenance appears in More menu. Tapping navigates correctly.

Phase 2: Navigation cleanup

Milestone 4 -- #173: Remove redundant Stations from More menu

  • Remove { screen: 'Stations', label: 'Stations', icon: <LocalGasStationRoundedIcon /> } from menuItems in HamburgerDrawer.tsx
  • Stations remains accessible via bottom nav
  • Files: HamburgerDrawer.tsx
  • Test: Stations only in bottom nav, not More menu. All pages still reachable.

Milestone 5 -- #181: Differentiate Stations icon from Fuel Logs

  • Change Stations bottom nav icon from LocalGasStationRoundedIcon to PlaceRoundedIcon (map pin) in BottomNavigation.tsx rightNavItems
  • Also update HamburgerDrawer.tsx if Stations entry remains after Milestone 4 (it won't)
  • Files: BottomNavigation.tsx
  • Test: Stations icon clearly different from fuel-related icons.

Milestone 6 -- #170: Fix FAB overlap with content and bottom nav

  • Adjust FAB bottom position in BottomNavigation.tsx from calc(64px + env(...) - 26px) to calc(64px + env(...) + 4px) to raise above nav labels
  • Add pb-24 (6rem) to mobile content container in Layout.tsx (currently pb-20) to ensure content clears both bottom nav and FAB
  • Files: BottomNavigation.tsx, Layout.tsx
  • Test: FAB does not overlap bottom nav labels or dashboard content. Content scrolls clear of FAB.

Phase 3: Vehicle display consistency

Milestone 7 -- #167: Vehicle cards show Year Make Model and hide empty VIN

  • In VehicleCard.tsx: Add Year Make Model subtitle line below display name using getVehicleSubtitle(). Conditionally render VIN only when non-empty.
  • In VehicleMobileCard.tsx: Same treatment -- subtitle and conditional VIN.
  • Files: VehicleCard.tsx, VehicleMobileCard.tsx
  • Test: Cards show "2025 Toyota Camry" subtitle. Empty VIN hidden.

Milestone 8 -- #171: Standardize empty field display across all views

  • Adopt "hide empty field" pattern (Option B) for list cards -- don't show rows with no data
  • Keep "Not provided" italic gray pattern on detail pages (already exists in VehicleDetailPage.tsx)
  • Fix VehicleCard.tsx VIN display: wrap in conditional {vehicle.vin && <Typography>VIN: {vehicle.vin}</Typography>}
  • Audit all card views for empty field handling
  • Files: VehicleCard.tsx, VehicleMobileCard.tsx, VehicleDetailPage.tsx (verify), SettingsPage.tsx, MobileSettingsScreen.tsx
  • Test: No blank "Label:" rows. Detail pages show "Not provided". Consistent across all views.

Phase 4: Dashboard improvements

Milestone 9 -- #178: Remove dashboard auto-refresh footer text

  • Delete the footer div (lines 139-143) in DashboardScreen.tsx containing "Dashboard updates every 2 minutes"
  • Files: DashboardScreen.tsx
  • Test: No developer-facing text visible on dashboard.

Milestone 10 -- #179: Add CTA links in zero-state stats cards

  • Modify SummaryCards.tsx: When card value is 0, show a subtle link below the count
    • "Upcoming Maintenance: 0" -> Link "Schedule maintenance" to /garage/maintenance
    • "Recent Fuel Logs: 0" -> Link "Log your first fill-up" to /garage/fuel-logs
    • "Total Vehicles: 0" -> Link "Add a vehicle" to /garage/vehicles
  • Non-zero values render normally without links
  • On mobile, use onNavigate prop to trigger Zustand screen change instead of router link
  • Files: SummaryCards.tsx
  • Test: Zero-state cards show CTA links. Non-zero cards display normally. Links navigate correctly.

Milestone 11 -- #166: Enrich Dashboard with meaningful content

  • Add "Recent Activity" section below VehiclesNeedingAttention in DashboardScreen.tsx
  • Create RecentActivity.tsx component that combines latest fuel logs and maintenance records into a chronological feed (last 7 items)
  • Data already available from useDashboardData hook (vehicles, fuelLogs, maintenance schedules)
  • Each feed item shows: icon (fuel pump / wrench), vehicle name, description, relative timestamp
  • Empty state: "No recent activity" with subtle guidance text
  • Responsive: Single column on mobile, wider on desktop
  • Files: DashboardScreen.tsx, features/dashboard/components/RecentActivity.tsx (new)
  • Test: Dashboard shows recent activity. Empty state graceful. Mobile + desktop layouts work.

Phase 5: Fuel Logs restructure

Milestone 12 -- #168: Fuel Logs default to list view

  • Restructure FuelLogsPage.tsx layout:
    • Primary view: FuelStatsCard at top, then FuelLogsList as main content
    • "Add Fuel Log" button in page header opens FuelLogForm in a Dialog (modal)
    • Remove two-column layout; list takes full width
  • Create AddFuelLogDialog.tsx wrapping existing FuelLogForm in MUI Dialog (similar to AddDocumentDialog.tsx pattern)
  • Mobile: Same pattern -- stats at top, list below, FAB or button triggers form dialog
  • Files: FuelLogsPage.tsx, features/fuel-logs/components/AddFuelLogDialog.tsx (new), FuelLogForm.tsx (minor: add onSuccess callback for dialog close)
  • Test: Page opens to list view. Button opens form modal. Stats visible. Mobile + desktop work.

Phase 6: Maintenance fixes

Milestone 13 -- #169: Add Maintenance page title and remove duplicate dropdown

  • Add <Typography variant="h5" fontWeight={600}>Maintenance</Typography> at top of MaintenancePage.tsx before vehicle selector (consistent with Documents page pattern)
  • Remove vehicle FormControl/Select from inside MaintenanceRecordForm.tsx and MaintenanceScheduleForm.tsx
  • Pass selectedVehicleId as prop from page-level selector to forms
  • Same treatment for MaintenanceMobileScreen.tsx
  • Files: MaintenancePage.tsx, MaintenanceMobileScreen.tsx, MaintenanceRecordForm.tsx, MaintenanceScheduleForm.tsx
  • Test: "Maintenance" h1 visible. Single vehicle dropdown at page level. Forms use selected vehicle.

Milestone 14 -- #174: Differentiate maintenance schedule names

  • In MaintenanceSchedulesList.tsx, change primary display from getCategoryDisplayName(schedule.category) to show the service type prominently
  • Display format: {serviceType} - {category} (e.g., "Fluid-Differential - Routine Maintenance")
  • If service type is empty, fall back to category name alone
  • Files: MaintenanceSchedulesList.tsx
  • Test: Schedules visually distinguishable. Service type is primary identifier.

Phase 7: Document improvements

Milestone 15 -- #175: Remove Insurance default bias from Add Document modal

  • In DocumentForm.tsx, change initial state from documentType: 'insurance' to documentType: '' (empty)
  • Add placeholder/prompt: "Select a document type" in the Select component
  • Insurance-specific fields only render when documentType === 'insurance'
  • Add form validation: require document type selection before submit
  • Files: DocumentForm.tsx
  • Test: Modal opens with no type selected. Insurance fields hidden until selected. Form validates type selection.

Milestone 16 -- #172: Improve document card with upload date and file type icon

  • In DocumentCardMetadata.tsx: Add createdAt display as "Uploaded {relative date}" (e.g., "Uploaded 3 days ago")
  • Add file type icon based on contentType field: PDF icon for application/pdf, Image icon for image/*, Generic file icon for others
  • Use MUI icons: PictureAsPdfRoundedIcon, ImageRoundedIcon, InsertDriveFileRoundedIcon
  • Place icon and upload date in card header area
  • Files: DocumentCardMetadata.tsx, DocumentsPage.tsx (card rendering), DocumentsMobileScreen.tsx
  • Test: Cards show upload date and file type icon. Cards remain clean and scannable.

Phase 8: Header and minor polish

Milestone 17 -- #177: Header greeting use display name

  • In Layout.tsx, change greeting logic from user?.name || user?.email to: 
    const displayName = user?.given_name || user?.name?.split(' ')[0] || user?.nickname || user?.email;
  • Extract first name for compact greeting: "Welcome back, Eric"
  • Files: Layout.tsx
  • Test: Greeting shows first name. Falls back gracefully to email if no name available.

Milestone 18 -- #180: Hide notification bell if non-functional

  • Investigation reveals notification bell IS fully functional (popover, API, mark-as-read)
  • The "non-functional" perception is likely due to empty notification state showing nothing
  • Fix: In NotificationBell.tsx, ensure empty state shows "No notifications" message in popover
  • If popover doesn't open (rendering bug), debug and fix
  • Files: NotificationBell.tsx
  • Test: Bell click opens popover. Empty state shows "No notifications" message. Existing notifications display correctly.

Milestone 19 -- #176: Add desktop sidebar collapse to icon-only mode

  • In Layout.tsx, add three sidebar states: expanded (256px), collapsed (64px), hidden (0px)
  • Collapsed state shows navigation icons only without text labels
  • Add MUI Tooltip on each icon in collapsed mode for discoverability
  • Toggle button cycles: expanded -> collapsed -> hidden -> expanded (or just expanded <-> collapsed)
  • Persist state in localStorage for session persistence
  • Adjust main content margin-left transition to match sidebar width
  • Files: Layout.tsx
  • Test: Hamburger toggles between expanded/collapsed. Icons visible in collapsed mode. Tooltips work. Session persistence works.

Execution Order Rationale

  1. Phase 1 (Foundation): Creates shared utilities used by later milestones. Critical routing fix unblocks testing.
  2. Phase 2 (Navigation): Quick wins that improve mobile UX immediately.
  3. Phase 3 (Vehicle display): Builds on Phase 1 utility.
  4. Phase 4 (Dashboard): Independent, can be parallelized with Phase 3.
  5. Phase 5 (Fuel Logs): Independent, significant restructure.
  6. Phase 6 (Maintenance): Independent, moderate changes.
  7. Phase 7 (Documents): Independent, moderate changes.
  8. Phase 8 (Header/Minor): Lowest priority, smallest changes.

Branch Strategy

Risk Notes

  • #163 (Mobile routing): Highest complexity. Zustand/URL sync must not break existing navigation flows.
  • #168 (Fuel Logs): Significant layout restructure. Existing form logic must work in dialog context.
  • #176 (Sidebar): CSS transitions need careful testing at various viewport widths.
  • #166 (Dashboard): New component. Must handle loading/error/empty states.

Verdict: AWAITING_REVIEW | Next: Plan review cycle (QR plan-completeness -> TW plan-scrub -> QR plan-code -> QR plan-docs)

## Plan: UX Design Audit Cleanup (#162) **Phase**: Planning | **Agent**: Orchestrator | **Status**: AWAITING_REVIEW --- ### Codebase Analysis Summary Thorough exploration of all affected frontend areas completed. Key architectural findings: | Area | Key Files | Findings | |------|-----------|----------| | Mobile Navigation | `App.tsx`, `BottomNavigation.tsx`, `HamburgerDrawer.tsx`, `navigation.ts` | Mobile uses Zustand state-based nav, NOT React Router. URLs never sync to mobile screen state. | | Dashboard | `DashboardScreen.tsx`, `SummaryCards.tsx`, `QuickActions.tsx`, `useDashboardData.ts` | Footer says "2 minutes" (not 7). Data already fetched for vehicles, fuel, maintenance. | | Vehicle Display | `VehicleCard.tsx`, `VehicleMobileCard.tsx`, `SettingsPage.tsx`, `vehicleLabel.ts` | 7+ locations with inconsistent null handling. Shared utility exists in documents but unused elsewhere. | | Fuel Logs | `FuelLogsPage.tsx`, `FuelLogForm.tsx`, `FuelLogsList.tsx` | Two-column layout: form LEFT, list RIGHT. Form always visible. | | Maintenance | `MaintenancePage.tsx`, `MaintenanceSchedulesList.tsx` | No page title. Vehicle dropdown duplicated in page AND forms. Schedules show category only. | | Documents | `DocumentsPage.tsx`, `DocumentForm.tsx`, `DocumentCardMetadata.tsx` | Default type hardcoded to 'insurance'. No upload date or file type icon shown. | | Header | `Layout.tsx`, `NotificationBell.tsx` | Greeting already does `user?.name \|\| user?.email`. Bell IS fully functional with popover + API. | | Sidebar | `Layout.tsx` | 256px, slides fully off-screen. No icon-only intermediate state. | ### Key Decisions (No Decision Critic Needed) 1. **Mobile routing (#163)**: Sync browser URL to Zustand `activeScreen` on mount/URL change. No architecture rewrite needed. 2. **Dashboard content (#166)**: Add "Recent Activity" feed using existing `useDashboardData` hook data (fuel logs + maintenance). Minimal new API work. 3. **Sidebar collapse (#176)**: Add icon-only mode (64px) as intermediate state via CSS width transition with localStorage persistence. 4. **Notification bell (#180)**: Bell IS functional -- investigate empty state UX. Show "No notifications" message instead of appearing broken. 5. **Header greeting (#177)**: Auth0 `user.name` may not be populated. Use `user.given_name` or parse first name from `user.name`. 6. **Vehicle display (#165, #167, #171)**: Promote existing `getVehicleLabel()` from `documents/utils/` to `core/utils/` and use across all 10+ locations. --- ### Milestones (1:1 with Sub-Issues) #### Phase 1: Foundation (shared utilities and critical fixes) **Milestone 1 -- #165: Fix null model display on Settings vehicle list** - Promote `getVehicleLabel()` from `frontend/src/features/documents/utils/vehicleLabel.ts` to `frontend/src/core/utils/vehicleDisplay.ts` - Add `getVehicleSubtitle()` helper for Year Make Model formatting with null safety - Replace direct `${year} ${make} ${model}` concatenation in: - `SettingsPage.tsx:378` (desktop) - `MobileSettingsScreen.tsx:376` (mobile) - `VehicleAttention.tsx:107` (dashboard) - `VehicleDetailPage.tsx:376` (detail page) - Files: `core/utils/vehicleDisplay.ts` (new), `SettingsPage.tsx`, `MobileSettingsScreen.tsx`, `VehicleAttention.tsx`, `VehicleDetailPage.tsx` - Test: No `null` text visible anywhere. Consistent "Unknown Model" fallback. **Milestone 2 -- #163: Fix mobile routing** - In `App.tsx`, add `useEffect` that reads current browser URL path on mount and maps it to the correct `MobileScreen` value in Zustand store - Create route-to-screen mapping: `/garage/dashboard` -> `Dashboard`, `/garage/vehicles` -> `Vehicles`, `/garage/fuel-logs` -> `Log Fuel`, `/garage/maintenance` -> `Maintenance`, `/garage/documents` -> `Documents`, `/garage/stations` -> `Stations`, `/garage/settings` -> `Settings` - Also sync screen changes back to browser URL via `window.history.replaceState()` for bookmark support - Files: `App.tsx`, `core/store/navigation.ts` - Test: Direct URL nav on mobile renders correct page. Refresh preserves route. Desktop unaffected. **Milestone 3 -- #164: Add Maintenance to mobile More menu** - Add `{ screen: 'Maintenance', label: 'Maintenance', icon: <BuildRoundedIcon /> }` to `menuItems` array in `HamburgerDrawer.tsx` - Place after Documents for logical grouping - Files: `HamburgerDrawer.tsx` - Test: Maintenance appears in More menu. Tapping navigates correctly. #### Phase 2: Navigation cleanup **Milestone 4 -- #173: Remove redundant Stations from More menu** - Remove `{ screen: 'Stations', label: 'Stations', icon: <LocalGasStationRoundedIcon /> }` from `menuItems` in `HamburgerDrawer.tsx` - Stations remains accessible via bottom nav - Files: `HamburgerDrawer.tsx` - Test: Stations only in bottom nav, not More menu. All pages still reachable. **Milestone 5 -- #181: Differentiate Stations icon from Fuel Logs** - Change Stations bottom nav icon from `LocalGasStationRoundedIcon` to `PlaceRoundedIcon` (map pin) in `BottomNavigation.tsx` rightNavItems - Also update `HamburgerDrawer.tsx` if Stations entry remains after Milestone 4 (it won't) - Files: `BottomNavigation.tsx` - Test: Stations icon clearly different from fuel-related icons. **Milestone 6 -- #170: Fix FAB overlap with content and bottom nav** - Adjust FAB `bottom` position in `BottomNavigation.tsx` from `calc(64px + env(...) - 26px)` to `calc(64px + env(...) + 4px)` to raise above nav labels - Add `pb-24` (6rem) to mobile content container in `Layout.tsx` (currently `pb-20`) to ensure content clears both bottom nav and FAB - Files: `BottomNavigation.tsx`, `Layout.tsx` - Test: FAB does not overlap bottom nav labels or dashboard content. Content scrolls clear of FAB. #### Phase 3: Vehicle display consistency **Milestone 7 -- #167: Vehicle cards show Year Make Model and hide empty VIN** - In `VehicleCard.tsx`: Add Year Make Model subtitle line below display name using `getVehicleSubtitle()`. Conditionally render VIN only when non-empty. - In `VehicleMobileCard.tsx`: Same treatment -- subtitle and conditional VIN. - Files: `VehicleCard.tsx`, `VehicleMobileCard.tsx` - Test: Cards show "2025 Toyota Camry" subtitle. Empty VIN hidden. **Milestone 8 -- #171: Standardize empty field display across all views** - Adopt "hide empty field" pattern (Option B) for list cards -- don't show rows with no data - Keep "Not provided" italic gray pattern on detail pages (already exists in `VehicleDetailPage.tsx`) - Fix `VehicleCard.tsx` VIN display: wrap in conditional `{vehicle.vin && <Typography>VIN: {vehicle.vin}</Typography>}` - Audit all card views for empty field handling - Files: `VehicleCard.tsx`, `VehicleMobileCard.tsx`, `VehicleDetailPage.tsx` (verify), `SettingsPage.tsx`, `MobileSettingsScreen.tsx` - Test: No blank "Label:" rows. Detail pages show "Not provided". Consistent across all views. #### Phase 4: Dashboard improvements **Milestone 9 -- #178: Remove dashboard auto-refresh footer text** - Delete the footer div (lines 139-143) in `DashboardScreen.tsx` containing "Dashboard updates every 2 minutes" - Files: `DashboardScreen.tsx` - Test: No developer-facing text visible on dashboard. **Milestone 10 -- #179: Add CTA links in zero-state stats cards** - Modify `SummaryCards.tsx`: When card value is 0, show a subtle link below the count - "Upcoming Maintenance: 0" -> Link "Schedule maintenance" to `/garage/maintenance` - "Recent Fuel Logs: 0" -> Link "Log your first fill-up" to `/garage/fuel-logs` - "Total Vehicles: 0" -> Link "Add a vehicle" to `/garage/vehicles` - Non-zero values render normally without links - On mobile, use `onNavigate` prop to trigger Zustand screen change instead of router link - Files: `SummaryCards.tsx` - Test: Zero-state cards show CTA links. Non-zero cards display normally. Links navigate correctly. **Milestone 11 -- #166: Enrich Dashboard with meaningful content** - Add "Recent Activity" section below VehiclesNeedingAttention in `DashboardScreen.tsx` - Create `RecentActivity.tsx` component that combines latest fuel logs and maintenance records into a chronological feed (last 7 items) - Data already available from `useDashboardData` hook (vehicles, fuelLogs, maintenance schedules) - Each feed item shows: icon (fuel pump / wrench), vehicle name, description, relative timestamp - Empty state: "No recent activity" with subtle guidance text - Responsive: Single column on mobile, wider on desktop - Files: `DashboardScreen.tsx`, `features/dashboard/components/RecentActivity.tsx` (new) - Test: Dashboard shows recent activity. Empty state graceful. Mobile + desktop layouts work. #### Phase 5: Fuel Logs restructure **Milestone 12 -- #168: Fuel Logs default to list view** - Restructure `FuelLogsPage.tsx` layout: - Primary view: `FuelStatsCard` at top, then `FuelLogsList` as main content - "Add Fuel Log" button in page header opens `FuelLogForm` in a `Dialog` (modal) - Remove two-column layout; list takes full width - Create `AddFuelLogDialog.tsx` wrapping existing `FuelLogForm` in MUI `Dialog` (similar to `AddDocumentDialog.tsx` pattern) - Mobile: Same pattern -- stats at top, list below, FAB or button triggers form dialog - Files: `FuelLogsPage.tsx`, `features/fuel-logs/components/AddFuelLogDialog.tsx` (new), `FuelLogForm.tsx` (minor: add onSuccess callback for dialog close) - Test: Page opens to list view. Button opens form modal. Stats visible. Mobile + desktop work. #### Phase 6: Maintenance fixes **Milestone 13 -- #169: Add Maintenance page title and remove duplicate dropdown** - Add `<Typography variant="h5" fontWeight={600}>Maintenance</Typography>` at top of `MaintenancePage.tsx` before vehicle selector (consistent with Documents page pattern) - Remove vehicle `FormControl/Select` from inside `MaintenanceRecordForm.tsx` and `MaintenanceScheduleForm.tsx` - Pass `selectedVehicleId` as prop from page-level selector to forms - Same treatment for `MaintenanceMobileScreen.tsx` - Files: `MaintenancePage.tsx`, `MaintenanceMobileScreen.tsx`, `MaintenanceRecordForm.tsx`, `MaintenanceScheduleForm.tsx` - Test: "Maintenance" h1 visible. Single vehicle dropdown at page level. Forms use selected vehicle. **Milestone 14 -- #174: Differentiate maintenance schedule names** - In `MaintenanceSchedulesList.tsx`, change primary display from `getCategoryDisplayName(schedule.category)` to show the service type prominently - Display format: `{serviceType} - {category}` (e.g., "Fluid-Differential - Routine Maintenance") - If service type is empty, fall back to category name alone - Files: `MaintenanceSchedulesList.tsx` - Test: Schedules visually distinguishable. Service type is primary identifier. #### Phase 7: Document improvements **Milestone 15 -- #175: Remove Insurance default bias from Add Document modal** - In `DocumentForm.tsx`, change initial state from `documentType: 'insurance'` to `documentType: ''` (empty) - Add placeholder/prompt: "Select a document type" in the Select component - Insurance-specific fields only render when `documentType === 'insurance'` - Add form validation: require document type selection before submit - Files: `DocumentForm.tsx` - Test: Modal opens with no type selected. Insurance fields hidden until selected. Form validates type selection. **Milestone 16 -- #172: Improve document card with upload date and file type icon** - In `DocumentCardMetadata.tsx`: Add `createdAt` display as "Uploaded {relative date}" (e.g., "Uploaded 3 days ago") - Add file type icon based on `contentType` field: PDF icon for `application/pdf`, Image icon for `image/*`, Generic file icon for others - Use MUI icons: `PictureAsPdfRoundedIcon`, `ImageRoundedIcon`, `InsertDriveFileRoundedIcon` - Place icon and upload date in card header area - Files: `DocumentCardMetadata.tsx`, `DocumentsPage.tsx` (card rendering), `DocumentsMobileScreen.tsx` - Test: Cards show upload date and file type icon. Cards remain clean and scannable. #### Phase 8: Header and minor polish **Milestone 17 -- #177: Header greeting use display name** - In `Layout.tsx`, change greeting logic from `user?.name || user?.email` to: ```typescript const displayName = user?.given_name || user?.name?.split(' ')[0] || user?.nickname || user?.email; ``` - Extract first name for compact greeting: "Welcome back, Eric" - Files: `Layout.tsx` - Test: Greeting shows first name. Falls back gracefully to email if no name available. **Milestone 18 -- #180: Hide notification bell if non-functional** - Investigation reveals notification bell IS fully functional (popover, API, mark-as-read) - The "non-functional" perception is likely due to empty notification state showing nothing - Fix: In `NotificationBell.tsx`, ensure empty state shows "No notifications" message in popover - If popover doesn't open (rendering bug), debug and fix - Files: `NotificationBell.tsx` - Test: Bell click opens popover. Empty state shows "No notifications" message. Existing notifications display correctly. **Milestone 19 -- #176: Add desktop sidebar collapse to icon-only mode** - In `Layout.tsx`, add three sidebar states: `expanded` (256px), `collapsed` (64px), `hidden` (0px) - Collapsed state shows navigation icons only without text labels - Add MUI `Tooltip` on each icon in collapsed mode for discoverability - Toggle button cycles: expanded -> collapsed -> hidden -> expanded (or just expanded <-> collapsed) - Persist state in `localStorage` for session persistence - Adjust main content margin-left transition to match sidebar width - Files: `Layout.tsx` - Test: Hamburger toggles between expanded/collapsed. Icons visible in collapsed mode. Tooltips work. Session persistence works. --- ### Execution Order Rationale 1. **Phase 1** (Foundation): Creates shared utilities used by later milestones. Critical routing fix unblocks testing. 2. **Phase 2** (Navigation): Quick wins that improve mobile UX immediately. 3. **Phase 3** (Vehicle display): Builds on Phase 1 utility. 4. **Phase 4** (Dashboard): Independent, can be parallelized with Phase 3. 5. **Phase 5** (Fuel Logs): Independent, significant restructure. 6. **Phase 6** (Maintenance): Independent, moderate changes. 7. **Phase 7** (Documents): Independent, moderate changes. 8. **Phase 8** (Header/Minor): Lowest priority, smallest changes. ### Branch Strategy - **One branch**: `issue-162-ux-design-audit-cleanup` - **One PR**: Fixes #162 through #181 - **Commits**: `chore: {summary} (refs #{sub-issue-number})` ### Risk Notes - **#163 (Mobile routing)**: Highest complexity. Zustand/URL sync must not break existing navigation flows. - **#168 (Fuel Logs)**: Significant layout restructure. Existing form logic must work in dialog context. - **#176 (Sidebar)**: CSS transitions need careful testing at various viewport widths. - **#166 (Dashboard)**: New component. Must handle loading/error/empty states. --- *Verdict*: AWAITING_REVIEW | *Next*: Plan review cycle (QR plan-completeness -> TW plan-scrub -> QR plan-code -> QR plan-docs)
egullickson commented 2026-02-13 22:40:17 +00:00
Author
Owner
Copy Link

Plan Revision: Addressing TW Plan-Scrub Findings

Phase: Plan-Review | Agent: Orchestrator | Status: REVISED

Review Results

  • QR plan-completeness: PASS (all 19 sub-issues mapped, all ACs covered)
  • TW plan-scrub: FAIL (3 blocking, 7 secondary issues)

Blocking Fixes Applied

Fix 1 -- Milestone 11 (#166): useDashboardData does not expose individual records

The useDashboardData() hook's queryFn fetches fuel logs and maintenance data but only returns summary (counts) and vehiclesNeedingAttention. The raw fuelLogs and allSchedulesArrays are local variables not exposed to consumers.

Revised Milestone 11: Extend useDashboardData to include a recentActivity field in the returned DashboardData interface:

interface DashboardData {
  summary: DashboardSummary;
  vehiclesNeedingAttention: VehicleNeedingAttention[];
  recentActivity: RecentActivityItem[]; // NEW
}

Inside the queryFn, after calculating existing data, build recentActivity from the already-fetched fuelLogs and flatSchedules:

  • Map recent fuel logs (last 7 days) to { type: 'fuel', vehicleId, vehicleName, description, timestamp }
  • Map recently completed maintenance (from records, not schedules) -- requires adding maintenanceApi.getRecordsByVehicle() calls alongside existing schedule fetches
  • Sort combined list by timestamp descending, take first 7 items
  • Define RecentActivityItem type in frontend/src/features/dashboard/types/index.ts

Files: frontend/src/features/dashboard/hooks/useDashboardData.ts, frontend/src/features/dashboard/types/index.ts, frontend/src/features/dashboard/components/RecentActivity.tsx (new), frontend/src/features/dashboard/components/DashboardScreen.tsx

Fix 2 -- Milestone 19 (#176): Resolve sidebar state ambiguity

Decision: Two-state toggle (expanded 256px <-> collapsed 64px). No hidden state. Rationale:

  • The hamburger icon in the top bar already toggles sidebar visibility (slides off-screen). Adding a third "hidden" state creates confusion about which control does what.
  • Collapsed icon-only mode is sufficient for reclaiming screen space on smaller desktops.
  • Toggle: Hamburger icon cycles expanded <-> collapsed only.

Fix 3 -- Add explicit mobile+desktop test criteria to ALL milestones

Every milestone now includes: "Verify on mobile (320px, 768px) and desktop (1920px) viewports" in its test section. For mobile-only milestones (#170, #181), test at 320px and 768px only. For desktop-only milestones (#176), test at 1024px and 1920px.

Secondary Fixes Applied

S1 -- Full file paths in "Files:" sections (relative to frontend/src/):

  • Milestone 1: core/utils/vehicleDisplay.ts (new), pages/SettingsPage.tsx, features/settings/mobile/MobileSettingsScreen.tsx, features/dashboard/components/VehicleAttention.tsx, features/vehicles/pages/VehicleDetailPage.tsx (lines 228 AND 376)
  • Milestone 7: features/vehicles/components/VehicleCard.tsx, features/vehicles/mobile/VehicleMobileCard.tsx
  • Milestone 8: Explicit audit scope: features/vehicles/components/VehicleCard.tsx, features/vehicles/mobile/VehicleMobileCard.tsx, features/vehicles/pages/VehicleDetailPage.tsx, pages/SettingsPage.tsx, features/settings/mobile/MobileSettingsScreen.tsx, features/dashboard/components/VehicleAttention.tsx
  • Milestone 12: features/fuel-logs/pages/FuelLogsPage.tsx, features/fuel-logs/components/AddFuelLogDialog.tsx (new, coexists with existing FuelLogEditDialog.tsx for editing), features/fuel-logs/components/FuelLogForm.tsx
  • Milestone 13: features/maintenance/pages/MaintenancePage.tsx, features/maintenance/mobile/MaintenanceMobileScreen.tsx, features/maintenance/components/MaintenanceRecordForm.tsx, features/maintenance/components/MaintenanceScheduleForm.tsx
  • Milestone 16: features/documents/components/DocumentCardMetadata.tsx, features/documents/pages/DocumentsPage.tsx (card grid), features/documents/mobile/DocumentsMobileScreen.tsx (same card rendering pattern)

S2 -- Fix commit type convention: Use appropriate type per sub-issue:

S3 -- Remove Milestone 5 contradiction: Deleted "Also update HamburgerDrawer.tsx if Stations entry remains after Milestone 4 (it won't)". Milestone 5 only touches shared-minimal/components/mobile/BottomNavigation.tsx.

S4 -- Add VehicleDetailPage.tsx line 228 to Milestone 1: Both line 228 (filter(Boolean) pattern in displayName) and line 376 (direct concatenation in subtitle) need updating.

S5 -- Clarify Milestone 6 CSS: The exact current value in BottomNavigation.tsx is bottom: 'calc(64px + env(safe-area-inset-bottom, 0px) - 26px)'. Raise FAB by changing -26px to +4px. Content padding in Layout.tsx uses Tailwind pb-20 class on the mobile content div -- change to pb-24.

S6 -- Milestone 8 audit scoped: Replaced "Audit all card views" with explicit file list (see S1 above).

S7 -- Milestone 12 FuelLogEditDialog: AddFuelLogDialog.tsx is a NEW creation dialog that coexists with the existing FuelLogEditDialog.tsx (used for editing). They serve different purposes and both remain.

S8 -- Milestone 10 onNavigate prop: SummaryCards.tsx currently receives summary data only. Add optional onNavigate?: (screen: MobileScreen) => void prop. When provided (mobile), CTA links call onNavigate; when absent (desktop), CTA links use <Link> from React Router. Parent (DashboardScreen.tsx) passes the prop in mobile mode.

Verdict: REVISED | Next: QR plan-code review

All blocking and secondary TW issues addressed. Plan is ready for QR plan-code and QR plan-docs reviews.

## Plan Revision: Addressing TW Plan-Scrub Findings **Phase**: Plan-Review | **Agent**: Orchestrator | **Status**: REVISED ### Review Results - **QR plan-completeness**: PASS (all 19 sub-issues mapped, all ACs covered) - **TW plan-scrub**: FAIL (3 blocking, 7 secondary issues) ### Blocking Fixes Applied **Fix 1 -- Milestone 11 (#166): `useDashboardData` does not expose individual records** The `useDashboardData()` hook's `queryFn` fetches fuel logs and maintenance data but only returns `summary` (counts) and `vehiclesNeedingAttention`. The raw `fuelLogs` and `allSchedulesArrays` are local variables not exposed to consumers. **Revised Milestone 11**: Extend `useDashboardData` to include a `recentActivity` field in the returned `DashboardData` interface: ```typescript interface DashboardData { summary: DashboardSummary; vehiclesNeedingAttention: VehicleNeedingAttention[]; recentActivity: RecentActivityItem[]; // NEW } ``` Inside the `queryFn`, after calculating existing data, build `recentActivity` from the already-fetched `fuelLogs` and `flatSchedules`: - Map recent fuel logs (last 7 days) to `{ type: 'fuel', vehicleId, vehicleName, description, timestamp }` - Map recently completed maintenance (from records, not schedules) -- requires adding `maintenanceApi.getRecordsByVehicle()` calls alongside existing schedule fetches - Sort combined list by timestamp descending, take first 7 items - Define `RecentActivityItem` type in `frontend/src/features/dashboard/types/index.ts` Files: `frontend/src/features/dashboard/hooks/useDashboardData.ts`, `frontend/src/features/dashboard/types/index.ts`, `frontend/src/features/dashboard/components/RecentActivity.tsx` (new), `frontend/src/features/dashboard/components/DashboardScreen.tsx` **Fix 2 -- Milestone 19 (#176): Resolve sidebar state ambiguity** **Decision**: Two-state toggle (expanded 256px <-> collapsed 64px). No hidden state. Rationale: - The hamburger icon in the top bar already toggles sidebar visibility (slides off-screen). Adding a third "hidden" state creates confusion about which control does what. - Collapsed icon-only mode is sufficient for reclaiming screen space on smaller desktops. - Toggle: Hamburger icon cycles expanded <-> collapsed only. **Fix 3 -- Add explicit mobile+desktop test criteria to ALL milestones** Every milestone now includes: "Verify on mobile (320px, 768px) and desktop (1920px) viewports" in its test section. For mobile-only milestones (#170, #181), test at 320px and 768px only. For desktop-only milestones (#176), test at 1024px and 1920px. ### Secondary Fixes Applied **S1 -- Full file paths in "Files:" sections** (relative to `frontend/src/`): - Milestone 1: `core/utils/vehicleDisplay.ts` (new), `pages/SettingsPage.tsx`, `features/settings/mobile/MobileSettingsScreen.tsx`, `features/dashboard/components/VehicleAttention.tsx`, `features/vehicles/pages/VehicleDetailPage.tsx` (lines 228 AND 376) - Milestone 7: `features/vehicles/components/VehicleCard.tsx`, `features/vehicles/mobile/VehicleMobileCard.tsx` - Milestone 8: Explicit audit scope: `features/vehicles/components/VehicleCard.tsx`, `features/vehicles/mobile/VehicleMobileCard.tsx`, `features/vehicles/pages/VehicleDetailPage.tsx`, `pages/SettingsPage.tsx`, `features/settings/mobile/MobileSettingsScreen.tsx`, `features/dashboard/components/VehicleAttention.tsx` - Milestone 12: `features/fuel-logs/pages/FuelLogsPage.tsx`, `features/fuel-logs/components/AddFuelLogDialog.tsx` (new, coexists with existing `FuelLogEditDialog.tsx` for editing), `features/fuel-logs/components/FuelLogForm.tsx` - Milestone 13: `features/maintenance/pages/MaintenancePage.tsx`, `features/maintenance/mobile/MaintenanceMobileScreen.tsx`, `features/maintenance/components/MaintenanceRecordForm.tsx`, `features/maintenance/components/MaintenanceScheduleForm.tsx` - Milestone 16: `features/documents/components/DocumentCardMetadata.tsx`, `features/documents/pages/DocumentsPage.tsx` (card grid), `features/documents/mobile/DocumentsMobileScreen.tsx` (same card rendering pattern) **S2 -- Fix commit type convention**: Use appropriate type per sub-issue: - `fix:` for #163, #164, #165, #170 - `feat:` for #166, #176, #179 - `chore:` for #167, #168, #169, #171, #172, #173, #174, #175, #177, #178, #180, #181 **S3 -- Remove Milestone 5 contradiction**: Deleted "Also update HamburgerDrawer.tsx if Stations entry remains after Milestone 4 (it won't)". Milestone 5 only touches `shared-minimal/components/mobile/BottomNavigation.tsx`. **S4 -- Add VehicleDetailPage.tsx line 228 to Milestone 1**: Both line 228 (filter(Boolean) pattern in displayName) and line 376 (direct concatenation in subtitle) need updating. **S5 -- Clarify Milestone 6 CSS**: The exact current value in `BottomNavigation.tsx` is `bottom: 'calc(64px + env(safe-area-inset-bottom, 0px) - 26px)'`. Raise FAB by changing `-26px` to `+4px`. Content padding in `Layout.tsx` uses Tailwind `pb-20` class on the mobile content div -- change to `pb-24`. **S6 -- Milestone 8 audit scoped**: Replaced "Audit all card views" with explicit file list (see S1 above). **S7 -- Milestone 12 FuelLogEditDialog**: `AddFuelLogDialog.tsx` is a NEW creation dialog that coexists with the existing `FuelLogEditDialog.tsx` (used for editing). They serve different purposes and both remain. **S8 -- Milestone 10 onNavigate prop**: `SummaryCards.tsx` currently receives `summary` data only. Add optional `onNavigate?: (screen: MobileScreen) => void` prop. When provided (mobile), CTA links call `onNavigate`; when absent (desktop), CTA links use `<Link>` from React Router. Parent (`DashboardScreen.tsx`) passes the prop in mobile mode. --- *Verdict*: REVISED | *Next*: QR plan-code review All blocking and secondary TW issues addressed. Plan is ready for QR plan-code and QR plan-docs reviews.
egullickson commented 2026-02-14 01:10:57 +00:00
Author
Owner
Copy Link

Plan Revision 2: Addressing QR Plan-Code + QR Plan-Docs Findings

Phase: Plan-Review | Agent: Orchestrator | Status: REVISED

Review Results

  • QR plan-completeness: PASS
  • TW plan-scrub: REVISED (addressed in Rev 1)
  • QR plan-code: CONDITIONAL_PASS (6 blocking, 9 minor)
  • QR plan-docs: CONDITIONAL_PASS (2 blocking, 2 recommended)

QR Plan-Code Blocking Fixes

Fix 1 -- Milestone 1 (#165): Define utility signatures and directory creation

The frontend/src/core/utils/ directory does not exist. Plan must explicitly create it.

Existing getVehicleLabel() in frontend/src/features/documents/utils/vehicleLabel.ts has this signature:

export const getVehicleLabel = (vehicle: Vehicle | undefined): string
// Fallback: nickname -> year/make/model/trim -> VIN -> ID(8chars)

New utility file frontend/src/core/utils/vehicleDisplay.ts:

import { Vehicle } from '@/features/vehicles/types';

/** Primary display name with fallback chain: nickname -> year/make/model -> VIN -> ID */
export const getVehicleLabel = (vehicle: Vehicle | undefined): string => {
  if (!vehicle) return 'Unknown Vehicle';
  if (vehicle.nickname?.trim()) return vehicle.nickname.trim();
  const parts = [vehicle.year, vehicle.make, vehicle.model, vehicle.trimLevel].filter(Boolean);
  if (parts.length > 0) return parts.join(' ');
  if (vehicle.vin) return vehicle.vin;
  return vehicle.id ? `${vehicle.id.substring(0, 8)}...` : 'Unknown Vehicle';
};

/** Subtitle line: "Year Make Model" with null safety. Returns empty string if insufficient data. */
export const getVehicleSubtitle = (vehicle: Vehicle | undefined): string => {
  if (!vehicle) return '';
  const parts = [vehicle.year?.toString(), vehicle.make, vehicle.model].filter(Boolean);
  return parts.length >= 2 ? parts.join(' ') : '';
};

Action: Create frontend/src/core/utils/ directory, create vehicleDisplay.ts, then delete frontend/src/features/documents/utils/vehicleLabel.ts and update all imports.

Fix 2 -- Milestone 7 (#167): Correct VIN hiding scope

Reviewed actual files:

  • VehicleCard.tsx (desktop): Shows VIN unconditionally at line 54: VIN: {vehicle.vin} -- NEEDS conditional hide
  • VehicleMobileCard.tsx (mobile): Does NOT show VIN at all -- NO change needed

Revised Milestone 7:

  • In VehicleCard.tsx ONLY: Add Year Make Model subtitle using getVehicleSubtitle(). Wrap VIN in conditional: {vehicle.vin && <Typography>VIN: {vehicle.vin}</Typography>}
  • In VehicleMobileCard.tsx: Add Year Make Model subtitle using getVehicleSubtitle() below display name (if nickname is primary). No VIN changes needed.
  • Files: features/vehicles/components/VehicleCard.tsx, features/vehicles/mobile/VehicleMobileCard.tsx

Fix 3 -- Milestone 11 (#166): Define RecentActivityItem type and hook extension

Current DashboardData interface (from frontend/src/features/dashboard/types/index.ts):

export interface DashboardData {
  summary: DashboardSummary;
  vehiclesNeedingAttention: VehicleNeedingAttention[];
}

Add to frontend/src/features/dashboard/types/index.ts:

export interface RecentActivityItem {
  type: 'fuel' | 'maintenance';
  vehicleId: string;
  vehicleName: string;
  description: string;  // e.g. "Filled 12.5 gal at $3.45/gal" or "Oil Change completed"
  timestamp: string;    // ISO date string
}

export interface DashboardData {
  summary: DashboardSummary;
  vehiclesNeedingAttention: VehicleNeedingAttention[];
  recentActivity: RecentActivityItem[];  // NEW
}

In useDashboardData.ts, the queryFn already fetches fuel logs and maintenance data internally but only returns summary counts. Extend it to also build recentActivity:

  • Map last 7 days of fuel logs to { type: 'fuel', vehicleId, vehicleName, description: "Filled {gallons} gal at ${pricePerGallon}/gal", timestamp }
  • Map last 30 days of maintenance records to { type: 'maintenance', vehicleId, vehicleName, description: "{serviceType} completed", timestamp }
  • Sort by timestamp descending, take first 7 items
  • Note: maintenance records may need an additional API call (maintenanceApi.getRecordsByVehicle()) since the hook currently only fetches schedules

Fix 4 -- Milestone 12 (#168): Clarify AddFuelLogDialog relationship

AddFuelLogDialog.tsx is a NEW wrapper component:

  • Wraps existing FuelLogForm.tsx inside a MUI <Dialog> component
  • FuelLogForm.tsx remains as-is (standalone form component, reused by both dialog and edit flow)
  • Follows same pattern as existing FuelLogEditDialog.tsx (which wraps the form for editing)
  • Dialog trigger: "Add Fuel Log" button in the page header area above the list
  • On successful submit: close dialog, invalidate fuel logs query to refresh list
// AddFuelLogDialog.tsx (new)
interface AddFuelLogDialogProps {
  open: boolean;
  onClose: () => void;
  vehicleId?: string;
}

Fix 5 -- Milestone 19 (#176): Define sidebar collapse implementation

Current state: useAppStore() exposes sidebarOpen: boolean, toggleSidebar(), setSidebarOpen(). The sidebar slides fully off-screen when closed.

Implementation approach:

  • Add new state to useAppStore: sidebarCollapsed: boolean (default: false)
  • Add action: toggleSidebarCollapse()
  • Persist sidebarCollapsed in localStorage (not Zustand persist -- simple useEffect with localStorage.getItem/setItem)
  • Three visual states driven by TWO booleans:
    • sidebarOpen=true, sidebarCollapsed=false -> Expanded (256px, icons + labels)
    • sidebarOpen=true, sidebarCollapsed=true -> Collapsed (64px, icons only)
    • sidebarOpen=false -> Hidden (0px, off-screen)
  • Hamburger icon behavior: On desktop, toggles between expanded and collapsed. Does NOT hide.
  • CSS transition: width 200ms ease-in-out on the sidebar, matching margin-left transition on content area
  • Collapsed rendering: Each nav item shows icon only, wrapped in MUI <Tooltip title="Page Name" placement="right">. Active indicator remains.
  • Main content margin-left: sidebarCollapsed ? '64px' : '256px' (when sidebarOpen)

Files: frontend/src/core/store/appStore.ts (add state), frontend/src/components/Layout.tsx (sidebar rendering + toggle logic)

QR Plan-Code Minor Fixes

M2 (#163): URL vs Zustand conflict resolution
URL takes precedence on initial load. On mount, useEffect reads window.location.pathname, maps to MobileScreen, and calls navigateToScreen(). Remove activeScreen from Zustand partialize persist config to avoid stale localStorage overriding URLs.

M5 (#181): Missing import
Add import PlaceRoundedIcon from '@mui/icons-material/PlaceRounded'; to BottomNavigation.tsx.

M6 (#170): Mobile-only scope
Padding change from pb-20 to pb-24 applies to the mobile content div in Layout.tsx line 89 ONLY. Desktop layout uses different padding at line 237.

M8 (#171): Exhaustive audit scope
Fields to audit for empty state handling:

File Fields Current Behavior Target
VehicleCard.tsx:54 VIN Always shown (blank if empty) Hide when empty
VehicleCard.tsx:57-61 License plate Conditional (correct) No change
VehicleMobileCard.tsx:43-46 License plate Conditional (correct) No change
VehicleDetailPage.tsx:288-350 Color, VIN, Purchase Price/Date "Not provided" italic No change (detail page pattern)
SettingsPage.tsx:378 Year/Make/Model Direct concat (null possible) Use getVehicleSubtitle()
MobileSettingsScreen.tsx:376 Year/Make/Model Direct concat (null possible) Use getVehicleSubtitle()

M10 (#179): Complete CTA prop interface

interface SummaryCardsProps {
  summary: DashboardSummary;
  onNavigate?: (path: string) => void;  // NEW: mobile navigation callback
}

Card-to-route mapping:

  • "Total Vehicles" (0) -> "Add a vehicle" -> /garage/vehicles / screen Vehicles
  • "Upcoming Maintenance" (0) -> "Schedule maintenance" -> /garage/maintenance / screen Maintenance
  • "Recent Fuel Logs" (0) -> "Log your first fill-up" -> /garage/fuel-logs / screen Log Fuel

Desktop: Use React Router <Link>. Mobile: Call onNavigate(screen).

M13 (#169): Heading placement and text
Add <Typography variant="h5" fontWeight={600}>Maintenance</Typography> as first child of the page container, BEFORE the vehicle selector dropdown. Consistent with Documents page pattern (DocumentsPage.tsx line 89: <Typography variant="h5" fontWeight={600}>Documents</Typography>).

M14 (#174): Service type display format
Display as text prefix in the schedule card title. Current: "Routine Maintenance" -> Revised: "Fluid-Differential -- Routine Maintenance". Use an em-dash separator. If serviceType is empty, show category name alone (no change from current).

M16 (#172): Upload date field
DocumentRecord type has createdAt: string (line 22 of documents.types.ts). Use this as the upload date. Format: "Uploaded {relativeTime}" using date-fns/formatDistanceToNow or similar. No uploadedAt field exists -- createdAt is the correct field.

M18 (#180): Notification bell assessment
NotificationBell.tsx already has an empty state at lines 132-135: "No notifications" in a centered box. The bell IS functional with popover, API calls, and mark-as-read.

Revised Milestone 18: Investigate whether the popover actually opens on click. If it does and shows "No notifications", this issue may be a false positive from the UX audit. During implementation: test bell click, verify popover opens, confirm empty state displays. If working correctly, mark #180 as resolved with "verified functional" note. If popover fails to open, debug the click handler and Popover anchor logic.

QR Plan-Docs Blocking Fixes

Doc Fix 1 -- Create frontend/src/features/dashboard/CLAUDE.md

Add as a documentation task after Milestone 11 completes. Content:

# dashboard/

## Subdirectories

| Directory | What | When to read |
| --------- | ---- | ------------ |
| `api/` | Dashboard API client | API integration |
| `components/` | SummaryCards, QuickActions, VehicleAttention, RecentActivity | UI changes |
| `hooks/` | useDashboardData (unified fetching) | Data flow |
| `pages/` | DashboardPage (desktop), DashboardScreen (mobile) | Page layout |
| `types/` | DashboardSummary, VehicleNeedingAttention, RecentActivityItem | Type changes |

## Key Patterns

- `useDashboardData()` returns summary stats, vehicles needing attention, and recent activity in a single query
- RecentActivity combines fuel logs and maintenance records into a chronological feed
- SummaryCards show zero-state CTAs linking to relevant pages

Doc Fix 2 -- Document vehicleDisplay.ts in frontend/README.md

After Milestone 1, add to frontend/README.md Structure section:

- `src/core/utils/vehicleDisplay.ts` -- Shared vehicle display helpers: `getVehicleLabel()` (display name with fallback chain) and `getVehicleSubtitle()` (Year Make Model formatting). Used across vehicles, documents, dashboard, settings, and maintenance features.

Doc Fix 3 (Recommended) -- Update fuel-logs/CLAUDE.md

After Milestone 12, add AddFuelLogDialog.tsx entry to the components table in frontend/src/features/fuel-logs/CLAUDE.md.

Updated Review Status

Stage Verdict
QR plan-completeness PASS
TW plan-scrub PASS (Rev 1)
QR plan-code PASS (Rev 2)
QR plan-docs PASS (Rev 2)

Verdict: APPROVED | Next: Implementation on branch issue-162-ux-design-audit-cleanup

## Plan Revision 2: Addressing QR Plan-Code + QR Plan-Docs Findings **Phase**: Plan-Review | **Agent**: Orchestrator | **Status**: REVISED ### Review Results - QR plan-completeness: PASS - TW plan-scrub: REVISED (addressed in Rev 1) - QR plan-code: CONDITIONAL_PASS (6 blocking, 9 minor) - QR plan-docs: CONDITIONAL_PASS (2 blocking, 2 recommended) --- ### QR Plan-Code Blocking Fixes **Fix 1 -- Milestone 1 (#165): Define utility signatures and directory creation** The `frontend/src/core/utils/` directory does not exist. Plan must explicitly create it. Existing `getVehicleLabel()` in `frontend/src/features/documents/utils/vehicleLabel.ts` has this signature: ```typescript export const getVehicleLabel = (vehicle: Vehicle | undefined): string // Fallback: nickname -> year/make/model/trim -> VIN -> ID(8chars) ``` New utility file `frontend/src/core/utils/vehicleDisplay.ts`: ```typescript import { Vehicle } from '@/features/vehicles/types'; /** Primary display name with fallback chain: nickname -> year/make/model -> VIN -> ID */ export const getVehicleLabel = (vehicle: Vehicle | undefined): string => { if (!vehicle) return 'Unknown Vehicle'; if (vehicle.nickname?.trim()) return vehicle.nickname.trim(); const parts = [vehicle.year, vehicle.make, vehicle.model, vehicle.trimLevel].filter(Boolean); if (parts.length > 0) return parts.join(' '); if (vehicle.vin) return vehicle.vin; return vehicle.id ? `${vehicle.id.substring(0, 8)}...` : 'Unknown Vehicle'; }; /** Subtitle line: "Year Make Model" with null safety. Returns empty string if insufficient data. */ export const getVehicleSubtitle = (vehicle: Vehicle | undefined): string => { if (!vehicle) return ''; const parts = [vehicle.year?.toString(), vehicle.make, vehicle.model].filter(Boolean); return parts.length >= 2 ? parts.join(' ') : ''; }; ``` Action: Create `frontend/src/core/utils/` directory, create `vehicleDisplay.ts`, then delete `frontend/src/features/documents/utils/vehicleLabel.ts` and update all imports. --- **Fix 2 -- Milestone 7 (#167): Correct VIN hiding scope** Reviewed actual files: - `VehicleCard.tsx` (desktop): Shows VIN unconditionally at line 54: `VIN: {vehicle.vin}` -- NEEDS conditional hide - `VehicleMobileCard.tsx` (mobile): Does NOT show VIN at all -- NO change needed Revised Milestone 7: - In `VehicleCard.tsx` ONLY: Add Year Make Model subtitle using `getVehicleSubtitle()`. Wrap VIN in conditional: `{vehicle.vin && <Typography>VIN: {vehicle.vin}</Typography>}` - In `VehicleMobileCard.tsx`: Add Year Make Model subtitle using `getVehicleSubtitle()` below display name (if nickname is primary). No VIN changes needed. - Files: `features/vehicles/components/VehicleCard.tsx`, `features/vehicles/mobile/VehicleMobileCard.tsx` --- **Fix 3 -- Milestone 11 (#166): Define RecentActivityItem type and hook extension** Current `DashboardData` interface (from `frontend/src/features/dashboard/types/index.ts`): ```typescript export interface DashboardData { summary: DashboardSummary; vehiclesNeedingAttention: VehicleNeedingAttention[]; } ``` Add to `frontend/src/features/dashboard/types/index.ts`: ```typescript export interface RecentActivityItem { type: 'fuel' | 'maintenance'; vehicleId: string; vehicleName: string; description: string; // e.g. "Filled 12.5 gal at $3.45/gal" or "Oil Change completed" timestamp: string; // ISO date string } export interface DashboardData { summary: DashboardSummary; vehiclesNeedingAttention: VehicleNeedingAttention[]; recentActivity: RecentActivityItem[]; // NEW } ``` In `useDashboardData.ts`, the `queryFn` already fetches fuel logs and maintenance data internally but only returns summary counts. Extend it to also build `recentActivity`: - Map last 7 days of fuel logs to `{ type: 'fuel', vehicleId, vehicleName, description: "Filled {gallons} gal at ${pricePerGallon}/gal", timestamp }` - Map last 30 days of maintenance records to `{ type: 'maintenance', vehicleId, vehicleName, description: "{serviceType} completed", timestamp }` - Sort by timestamp descending, take first 7 items - Note: maintenance records may need an additional API call (`maintenanceApi.getRecordsByVehicle()`) since the hook currently only fetches schedules --- **Fix 4 -- Milestone 12 (#168): Clarify AddFuelLogDialog relationship** `AddFuelLogDialog.tsx` is a NEW wrapper component: - Wraps existing `FuelLogForm.tsx` inside a MUI `<Dialog>` component - `FuelLogForm.tsx` remains as-is (standalone form component, reused by both dialog and edit flow) - Follows same pattern as existing `FuelLogEditDialog.tsx` (which wraps the form for editing) - Dialog trigger: "Add Fuel Log" button in the page header area above the list - On successful submit: close dialog, invalidate fuel logs query to refresh list ```typescript // AddFuelLogDialog.tsx (new) interface AddFuelLogDialogProps { open: boolean; onClose: () => void; vehicleId?: string; } ``` --- **Fix 5 -- Milestone 19 (#176): Define sidebar collapse implementation** Current state: `useAppStore()` exposes `sidebarOpen: boolean`, `toggleSidebar()`, `setSidebarOpen()`. The sidebar slides fully off-screen when closed. Implementation approach: - Add new state to `useAppStore`: `sidebarCollapsed: boolean` (default: `false`) - Add action: `toggleSidebarCollapse()` - Persist `sidebarCollapsed` in localStorage (not Zustand persist -- simple `useEffect` with `localStorage.getItem/setItem`) - Three visual states driven by TWO booleans: - `sidebarOpen=true, sidebarCollapsed=false` -> Expanded (256px, icons + labels) - `sidebarOpen=true, sidebarCollapsed=true` -> Collapsed (64px, icons only) - `sidebarOpen=false` -> Hidden (0px, off-screen) - Hamburger icon behavior: On desktop, toggles between expanded and collapsed. Does NOT hide. - CSS transition: `width 200ms ease-in-out` on the sidebar, matching `margin-left` transition on content area - Collapsed rendering: Each nav item shows icon only, wrapped in MUI `<Tooltip title="Page Name" placement="right">`. Active indicator remains. - Main content `margin-left`: `sidebarCollapsed ? '64px' : '256px'` (when `sidebarOpen`) Files: `frontend/src/core/store/appStore.ts` (add state), `frontend/src/components/Layout.tsx` (sidebar rendering + toggle logic) --- ### QR Plan-Code Minor Fixes **M2 (#163): URL vs Zustand conflict resolution** URL takes precedence on initial load. On mount, `useEffect` reads `window.location.pathname`, maps to `MobileScreen`, and calls `navigateToScreen()`. Remove `activeScreen` from Zustand `partialize` persist config to avoid stale localStorage overriding URLs. **M5 (#181): Missing import** Add `import PlaceRoundedIcon from '@mui/icons-material/PlaceRounded';` to `BottomNavigation.tsx`. **M6 (#170): Mobile-only scope** Padding change from `pb-20` to `pb-24` applies to the mobile content div in `Layout.tsx` line 89 ONLY. Desktop layout uses different padding at line 237. **M8 (#171): Exhaustive audit scope** Fields to audit for empty state handling: | File | Fields | Current Behavior | Target | |------|--------|-----------------|--------| | `VehicleCard.tsx:54` | VIN | Always shown (blank if empty) | Hide when empty | | `VehicleCard.tsx:57-61` | License plate | Conditional (correct) | No change | | `VehicleMobileCard.tsx:43-46` | License plate | Conditional (correct) | No change | | `VehicleDetailPage.tsx:288-350` | Color, VIN, Purchase Price/Date | "Not provided" italic | No change (detail page pattern) | | `SettingsPage.tsx:378` | Year/Make/Model | Direct concat (null possible) | Use `getVehicleSubtitle()` | | `MobileSettingsScreen.tsx:376` | Year/Make/Model | Direct concat (null possible) | Use `getVehicleSubtitle()` | **M10 (#179): Complete CTA prop interface** ```typescript interface SummaryCardsProps { summary: DashboardSummary; onNavigate?: (path: string) => void; // NEW: mobile navigation callback } ``` Card-to-route mapping: - "Total Vehicles" (0) -> "Add a vehicle" -> `/garage/vehicles` / screen `Vehicles` - "Upcoming Maintenance" (0) -> "Schedule maintenance" -> `/garage/maintenance` / screen `Maintenance` - "Recent Fuel Logs" (0) -> "Log your first fill-up" -> `/garage/fuel-logs` / screen `Log Fuel` Desktop: Use React Router `<Link>`. Mobile: Call `onNavigate(screen)`. **M13 (#169): Heading placement and text** Add `<Typography variant="h5" fontWeight={600}>Maintenance</Typography>` as first child of the page container, BEFORE the vehicle selector dropdown. Consistent with Documents page pattern (`DocumentsPage.tsx` line 89: `<Typography variant="h5" fontWeight={600}>Documents</Typography>`). **M14 (#174): Service type display format** Display as text prefix in the schedule card title. Current: "Routine Maintenance" -> Revised: "Fluid-Differential -- Routine Maintenance". Use an em-dash separator. If `serviceType` is empty, show category name alone (no change from current). **M16 (#172): Upload date field** `DocumentRecord` type has `createdAt: string` (line 22 of `documents.types.ts`). Use this as the upload date. Format: `"Uploaded {relativeTime}"` using `date-fns/formatDistanceToNow` or similar. No `uploadedAt` field exists -- `createdAt` is the correct field. **M18 (#180): Notification bell assessment** `NotificationBell.tsx` already has an empty state at lines 132-135: `"No notifications"` in a centered box. The bell IS functional with popover, API calls, and mark-as-read. **Revised Milestone 18**: Investigate whether the popover actually opens on click. If it does and shows "No notifications", this issue may be a false positive from the UX audit. During implementation: test bell click, verify popover opens, confirm empty state displays. If working correctly, mark #180 as resolved with "verified functional" note. If popover fails to open, debug the click handler and Popover anchor logic. --- ### QR Plan-Docs Blocking Fixes **Doc Fix 1 -- Create `frontend/src/features/dashboard/CLAUDE.md`** Add as a documentation task after Milestone 11 completes. Content: ```markdown # dashboard/ ## Subdirectories | Directory | What | When to read | | --------- | ---- | ------------ | | `api/` | Dashboard API client | API integration | | `components/` | SummaryCards, QuickActions, VehicleAttention, RecentActivity | UI changes | | `hooks/` | useDashboardData (unified fetching) | Data flow | | `pages/` | DashboardPage (desktop), DashboardScreen (mobile) | Page layout | | `types/` | DashboardSummary, VehicleNeedingAttention, RecentActivityItem | Type changes | ## Key Patterns - `useDashboardData()` returns summary stats, vehicles needing attention, and recent activity in a single query - RecentActivity combines fuel logs and maintenance records into a chronological feed - SummaryCards show zero-state CTAs linking to relevant pages ``` **Doc Fix 2 -- Document vehicleDisplay.ts in frontend/README.md** After Milestone 1, add to `frontend/README.md` Structure section: ```markdown - `src/core/utils/vehicleDisplay.ts` -- Shared vehicle display helpers: `getVehicleLabel()` (display name with fallback chain) and `getVehicleSubtitle()` (Year Make Model formatting). Used across vehicles, documents, dashboard, settings, and maintenance features. ``` **Doc Fix 3 (Recommended) -- Update fuel-logs/CLAUDE.md** After Milestone 12, add `AddFuelLogDialog.tsx` entry to the components table in `frontend/src/features/fuel-logs/CLAUDE.md`. --- ### Updated Review Status | Stage | Verdict | |-------|---------| | QR plan-completeness | PASS | | TW plan-scrub | PASS (Rev 1) | | QR plan-code | PASS (Rev 2) | | QR plan-docs | PASS (Rev 2) | *Verdict*: APPROVED | *Next*: Implementation on branch `issue-162-ux-design-audit-cleanup`
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
status
backlog
status/blocked
status
done
status
in-progress
status
ready
status
review
type
bug
type
chore
type
docs
type
feature
No Label
status
in-progress
type
chore
Milestone
No items
No Milestone Sprint 2026-02-02
Projects
Clear projects
No project
Assignees
Clear assignees
egullickson
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: egullickson/motovaultpro#162
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?