# MealPlanner UI Redesign Plan
## Nielsen's 10 Heuristics → Concrete Changes

### Classification: `large/high-risk` — full visual redesign + component library

---

## Phase 1: Design System Foundation
- [ ] Custom Tailwind config: color tokens (primary, semantic, surface), font scale, spacing scale, shadow scale, radius scale
- [ ] Install icon library (Lucide React — lightweight, tree-shakeable)
- [ ] Create shared components: Button, Badge, Card, Input, Select, Textarea, Toast, Skeleton, EmptyState, Modal, Tooltip
- [ ] Define animation tokens (Framer Motion — micro-interactions, page transitions)
- [ ] Dark mode foundation (class-based, not implementing yet)

## Phase 2: Global UX Improvements (Heuristics 1, 3, 5, 6, 7, 9)
- [ ] Toast notification system (React Hot Toast) — system status visibility
- [ ] Loading states: skeleton screens for every async view
- [ ] Error boundaries + graceful error recovery UI
- [ ] Empty states for all lists (no meals, no pantry items, no shopping list)
- [ ] Confirmation dialogs for destructive actions (delete, remove from pantry, never-suggest)
- [ ] Undo capability where possible (remove from pantry → "Undo" toast)
- [ ] Keyboard shortcuts reference (Cmd+K command palette? Maybe too ambitious. Start with basic: / for search, Esc to close modals)

## Phase 3: Dashboard Redesign (Heuristic 1, 2, 6, 8)
- [ ] Visual hierarchy: week header with clear date range, status summary chips
- [ ] Day columns with clear headers (Mon 5/12, Tue 5/13, etc.)
- [ ] Meal cards: better image handling (aspect ratio, fallback), clearer metadata, hover interactions
- [ ] Quick actions bar: "Generate Week", "Send Vote Email", "View Shopping List"
- [ ] Recent activity / system status panel (last scrape time, next vote date)
- [ ] Responsive: mobile-first card stack, desktop grid

## Phase 4: Meal Detail Redesign (Heuristic 2, 5, 8)
- [ ] Hero section: full-bleed image, recipe title, key metadata row (time, servings, cost, cuisine tags)
- [ ] Tabbed interface: Overview / Ingredients / Instructions / Feedback
- [ ] Ingredients: checkbox toggle "in pantry", visual quantity display, aisle grouping
- [ ] Instructions: numbered with visual separators, progress indicator
- [ ] Feedback: inline star rating (not a separate card), compact form, saved state indicator
- [ ] Print-friendly layout preserved

## Phase 5: Pantry Redesign (Heuristic 1, 5, 6, 8)
- [ ] Inline add (not expandable form — always visible, compact)
- [ ] Search + filter existing items
- [ ] Visual quantity badges, expiry warnings (color-coded)
- [ ] Bulk actions (select multiple → remove)
- [ ] Empty state with illustration + CTA

## Phase 6: Shopping List Redesign (Heuristic 1, 2, 6, 8)
- [ ] Summary header with total cost, savings, item count
- [ ] Aisle sections as collapsible accordions
- [ ] Checkbox strikethrough animation, "in cart" vs "in pantry" distinction
- [ ] Print layout: clean, no UI chrome
- [ ] Empty state when no items

## Phase 7: Login + Global Nav (Heuristic 1, 4, 8)
- [ ] Centered card with better spacing, icon, and visual focus
- [ ] Nav bar: active state indicator, mobile hamburger, user avatar dropdown
- [ ] Breadcrumbs on sub-pages
- [ ] Footer with version + system status

## Phase 8: Accessibility + Polish (Heuristic 9, 10)
- [ ] Focus rings on all interactive elements
- [ ] ARIA labels, roles, live regions for toasts
- [ ] Color contrast audit (WCAG AA)
- [ ] Reduced motion support
- [ ] Help tooltips on complex features (vote system, matching algorithm)

---

## Implementation Order
1. Install deps (lucide-react, framer-motion, react-hot-toast)
2. Tailwind config + base design tokens
3. Shared component library
4. Toast + loading infrastructure
5. Dashboard (highest traffic page)
6. Meal Detail
7. Pantry + Shopping List (parallel)
8. Login + Nav
9. Accessibility polish + error boundaries
10. Test responsive on mobile widths

## New Dependencies
```
npm install lucide-react framer-motion react-hot-toast
```

## Nielsen Mapping Summary
| Heuristic | Where addressed |
|---|---|
| 1. Visibility of status | Skeletons, toasts, loading spinners, progress indicators |
| 2. Match real world | Clear labels, familiar icons, calendar metaphor |
| 3. User control | Confirm dialogs, undo toasts, Escape to close |
| 4. Consistency | Design tokens, shared components, uniform spacing |
| 5. Error prevention | Form validation, disable buttons while loading, confirm destructive actions |
| 6. Recognition > recall | Visual badges, status chips, pantry checkboxes, recent activity |
| 7. Flexibility | Keyboard shortcuts, bulk actions, print layouts |
| 8. Aesthetic + minimal | Clean cards, whitespace, single primary action per view |
| 9. Error recovery | Error boundaries, friendly error messages, retry buttons |
| 10. Help | Empty state CTAs, tooltip hints, inline help text |