From 882a609c57c4805aa53d64eebb1041f019b21a83 Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Mon, 16 Mar 2026 12:43:01 +0100 Subject: [PATCH] docs(02): capture phase context --- .../02-CONTEXT.md | 99 +++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 .planning/phases/02-dashboard-charts-and-layout/02-CONTEXT.md diff --git a/.planning/phases/02-dashboard-charts-and-layout/02-CONTEXT.md b/.planning/phases/02-dashboard-charts-and-layout/02-CONTEXT.md new file mode 100644 index 0000000..d5f7d14 --- /dev/null +++ b/.planning/phases/02-dashboard-charts-and-layout/02-CONTEXT.md @@ -0,0 +1,99 @@ +# Phase 2: Dashboard Charts and Layout - Context + +**Gathered:** 2026-03-16 +**Status:** Ready for planning + + +## Phase Boundary + +Deliver the full dashboard chart suite — expense donut chart, grouped vertical bar chart (income budgeted vs actual), and horizontal bar chart (budget vs actual by category type) — inside a responsive 3-column layout with month navigation and memoized data derivations. Replaces the existing flat pie chart and progress bars. + + + + +## Implementation Decisions + +### Chart layout & arrangement +- 3-column grid on desktop — donut, vertical bar, and horizontal bar charts side by side in a single row +- Each chart wrapped in its own Card component (consistent with StatCard pattern) +- Responsive collapse on smaller screens — Claude's discretion on breakpoints +- Visual order: SummaryStrip first, chart row second, QuickAdd button moved below charts + +### Month navigation +- Arrow buttons for prev/next month plus a clickable month label that opens a dropdown for direct jump to any available month +- Month stored in URL search params (e.g. `/dashboard?month=2026-02`) — enables sharing links and browser back button +- When navigating to a month with no budget: show the month page with an empty prompt ("No budget for this month") and a create/generate option +- Dropdown lists all months that have budgets; arrow buttons allow navigating beyond existing budgets (showing empty prompt) + +### Chart empty states +- When a chart has no data: show a muted placeholder (greyed-out chart outline with text overlay) inside the chart card +- Donut chart with zero amounts (budget exists, nothing spent): show empty ring in neutral/muted color with $0 center label — indicates chart is "ready" +- When a brand new budget has no items at all: show individual placeholders per chart card independently (no combined empty state) + +### Donut chart styling +- Center label shows total expense amount only (formatted currency, no label text) +- Active sector expands on hover +- Custom legend — Claude's discretion on placement (below vs right side) based on 3-column layout constraints +- Uses existing category color CSS variables from palette.ts + +### Bar chart styling +- Vertical bar chart (income): budgeted bars in muted/lighter shade, actual bars in vivid category color — emphasizes actuals +- Horizontal bar chart (category type spend): budgeted bars muted, actual bars vivid +- Over-budget indicator: actual bar extends past budgeted mark with red accent (over-budget semantic color) — visually flags overspending +- All bars consume CSS variable tokens (no hardcoded hex values) + +### Claude's Discretion +- Responsive breakpoints for chart row collapse (3-col → stacked) +- Donut legend placement (below vs right side of chart) +- Chart tooltip content and formatting +- Exact spacing and typography within chart cards +- DashboardSkeleton updates for new layout +- Data memoization strategy (useMemo vs derived state) +- Month navigation placement (PageShell CTA slot vs own row) + + + + +## Specific Ideas + +No specific references — open to standard approaches within the established design system. + + + + +## Existing Code Insights + +### Reusable Assets +- `chart.tsx` (shadcn): ChartContainer with ChartConfig, initialDimension patch applied — use for all three charts +- `categoryColors` (palette.ts): CSS variable map for all 6 category types — use for chart fills +- `StatCard` / `SummaryStrip` (components/dashboard/): Already integrated in DashboardContent — keep as-is +- `DashboardSkeleton` (components/dashboard/): Mirrors current layout — needs updating for 3-column chart row +- `Card` / `CardHeader` / `CardContent` (ui/card.tsx): Wrap each chart in a Card +- `formatCurrency` (lib/format.ts): Currency formatting for chart labels and tooltips + +### Established Patterns +- Two-tier OKLCH color pattern: text colors at ~0.55 lightness, chart fills at ~0.65-0.70 (Phase 1 decision) +- Semantic status tokens: `--color-over-budget` (red) and `--color-on-budget` (green) available +- TanStack Query for data fetching: `useBudgetDetail(id)` returns budget + items with category joins +- `useBudgets()` returns all budgets list — can drive the month dropdown options +- Components accept `t()` as prop to stay presentational (Phase 1 pattern) + +### Integration Points +- `DashboardContent` component (DashboardPage.tsx:48): Currently orchestrates pie chart + progress bars — will be refactored to render 3 chart components +- `DashboardPage` (DashboardPage.tsx:256): Currently finds current-month budget by date prefix — needs refactoring for URL-param-driven month selection +- React Router: URL search params integration for month state +- `EXPENSE_TYPES` constant (DashboardPage.tsx:24): Already defines non-income category types — reusable for bar/donut data derivation + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 02-dashboard-charts-and-layout* +*Context gathered: 2026-03-16*