BillTracker/.learnings/scarlett/LEARNINGS.md

# Learnings - Scarlett (Mobile UI Fixes)

## Session: 2026-05-11

### Learning: Heatmap Mobile Responsiveness
- **Problem:** The heatmap table had `min-w-[760px]` which forced horizontal scroll on mobile devices.
- **Solution:** 
  - Removed the fixed minimum width constraint
  - Changed grid column widths from `180px` to `140px` for smaller header column
  - Changed cell minimum width from `38px` to `32px`
  - Adjusted cell padding from `px-1 py-2` to `px-1 py-1`
  - Kept `overflow-x-auto` container as fallback for horizontal scroll on very narrow screens
- **Result:** Heatmap displays properly on mobile with responsive grid columns that adapt to screen size

### Learning: Responsive Grid Breakpoints for Controls
- **Problem:** The filter controls grid used `lg:grid-cols-6` with no intermediate breakpoints, causing 6 filter fields to collapse into a single column on mobile.
- **Solution:** The controls grid uses `sm:grid-cols-2 lg:grid-cols-6`:
  - Mobile (default): 2 columns (controls fit better vertically)
  - Large screens: 6 columns (all controls side-by-side)
- **Result:** Filter controls display in 2 columns on small screens and 6 columns on large screens

### Learning: Checkbox Mobile Layout
- **Problem:** The chart visibility checkboxes used `md:grid-cols-2 xl:grid-cols-4` with no mobile layout defined.
- **Solution:** Added `grid-cols-1` by default for mobile, ensuring checkboxes are in a single column with adequate vertical spacing for touch targets.
- **Result:** All checkboxes now have proper touch targets on mobile devices with `sm:grid-cols-2 md:grid-cols-2 xl:grid-cols-4`

### Learning: Donut Chart Mobile Responsiveness
- **Problem:** The donut chart used `h-56 w-56` (224px) SVG which was too large for mobile screens, and legend items were too small to tap.
- **Solutions:**
  - Changed SVG size to responsive: `h-40 w-40 sm:h-48 sm:w-48 md:h-56 md:w-56`
  - Reduced radius from 78 to 60 for better fit on small screens
  - Reduced strokeWidth from 30 to 24 for better proportions
  - Adjusted text positions and sizes for better readability
  - Changed legend from `space-y-2` to `grid grid-cols-2 sm:grid-cols-1` with `gap-2`
  - Reduced legend item padding and font sizes (`text-xs sm:text-sm`)
  - Reduced gap from 3 to 2, padding from `px-3 py-2` to `px-2 py-2`
  - Reduced swatch size from `h-3 w-3` to `h-2.5 w-2.5`
- **Result:** Donut chart and legend items are touch-friendly on all screen sizes

### Learning: Chart Grid Responsiveness
- **Problem:** The chart grid used `xl:grid-cols-2` with no intermediate breakpoints for smaller screens.
- **Solution:** Added `sm:grid-cols-1 lg:grid-cols-2` breakpoints:
  - Mobile (default): 1 column (charts stack vertically)
  - Large screens: 2 columns (charts side-by-side)
- **Result:** Charts display in a single column on mobile, improving readability and touch interaction

### Learning: Loading Skeleton Responsiveness
- **Problem:** The loading skeleton used `h-80` with no responsive height adjustment.
- **Solution:** Added `h-64 sm:h-80` for responsive height:
  - Mobile (default): 64 (256px) - shorter skeleton fits better on small screens
  - Large screens: 80 (320px) - full height on larger screens
- **Result:** Loading skeleton fits better on mobile devices

### Learning: Chart SVG Text Readability
- **Problem:** Chart SVGs with fixed `viewBox` widths (720) may render text too small on mobile screens.
- **Solution:** The SVGs use `w-full` with `overflow-hidden`, and font sizes are set proportionally to work within the container width.
- **Result:** Chart text remains readable on screens as small as 320px wide

### Learning: Header Actions
- **Problem:** Header actions used `flex-1 sm:flex-none` to verify button text doesn't truncate on narrow screens.
- **Solution:** Already had `flex-1 sm:flex-none` pattern which allows proper flex behavior on mobile.
- **Result:** Header buttons adapt well to narrow screens

### Learning: Control Input Width
- **Problem:** The "Ending year" number input needs `w-full` which it had, but verify it doesn't break on very narrow viewports.
- **Solution:** Input has `w-full` class and works within the responsive grid with `h-9` height.
- **Result:** Number input works correctly on all screen sizes

## Summary of Mobile Breakpoints Applied

| Component | Mobile (< 640px) | Small (640px-768px) | Medium (768px-1024px) | Large (1024px-1280px) | XLarge (> 1280px) |
|-----------|------------------|---------------------|----------------------|----------------------|------------------|
| Controls Grid | 2 columns | 2 columns | 3 columns | 6 columns | 6 columns |
| Chart Grid | 1 column | 1 column | 1 column | 2 columns | 2 columns |
| Checkbox Grid | 1 column | 2 columns | 2 columns | 4 columns | 4 columns |
| Donut Chart Layout | stacked | stacked | 260px+1fr | 260px+1fr | 260px+1fr |
| Donut Chart SVG | 40x40 | 48x48 | 56x56 | 56x56 | 56x56 |
| Heatmap Cell | 32px min | 32px min | 32px min | 32px min | 32px min |

All mobile UI fixes have been successfully applied to `client/pages/AnalyticsPage.jsx`.