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

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.

<code_context>

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

</code_context>

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 02-dashboard-charts-and-layout Context gathered: 2026-03-16

4.9 KiB Raw Blame History