feat(dashboard): Epic — Elite Dashboard UX Overhaul

[ericsocrat]

Epic — Elite Dashboard UX Overhaul

Priority: P1 | Domain: Frontend / Dashboard
Scope: 5 sequential child issues, ~30 individual improvements
Goal: Transform the authenticated dashboard (/app) from a minimal MVP into a world-class, information-rich, delightful experience

---

Problem Statement

The TryVit dashboard currently renders only 5 of 14 available components, leaving ~60% of built intelligence invisible. Specific issues:

1. 9 fully-built components are orphaned — HealthInsightsPanel (+ 5 sub-components), NutritionTip, CategoriesBrowse, ScoreSparkline are complete with tests but never wired into page.tsx.
2. Bug: QuickWinCard links to wrong product — "View swap →" navigates to worstProduct.product_id (the unhealthy one) instead of alternative.product_id (the suggested swap). Users clicking the CTA see the bad product, not its better alternative.
3. HealthSummary uses a plain div instead of the existing animated ScoreGauge SVG ring component — missing stroke animation, arc fill, and visual hierarchy.
4. RecentlyViewed ignores available data — image_thumb_url and nutri_score_label fields are returned by the API but never rendered.
5. DashboardSkeleton is out of sync — renders categories + tips sections that don't exist on the real page, creating visual jarring on load→render transition.
6. DashboardGreeting.displayName prop is accepted but never passed from page.tsx, so personalized greetings never appear.
7. QuickActions are monochrome — all 4 icons are identical gray, with no color differentiation or count badges.
8. No entry animations — components appear instantly with no staggered reveal or visual delight.

---

UX Audit Reference

Full audit captured 24 gaps (G1-G24), 20 recommendations (R1-R20), and 8 animation enhancements (A1-A8). This epic implements all of them across 5 sequential PRs.

---

Child Issues (Sequential — each depends on the previous)

Issue 1 — Critical Fixes: QuickWinCard Bug, DisplayName, Seasonal Nudge, Skeleton Sync

Priority: P0/P1 | Effort: S
Covers: R3, R7, R8, R15, G11, G4, G5, G13

• Fix QuickWinCard "View swap →" href to link to alternative.product_id
• Wire displayName from Supabase user metadata into DashboardGreeting
• Elevate seasonal nudge from text-xs text-foreground-muted to a styled chip with seasonal emoji + leaf-green/amber background
• Rebuild DashboardSkeleton to match actual page composition (greeting → health summary → quick win → recently viewed → quick actions)

Issue 2 — ScoreGauge Integration + Animations

Priority: P1 | Effort: M
Covers: R2, R6, A1, A2, A4, G2, G6, G14

• Replace HealthSummary's plain h-16 w-16 rounded-full div with the ScoreGauge component (size="lg", 80px SVG ring with animated stroke)
• Add band distribution bar legend (dot + label + count beneath the bar)
• Add QuickWinCard score visualization using ScoreGauge (size="sm") instead of plain circles
• Add staggered fade-in-up entry animations to all dashboard sections (50ms offset per section)
• Add scale-in animation to ScoreGauge on mount
• Add pulse glow animation on the distribution bar segments

Issue 3 — Wire Dormant Components (HealthInsights, NutritionTip, CategoriesBrowse)

Priority: P1 | Effort: M
Covers: R1, R10, R11, G1, G7, G8, G9, G10

• Import and wire HealthInsightsPanel into page.tsx (after HealthSummary, inside ErrorBoundary)
• Import and wire NutritionTip into page.tsx (after QuickWinCard)
• Import and wire CategoriesBrowse into page.tsx (after RecentlyViewed, before QuickActions)
• Wrap each new section in ErrorBoundary with section-level context
• Verify getDashboardInsights API call works with staleTime from query-keys
• Update DashboardSkeleton to include skeleton rows for the 3 new sections

Issue 4 — RecentlyViewed Enrichment: Images, NutriScore, Time Badges

Priority: P2 | Effort: M
Covers: R4, R5, R13, R17, A3, A6, G3, G12, G15

• Add image_thumb_url rendering with lazy loading, rounded corners, and graceful fallback (colored initial circle)
• Add NutriScoreBadge (size="sm") next to each product row using the available nutri_score_label field
• Style the relative time badge (1m, 2h, 3d) as a subtle pill instead of plain text
• Add brand text with secondary styling beneath product name
• Add slide-in-right staggered entry animation (30ms offset) per product row
• Add shimmer loading effect during data fetch transition

Issue 5 — QuickActions Polish + Final Animations + Skeleton Finalization

Priority: P2 | Effort: M
Covers: R9, R12, R16, A5, A7, A8, G16, G17, G18

• Add distinct brand-colored backgrounds to QuickAction icons (scan=emerald, search=blue, compare=amber, lists=purple)
• Add count badges on QuickActions (e.g., lists count from dashboard stats)
• Add bounce-in entry animation to QuickAction buttons with 100ms stagger
• Add subtle hover:scale-105 on QuickAction icons
• Final DashboardSkeleton sync pass — ensure skeleton ↔ real page are 1:1
• Add motion-reduce media query respect (prefers-reduced-motion: reduce → disable animations)
• Overall visual polish pass: spacing, alignment, contrast audit

---

Implementation Rules

1. Sequential PRs — each child issue gets its own branch + PR, merged before the next begins
2. Screenshot verification — run .\RUN_PR_SCREENSHOTS.ps1 after each implementation to visually verify
3. Tests required — every component change must include updated unit tests
4. ALL CI checks must pass — including non-required (CodeQL, Lighthouse, Vercel, etc.) before merge
5. Clean branches — delete remote branches after merge
6. No breaking changes — all changes are additive improvements to existing components

---

File Impact Summary

Estimated: ~25 files, +800 / -200 lines across all 5 issues

• 0 DB migrations (frontend-only epic)
• 0 API changes (using existing RPC responses)
• ~15 modified frontend component files
• ~15 modified/new test files
• 1 skeleton file rebuilt
• i18n updates: 0 new keys expected (all keys already exist in en/pl/de)

---

Definition of Done

• All 5 child issues implemented, tested, screenshot-verified, and merged
• cd frontend && npx tsc --noEmit — 0 errors
• cd frontend && npx vitest run — all pass, coverage ≥ baseline
• cd frontend && npx playwright test --project=smoke — all pass
• Dashboard screenshot comparison: before vs after shows all improvements
• QuickWinCard bug confirmed fixed (navigates to alternative product)
• 9 dormant components are now visible on the dashboard
• Entry animations render on mobile (390×844 viewport)
• prefers-reduced-motion: reduce disables all animations

[ericsocrat]

Epic Complete — All 5 issues shipped ✅

Issue	PR	Summary	Merged
#961	#966	Accessible loading & empty states	7848e4f8
#962	#967	Animation & visual polish	264ce46f
#963	#969	Wire dormant components	f4c04013
#964	#970	RecentlyViewed enrichment	7aa51068
#965	#971	QuickActions polish — colored icons, count badges, bounce-in	b39268f0

All CI checks passed on every PR. Dashboard UX significantly improved across loading states, animations, data wiring, and visual polish.