Dashboard Redesign

Feature: [one-line name — e.g., "Analytics dashboard redesign — overview tab"]

## What and why

Problem
[What's wrong with the current dashboard? Is it slow, missing data, hard to navigate, visually outdated, or failing to surface the right information? Who is affected and how often?]

Who this is for
[Specific user role and context — e.g., "Admins reviewing team usage weekly" or "PMs checking feature adoption daily"]

In scope
- [Specific tabs, panels, or sections being redesigned]
- [Data sources and metrics being displayed]
- [Filter and sort capabilities being added or changed]
- [New visualisation types being introduced]
- [Responsive breakpoints in scope]

Out of scope
- [Tabs or panels not being touched in this phase]
- [Metrics or data sources not included]
- [Export or reporting features deferred]
- [User role permissions changes not in scope]

Key behaviors
- When [user applies filter X], [what updates on the page and how quickly]
- When [user changes date range], [which components re-fetch and which don't]
- When [there is no data for the selected filters], [what the user sees — empty state, not a blank page]
- When [data is loading], [what the user sees — skeleton, spinner, or stale data with a loading indicator]
- When [user exports], [what format, what data, and what time range is included]
- When [user bookmarks the URL], [does the URL encode their current filter state?]

Edge cases
- What does the dashboard show for a brand-new account with no data?
- What happens when a data source is temporarily unavailable — does the whole dashboard fail or just the affected panel?
- What happens when a user's saved filters reference a segment or dimension that no longer exists?
- What does the dashboard show when the selected date range returns partial data (e.g., today, mid-day)?
- What happens to existing bookmarked URLs if the URL structure changes?
- What happens when the dataset is very large — does pagination apply, and where?
- What happens on a narrow viewport — which data is prioritised, which is hidden?

Open questions
- [Are filters persistent — saved to user preferences, encoded in URL, or session-only?]
- [What's the data refresh rate — real-time, every N minutes, or on manual refresh?]
- [Are there any existing saved views or bookmarked URLs that must not break?]
- [Is export in scope for this phase?]
- [Which metrics are sourced from which data tables or services?]
- [Are there any role-based visibility rules — e.g., admins see all data, members see only their own?]

## Coding agent context

Tech stack
[e.g., "Next.js 14, TypeScript, Recharts for visualisation, React Query for data fetching, PostgreSQL"]
[e.g., "Data aggregation runs in a separate analytics service — see /services/analytics/ for the query layer"]

Reference files
[e.g., "See /components/dashboard/ for existing dashboard components and layout structure"]
[e.g., "See /hooks/useDashboardFilters.ts for the existing filter state management pattern"]
[e.g., "See /components/EmptyState.tsx and /components/LoadingState.tsx for standard patterns — use these, do not create new ones"]

Patterns to follow
- [e.g., "Filter state is encoded in URL query parameters — follow the pattern in /hooks/useFilterParams.ts"]
- [e.g., "Data fetching uses React Query — see /hooks/useAnalyticsData.ts for the existing query pattern including staleTime and retry config"]
- [e.g., "Charts follow the Recharts wrapper pattern in /components/charts/ — do not use the Recharts API directly in page components"]

Do not
- [ ] Do not change URL structure for any tab or view that is currently live without adding redirects from the old URLs
- [ ] Do not remove or rename filter parameters that may be encoded in users' bookmarked URLs
- [ ] Do not auto-refresh data on a timer without a visible indicator and user control to pause it
- [ ] Do not render an empty or broken state when data is loading — use the existing skeleton components
- [ ] Do not fetch all dashboard data in a single request — each panel should fetch independently so partial failures don't break the whole page
- [ ] Do not hardcode date ranges or metric names — use the constants file
- [ ] Do not introduce new charting libraries — extend the existing Recharts wrapper

Acceptance criteria
- [ ] All existing bookmarked URLs load the correct view — or redirects are in place for any changed URLs
- [ ] Empty states display correctly for: no account data, no results for current filters, and data source unavailable
- [ ] Loading states display correctly — skeletons appear before data loads, not blank sections
- [ ] Filter state is correctly encoded in the URL and restored when the URL is shared or reopened
- [ ] Each dashboard panel fails independently — one panel's data error does not crash the others
- [ ] The dashboard is usable at the defined responsive breakpoints — no horizontal scroll on supported viewports
- [ ] Export produces the correct data for the current filter and date range selection (if in scope)
- [ ] Role-based visibility rules apply correctly — users only see data they are permitted to see
- [ ] Existing tests pass without modification