makiolaj/SimpleFinanceDash
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete project research

Browse Source
This commit is contained in:
Jean-Luc Makiola
2026-04-02 15:30:56 +02:00
parent 8fdab4b796
commit 0b72f1c305
5 changed files with 1204 additions and 1010 deletions
Download Patch File Download Diff File Expand all files Collapse all files

331
.planning/research/FEATURES.md
View File

@@ -1,16 +1,24 @@
# Feature Research
**Domain:** Personal finance budget dashboard (UI presentation layer overhaul)
**Researched:** 2026-03-16
**Confidence:** HIGH — grounded in competitor analysis (YNAB, Empower), industry design guides, and direct codebase inspection
**Domain:** Personal budget app — wizard-driven setup, auto-budget creation, simplified monthly tracking UX
**Researched:** 2026-04-02
**Confidence:** MEDIUM — grounded in competitor analysis (YNAB, Monarch, EveryDollar, Actual Budget, Quicken Simplifi, Copilot) and UX/fintech design literature. Some specifics are inferred from behavioral patterns; no first-party user testing data.
---
## Context
This research covers the **presentation layer** only. Backend schema and data model are frozen. The question is: what UI/UX features make a personal finance dashboard feel polished rather than basic, and which of those apply to this project's existing data model (income, bills, variable expenses, debt, savings, investments — budgeted vs actual)?
This research covers v2.0 UX Simplification. The existing app already has all the data infrastructure — categories (6 types), template system, monthly budget generation, quick-add library, dashboard with charts. The problem is cognitive: too many disconnected concepts, friction in getting a budget running, and no guided experience for new users.
The existing stack is React 19 + Tailwind CSS 4 + Recharts + shadcn/ui. All chart capabilities already exist in Recharts; this research identifies how to use them well.
The research question: **How do personal budget apps handle first-run wizard setup, auto-creation from template, and simplified monthly views?** What is table stakes, what differentiates, and what should be avoided?
Existing features that remain and are not re-researched here:
- Category CRUD
- Template item management
- Budget detail with inline editing
- Charts (donut, bar, horizontal bar)
- Collapsible dashboard sections
- Settings (locale, currency)
---
@@ -18,23 +26,18 @@ The existing stack is React 19 + Tailwind CSS 4 + Recharts + shadcn/ui. All char
### Table Stakes (Users Expect These)
Features users assume exist. Missing these = product feels incomplete.
Features users assume exist. Missing these = product feels incomplete or broken.
| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Summary KPI cards at the top | Every finance dashboard leads with top-line numbers (income, total spend, balance). Users scan these first — it's the entry point to understanding the month. | LOW | Already exists but needs richer visual treatment: larger numbers, colored icons, clearer hierarchy |
| Green/red semantic color coding for over/under budget | Finance convention: green = on track, red = over budget. Violating this creates cognitive friction. | LOW | Already exists on progress bars and difference cells; must be consistent across all new chart types |
| Donut/pie chart for expense category breakdown | Standard visualization for "how is spending distributed." Users expect to see the breakdown at a glance. | LOW | Existing pie is plain; needs inner radius (donut), center total label, and richer color fills |
| Budget vs actual per category | The core comparison every budget tool offers. Users come here specifically to compare what they planned to what they actually spent. | MEDIUM | Existing progress bars satisfy this minimally; new grouped/horizontal bar charts will fulfill it properly |
| Inline value editing on budget detail | Users need to log actuals inline — no one wants a separate form for every line item. | LOW | Already implemented in BudgetDetailPage as InlineEditCell; keep and refine |
| Loading state that reflects page structure | If the page renders blank or flashes, users distrust the data or think it's broken. | LOW | Currently returns `null` during load — skeleton cards matching the final layout are expected |
| Empty state with actionable guidance | A blank dashboard for a new month should tell the user what to do next, not just show nothing. | LOW | Currently shows plain muted text; needs a CTA card pattern |
| Tabular-numeral formatting throughout | Financial amounts must use tabular (monospaced number) alignment so columns read correctly. | LOW | Already applied via `tabular-nums`; extend to all new components |
| Color-coded category identity | Users build a mental map: bills are orange, savings are blue. Consistent color per category type is required everywhere — charts, tables, badges. | LOW | Palette already defined in `index.css` and `palette.ts`; extend consistently to new components |
| Collapsible / grouped sections per category type | Budget detail and dashboard both group items by type. Users expect to expand/collapse groups, especially with many line items. | MEDIUM | BudgetDetailPage already groups by type; dashboard needs collapsible inline sections as new feature |
| Month navigation on the dashboard | Users want to check a prior month without navigating away. "Looking at last month" is a top-3 use case for any budget tool. | MEDIUM | Not in current dashboard (auto-resolves current month only); needs month selector |
| Totals row / footer per section | Standard pattern from spreadsheets. Each category group needs a sub-total visible without counting rows. | LOW | Already in BudgetDetailPage table footer; needs equivalent on dashboard sections |
| Consistent design language across all pages | Auth pages, settings, categories, and budget list must feel like the same product as the dashboard. Inconsistency signals amateur work. | HIGH | Currently only dashboard is styled; all other pages need the same card/color/typography treatment |
| Wizard-style first-run setup | Every modern app (YNAB, EveryDollar, Monarch) guides new users through initial setup — no blank-slate drop. Blank-state is a known retention killer for budget apps. | MEDIUM | Multi-step flow: income → recurring items → review. Must be skippable per step. |
| Pre-filled category items with common defaults | Users expect "rent," "groceries," "car insurance" to already be there — not to type everything from scratch. YNAB's Beginner Template and Quicken Simplifi both provide starter category lists. | LOW | Pre-seed the wizard with a curated list of ~15-20 common items grouped by type. User selects/deselects, edits amounts. |
| Auto-created budget on first month visit | After setup, users expect a budget to exist for the current month without a separate "generate budget" step. The manual trigger pattern is a v1-era pattern that creates friction. Quicken Simplifi does this with its Spending Plan. | MEDIUM | Trigger auto-generation server-side when a user visits the current month and no budget exists. |
| Ability to skip setup and start minimal | Power users and returning users want to start blank or skip ahead. Forcing everyone through a wizard is patronizing. | LOW | Each wizard step needs a "Skip" option. Entire wizard skippable via "I'll set this up later." |
| Inline add-from-library on the budget view | Users expect to add a one-off expense from their familiar item list without navigating away. The current separate Quick-Add page is a disconnect. Spendee and Actual Budget surface this inline. | MEDIUM | Replace Quick-Add page with an inline panel/sheet triggered from the budget view. Category + item picker, amount field, confirm. |
| Monthly budget shows budgeted vs actual, grouped | The core interaction loop: open budget, see what's in each category, enter actuals. Every app (YNAB, EveryDollar, Actual Budget) organizes this as grouped rows with a budgeted amount and an actuals field. | LOW | Already exists in the current BudgetDetailPage. Table stakes means this must work correctly and clearly — not changed, just verified. |
| Dashboard = this month's budget at a glance | Users want to open the app and immediately know their status: income, spending, balance. Not a chart gallery. Monarch and Copilot both lead with a "current month" summary card. | LOW | Dashboard must surface current month's data prominently — summary cards first, then detail. Already partially true; needs data correctness fix. |
| Empty state with clear call to action | If no template is set up, the app must explain what to do — not just show a blank page. "Set up your budget template" with a single action button. | LOW | Applies to: empty template page, empty budget view, empty dashboard. |
### Differentiators (Competitive Advantage)
@@ -42,16 +45,12 @@ Features that set the product apart. Not required, but valued.
| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| Grouped bar chart: income budgeted vs actual | Directly answers "Did I earn what I expected this month?" in a single visual. Most basic dashboards skip this, showing only expense charts. | MEDIUM | Recharts `BarChart` with two `Bar` components (budgeted / actual); use category colors |
| Horizontal bar chart: spend by category type (budget vs actual) | Lets users scan over-budget categories at a glance. Horizontal orientation makes labels readable without rotation. | MEDIUM | Recharts `BarChart layout="vertical"` with `XAxis type="number"` and `YAxis type="category"` |
| Donut chart with center total label | Center label turns the chart from decorative into informational — shows total spend while the ring shows distribution. YNAB and Empower both do this. | LOW | Recharts `Label` component inside `Pie` using `viewBox` coordinates for positioned text |
| Active sector hover highlight on donut | Hovering a slice expands it slightly and shows the category name + amount in a tooltip. Feels interactive and polished vs a static chart. | LOW | Recharts `activeShape` with expanded `outerRadius` — supported natively |
| Variance indicator (delta arrows) | Show "▲ 12% over" or "▼ 5% under" beside actual amounts on summary cards and section headers. Transforms raw numbers into directional insight. | LOW | Computed from budgeted/actual; render as small colored badge or arrow icon |
| Accent-colored card borders / icon containers | Rich visual style: each category section gets its palette color as a left border accent or icon container fill. Breaks the sea-of-grey-cards look. | LOW | Tailwind `border-l-4` or `bg-[color]/10` container with category CSS variable |
| Section collapse persisted in localStorage | Remembering which sections are open avoids users re-expanding the same sections every visit. Small touch that signals quality. | LOW | Simple `useState` + `localStorage` read/write; wrap in a `useCollapse` hook |
| Carryover amount visible on dashboard | The budget model already tracks `carryover_amount`. Showing it alongside the available balance makes the "running total" story clear. | LOW | Surface as a fourth summary card or sub-label on the balance card |
| Skeleton loading that mirrors the real layout | Animated skeleton cards/charts during load feel like the app is fast and predictable. Blank screens feel broken. | LOW | shadcn/ui `Skeleton` component already available; wrap summary cards and chart containers |
| Page header with budget month name | Every page in the app should show context: "March 2026 Budget." Users confirm they're looking at the right period immediately. | LOW | Format `budget.start_date` as "Month YYYY" in the page heading |
| Smart amount suggestions during wizard setup | Rather than blank amount fields, prefill with sensible defaults (e.g., $1,500 for rent, $400 for groceries) that users can override. Reduces the "I don't know what to put here" paralysis. Most apps leave this blank. | LOW | Can be static defaults (not AI). Store suggested amounts per item type in a constant/config. User edits freely. |
| "Start from your income" wizard framing | Frame setup as: "First, how much do you earn each month?" then "Here are common expenses people like you track." Income-first anchoring mirrors zero-based budgeting mental model (YNAB's core concept) and makes subsequent amounts feel grounded. | LOW | First wizard step = income amount. Subsequent steps show remaining balance updating as items are added — "you have $X left to allocate." |
| Running balance display during wizard | As the user adds items in the wizard, show "Remaining to allocate: $X" updating live. Makes it immediately obvious if they're over-allocating. This is YNAB's core interaction loop, applied to setup. | LOW | Derived from: income total minus sum of bill/expense/debt/saving/investment items. Frontend computation only. |
| Persistent sidebar "this month" widget on dashboard | A small always-visible card showing remaining balance for the month, top 2-3 categories near limit, and a "View full budget" link. Eliminates the need to navigate away to check status. Copilot uses this pattern. | MEDIUM | Requires current month budget query always running. Can be a sticky sidebar panel on the dashboard page rather than a global element. |
| Auto-create silently, notify only on first creation | First-time users see a brief notification "Your March budget was created from your template." Subsequent months: silently created, no notification. This is the right default — zero friction for users who've set up their template. | LOW | Backend: check if budget for current month exists on page load; create if not. Frontend: show a toast only if a new budget was just created. |
| Template edit directly accessible from monthly view | If a user wants to permanently change a recurring item (e.g., rent went up), they should be able to jump to the template from the budget view without hunting through the nav. | LOW | An "Edit template" link on the budget page or a per-item "Save to template" action. Single nav jump, no modal complexity. |
### Anti-Features (Commonly Requested, Often Problematic)
@@ -59,91 +58,87 @@ Features that seem good but create problems in this context.
| Feature | Why Requested | Why Problematic | Alternative |
|---------|---------------|-----------------|-------------|
| Trend / multi-month charts | Users always ask "can I see my spending over 6 months?" | Requires multi-budget data aggregation, a new query shape, and a new chart layout — out of scope for a UI-only overhaul. Adding it half-baked is worse than not adding it. | Explicitly defer to a future milestone. Put a placeholder card with "Coming soon" if needed. |
| Dark mode toggle | Professional apps always have a dark mode. | Tailwind CSS 4 dark mode via class strategy is possible, but requires auditing every component's contrast, chart colors, and skeleton states. Doing it properly doubles testing surface. The OKLCH color system is set up with dark mode in mind, but no dark palette is currently defined. | Define as a future phase deliverable. Keep the existing light-only approach consistent and polished first. |
| Real-time sync / live updates | "What if two tabs are open?" | No backend changes allowed this milestone. Supabase realtime would require schema changes and subscription setup. The current TanStack Query polling pattern is sufficient. | Rely on query invalidation on mutation — already in place. |
| Drag-to-reorder line items | Power users want custom sort order | Category `sort_order` field exists, but updating it requires PATCH calls and animation logic. No backend changes in scope. | Keep current `sort_order` from DB; do not expose drag handles this milestone. |
| Glassmorphism / heavy blur effects | Trendy, visually striking | `backdrop-blur` on many elements is GPU-heavy and can degrade performance on lower-end machines. Also risks reducing text readability on charts. Misapplied, it obscures data rather than enhancing it. | Use solid cards with subtle colored-border accents instead. Reserve `backdrop-blur` for a single hero element if at all. |
| AI / natural language budget insights | Feels modern, seen in apps like Copilot | Requires an AI backend, a new API integration, and user data being sent to a third-party service — none of which are part of a UI-only overhaul. | Surface static insights from computed data instead: "You spent 15% more on bills than budgeted this month." Computed in the frontend, no AI needed. |
| Infinite scroll on budget list | "I have many months of budgets" | Adds complexity to the budget list query and requires scroll position management. The budget list is unlikely to have more than 24 entries in a year of use. | Standard paginated or full list with a search/filter input is sufficient. |
| AI-suggested amounts based on spending history | "Smart defaults should learn from me over time" | Requires enough historical data (users don't have it at setup), an ML model or LLM call, and privacy tradeoffs. The payoff is low when static defaults work fine for first-run. | Static curated defaults per item type. After 3+ months of use, a "Review your template" prompt is sufficient. |
| Mandatory wizard (no escape) | "Force users to complete setup so they have a working budget" | Patronizing for returning users; creates frustration for users who want to explore before committing. YNAB's old onboarding got negative feedback for being too locked-in; they added a flexible checklist in Oct 2025 for this reason. | Skippable wizard with a prominent resume-later CTA. Show a "Complete setup" banner if template is empty. |
| Auto-sync with bank accounts | "Automatically populate actuals from transactions" | Plaid/bank integrations add significant infrastructure cost, security scope, and maintenance burden. Out of scope for a self-hosted personal tool. | Manual actual entry (inline editing, already implemented) with optional import as a future feature. |
| Complex wizard with 6+ steps | "Guide the user through every aspect of budgeting" | Drop-off increases sharply with each step beyond 3. Users who see step 4 of 7 abandon setup entirely. | Max 3 steps: (1) Income, (2) Recurring items, (3) Review + confirm. Everything else is editable post-setup. |
| Per-item recurrence configuration in wizard | "Let users set whether each item is weekly, monthly, etc." | Adds decision burden during setup. The app model is monthly budgeting — every item is implicitly monthly. Edge cases (weekly, biweekly) should be post-setup configuration. | Monthly-only assumption during wizard. Users can edit frequency on the template page after setup. |
| Gamification / streaks for budget tracking | "Engage users to check in daily" | Budget apps that add gamification often feel gimmicky for a personal finance tool. The target user is tracking a spreadsheet replacement — they want data, not achievements. | Progress indicators (spent X% of budget) provide motivation without game mechanics. |
| Duplicate "Quick Add" page alongside inline add | "Keep the existing page and add inline too" | Two ways to do the same thing creates confusion about which to use. The standalone Quick Add page has no added value over an inline approach. | Replace entirely with inline add-from-library on the budget view. Remove the nav link for the old Quick Add page. |
---
## Feature Dependencies
```
Donut Chart with Center Label
└──requires──> Category color system (already exists)
└──requires──> Recharts Label component in Pie (Recharts native)
Wizard Setup
└──requires──> Pre-seeded library items (common defaults in DB or seed data)
└──requires──> Template CRUD (already exists)
└──produces──> Populated template (unlocks auto-creation)
└──enhances──> Smart amount suggestions (display layer only)
└──enhances──> Running balance during wizard (computed from income + items)
Horizontal Bar Chart (budget vs actual by type)
└──requires──> Category color system (already exists)
└──requires──> Grouped data by category type (already in DashboardContent)
Auto-Budget Creation
└──requires──> Populated template (wizard must complete, or manual template setup)
└──requires──> Backend trigger logic (check if budget for month exists; create if not)
└──produces──> Current month budget (unlocks simplified budget view)
└──enhances──> Silent creation toast (frontend notification, optional)
Grouped Bar Chart (income budget vs actual)
└──requires──> Income items filtered from BudgetItems (already in DashboardContent)
Simplified Budget View (inline add from library)
└──requires──> Current month budget exists (auto-creation must fire first)
└──requires──> Category library with quick-add items (already exists as quick_add_items table)
└──replaces──> Standalone Quick Add page (remove from nav)
└──enhances──> Budget detail (adds inline picker panel alongside existing inline editing)
Collapsible Dashboard Sections
└──requires──> Category group data (already derived)
└──enhances──> Section collapse persistence (localStorage)
└──enhances──> Totals row per section (already exists in BudgetDetailPage)
Dashboard = This Month at a Glance
└──requires──> Current month budget exists (auto-creation must fire first)
└──requires──> Budget data correctness fix (tracked separately)
└──depends-on──> Simplified budget view (users need to be able to add actuals quickly)
Skeleton Loading
└──requires──> Final layout structure (must design layout first)
└──depends-on──> Summary cards layout (build cards first, then wrap in Skeleton)
Month Navigation on Dashboard
└──requires──> Budgets list query (already in useBudgets)
└──conflicts──> Auto-resolve current month (replace with explicit selection)
Consistent Design Language (all pages)
└──depends-on──> Dashboard redesign being finished first (establishes the design token/component pattern)
└──applies-to──> LoginPage, RegisterPage, CategoriesPage, TemplatePage, BudgetListPage, BudgetDetailPage, QuickAddPage, SettingsPage
Variance Indicators (delta arrows)
└──requires──> budgeted_amount and actual_amount both available (already on BudgetItem)
└──enhances──> Summary cards (add % change sub-label)
└──enhances──> Collapsible section headers (show group variance at a glance)
Template Edit from Budget View
└──requires──> Template page (already exists)
└──enhances──> Simplified budget view (provides escape hatch to change recurring items)
```
### Dependency Notes
- **Skeleton loading requires final layout:** Don't implement skeleton states until the target card/chart layout is finalized — skeleton shape must mirror real content shape.
- **All-pages redesign depends on dashboard:** The dashboard establishes the color system application patterns (accent borders, card styles, typography scale) that all other pages will inherit.
- **Month navigation conflicts with auto-resolve:** The current pattern auto-finds the budget for the current calendar month. Adding a selector means the dashboard must hold local `selectedBudgetId` state rather than computing it.
- **Donut center label requires Recharts Label:** shadcn/ui's chart system supports this natively via the `Label` component inside `Pie` using `viewBox` coordinates. No new library needed.
- **Wizard depends on pre-seeded library:** The wizard presents pre-filled common items. These must exist in the database (or a constants file) before the wizard can show them. This is the foundational data concern for v2.0.
- **Auto-creation depends on template having content:** If the user skips the wizard entirely, auto-creation generates an empty budget (no items). The UI must handle this gracefully — show empty-state with "Set up your template" CTA.
- **Inline add replaces Quick Add page:** This is a replacement, not an addition. The Quick Add page should be removed from the nav. The backend endpoint it uses can be repurposed or kept as the inline add trigger.
- **Dashboard correctness is a prerequisite:** The "dashboard = this month at a glance" feature is only meaningful if the data it displays is accurate. Data correctness fix must happen before or alongside the dashboard simplification.
---
## MVP Definition
This is a UI overhaul milestone, not a greenfield product. "MVP" here means: what must ship for the redesign to feel complete and polished?
This is v2.0 of an existing working app. "MVP" here means: what is the minimum set of changes that delivers the simplified UX without regressions?
### Launch With (v1 — Dashboard Overhaul)
### Launch With (v2.0 — Core UX Simplification)
- [ ] Summary cards with richer visual treatment (larger numbers, semantic color on balance, variance badge) — foundation of the dashboard
- [ ] Donut chart with center total label and active sector hover — replaces existing flat pie
- [ ] Horizontal bar chart (budget vs actual by category type) — new chart, satisfies the key "am I on track" question
- [ ] Grouped bar chart (income budget vs actual) — completes the three-chart suite from the reference
- [ ] Collapsible inline sections per category group on dashboard (with line items + group totals) — replaces current progress bars
- [ ] Skeleton loading states for cards and charts — removes the jarring blank-then-rendered experience
- [ ] Month navigation control (budget period selector) on dashboard — without this the dashboard is locked to current month only
- [ ] Wizard-style template setup — 3-step flow: income → common items (pre-filled, editable) → review — skippable
- [ ] Pre-seeded library with ~15-20 common items grouped by category type (rent, car insurance, groceries, utilities, car payment, etc.)
- [ ] Smart amount defaults in wizard (static sensible values per item — not AI)
- [ ] Running balance during wizard (income minus sum of selected items)
- [ ] Auto-create current month budget from template on first visit (backend trigger, silent)
- [ ] Toast notification on first auto-creation only ("Your April budget was created from your template")
- [ ] Inline add-from-library on the budget view (replaces Quick Add page)
- [ ] Remove Quick Add from navigation
- [ ] Dashboard summary cards correctly reflect current month budget data
- [ ] Empty state CTAs for: empty template, empty dashboard, empty budget
### Add After Dashboard Phase (v1.x — Full App Polish)
### Add After Core Ships (v2.x)
- [ ] Consistent card/color design applied to BudgetDetailPage — users navigate here from the dashboard; it must match
- [ ] Consistent design applied to BudgetListPage — entry point from nav, feels disconnected from dashboard without polish
- [ ] Consistent design applied to CategoriesPage and TemplatePage — setup pages; lower urgency but visible gap
- [ ] Consistent design applied to LoginPage and RegisterPage — first impression; polish matters
- [ ] Consistent design applied to QuickAddPage and SettingsPage — utility pages; can ship slightly after core flows
- [ ] Section collapse state persisted to localStorage — nice-to-have UX polish
- [ ] "Edit template" shortcut from budget view — once core flow is working, add the escape hatch
- [ ] Persistent "this month" summary widget on dashboard — adds value once data is correct
- [ ] "Complete setup" banner for users who skipped wizard but have empty template
- [ ] Wizard resume-later state (save partial wizard progress) — only needed if drop-off is observed
### Future Consideration (v2+)
### Future Consideration (v3+)
- [ ] Trend charts over multiple months — deferred explicitly in PROJECT.md out-of-scope
- [ ] Dark mode — foundational work (OKLCH variables) exists but needs full audit and dark palette definition
- [ ] AI-derived spending insights — requires backend changes; no scope here
- [ ] Drag-to-reorder categories — requires sort_order mutation support
- [ ] Income-based spending recommendations (percentages by category type)
- [ ] "Review your template" prompt after 3 months of use
- [ ] CSV/bank import for actuals — mentioned as future feature in PROJECT.md
- [ ] Recurring transaction automation — mentioned as future in PROJECT.md
---
@@ -151,94 +146,116 @@ This is a UI overhaul milestone, not a greenfield product. "MVP" here means: wha
| Feature | User Value | Implementation Cost | Priority |
|---------|------------|---------------------|----------|
| Summary cards — richer visual treatment | HIGH | LOW | P1 |
| Donut chart with center label + active hover | HIGH | LOW | P1 |
| Horizontal bar chart (spend vs budget by type) | HIGH | MEDIUM | P1 |
| Grouped bar chart (income budget vs actual) | HIGH | MEDIUM | P1 |
| Collapsible dashboard sections with line items | HIGH | MEDIUM | P1 |
| Skeleton loading states | MEDIUM | LOW | P1 |
| Month navigation on dashboard | HIGH | MEDIUM | P1 |
| Consistent design on BudgetDetailPage | HIGH | MEDIUM | P1 |
| Consistent design on BudgetListPage | MEDIUM | LOW | P2 |
| Variance indicators (delta arrows/badges) | MEDIUM | LOW | P2 |
| Accent-colored category section borders | MEDIUM | LOW | P2 |
| Carryover amount visible on dashboard | MEDIUM | LOW | P2 |
| Consistent design on auth/settings/utility pages | LOW | MEDIUM | P2 |
| Section collapse persisted in localStorage | LOW | LOW | P3 |
| Empty state with action guidance | MEDIUM | LOW | P2 |
| Wizard setup (3-step, skippable) | HIGH | MEDIUM | P1 |
| Pre-seeded library items (15-20 defaults) | HIGH | LOW | P1 |
| Smart amount defaults in wizard | MEDIUM | LOW | P1 |
| Running balance during wizard | HIGH | LOW | P1 |
| Auto-create budget on month visit | HIGH | MEDIUM | P1 |
| Dashboard data correctness fix | HIGH | MEDIUM | P1 |
| Inline add-from-library on budget view | HIGH | MEDIUM | P1 |
| Remove Quick Add page from nav | MEDIUM | LOW | P1 |
| Empty state CTAs (template, dashboard, budget) | MEDIUM | LOW | P1 |
| Silent creation with first-time toast | MEDIUM | LOW | P2 |
| "Edit template" link from budget view | MEDIUM | LOW | P2 |
| Persistent "this month" dashboard widget | MEDIUM | MEDIUM | P2 |
| "Complete setup" banner for empty template | LOW | LOW | P2 |
| Wizard resume-later persistence | LOW | MEDIUM | P3 |
**Priority key:**
- P1: Must have for the overhaul to feel complete
- P2: Should have; include in same milestone if effort allows
- P3: Nice to have; add as polish after core delivery
- P1: Must ship for v2.0 to feel complete
- P2: Should have; include if effort allows
- P3: Nice to have; future consideration
---
## Competitor Feature Analysis
| Feature | YNAB | Empower (formerly Personal Capital) | Our Approach |
|---------|------|--------------------------------------|--------------|
| Summary KPI cards | Yes — "Available" balance prominent | Yes — net worth headline | 3 cards: Income / Expenses / Balance |
| Budget vs actual bars | Yes — horizontal category bars with color (green/yellow/red) | Cash flow bars | Horizontal bar chart per category type |
| Donut / pie chart | No (YNAB uses different visualization) | Yes — allocation donut for investments | Donut with center total, colored by category type |
| Collapsible grouped sections | Yes — master categories expand to show sub-categories | No — flat list | Collapsible per category type (income, bills, etc.) |
| Inline editing | Yes — click amount to edit | No | Keep existing InlineEditCell pattern, refine styling |
| Color-coded categories | Yes — status colors (green/yellow/red) | Category colors for accounts | Per-type semantic color (income=green, debt=red/pink, etc.) |
| Month/period navigation | Yes — budget period selector in sidebar | Yes — date range selector | Month selector on dashboard |
| Skeleton loading | Yes — YNAB shows skeleton on load | Yes | Skeleton cards + chart placeholders |
| Variance / delta indicators | Yes — shows "over by $X" inline | Yes — shows gain/loss % | Variance badge on summary cards and section headers |
| Feature | YNAB | Monarch Money | EveryDollar | Quicken Simplifi | Our Approach |
|---------|------|---------------|-------------|------------------|--------------|
| First-run wizard | Flexible checklist (Oct 2025 update); Beginner Template to import categories | Guided category setup on signup; AI auto-categorizes after account link | Wizard-style setup; named "best for newbies" | Template import + Spending Plan auto-setup | 3-step wizard: income → items → review |
| Pre-filled defaults | Beginner Template with common categories (mortgage, groceries, vacation) | Default category list; user trims | Pre-loaded category list | Category templates to import | ~15-20 curated items, editable in wizard |
| Auto-budget creation | Manual monthly allocation required ("assign every dollar") | Spending Plan auto-projects from past data + recurring detected | Manual each month; no auto-create | Spending Plan auto-calculates and updates | Auto-create from template on month visit; silent |
| Add expense inline vs separate | Inline per category row; no separate page | Inline transaction entry | Separate transaction entry form | Inline via Spending Plan category rows | Inline panel on budget view; Quick Add page removed |
| Dashboard focus | "To be budgeted" balance + category status | Monthly spending summary + goals | Zero-based plan + remaining | Spending Plan summary + bills calendar | Summary cards (income/expense/balance) + current month budget |
| Skippable setup | Yes (since Oct 2025 checklist) | Yes | Limited | Yes | Yes — every step skippable |
---
## Chart Design Notes (Recharts-Specific)
## Wizard Flow Design Notes
These translate research findings into concrete implementation guidance for the Recharts stack.
Based on research into YNAB, EveryDollar, and UX onboarding best practices, the recommended wizard structure is:
**Donut chart:**
- Use `innerRadius={60}` to `innerRadius={72}` for a modern ring look (not too thin)
- Place center total using `<Label>` with `content` prop inside `<Pie>` using `viewBox` cx/cy coordinates
- Use `activeShape` with `outerRadius + 10` for hover expansion
- Add `isAnimationActive` to respect `prefers-reduced-motion`
- Legend as a separate `<ul>` below the chart (not Recharts built-in legend) for full styling control
**Step 1 — Income**
- Single question: "What's your monthly take-home income?"
- Single number input + currency formatting
- Skip option: "I'll add this later"
- Sets the anchor for running balance in step 2
**Horizontal bar chart (budget vs actual by type):**
- `<BarChart layout="vertical">` with `<XAxis type="number">` and `<YAxis type="category">`
- Two `<Bar>` components — one for budgeted (muted/secondary color) and one for actual (category color)
- Set `barSize` to keep bars compact; use `barCategoryGap` for breathing room
- `<LabelList position="right">` for actual amounts visible on bar ends
- Never start X axis at a non-zero value
**Step 2 — Recurring Items**
- Pre-loaded list of common items grouped by type (bills, variable expenses, debts, savings, investments)
- Each item has a checkbox (on by default for high-likelihood items, off for lower-likelihood)
- Editable amount field per item (prefilled with static sensible default)
- Running balance updates live: "Remaining to allocate: $X"
- "Add custom item" inline for items not in the list
- Skip option: "I'll set this up manually"
**Grouped bar chart (income budget vs actual):**
- Standard `<BarChart>` with `layout="horizontal"` (default)
- Two `<Bar>` groups: budgeted (muted fill) and actual (category color)
- `<CartesianGrid vertical={false}>` to reduce visual noise
- Custom `<ChartTooltip>` showing both values with currency formatting
**Step 3 — Review**
- Summary of selected items by group
- Total income, total allocated, remaining
- "Create my template" CTA — writes to the template table
- "Go back" link to step 2
**Color system:**
- All charts must consume CSS variables from the existing OKLCH palette (`var(--color-income)`, etc.)
- Never hardcode hex values in chart components — use the `categoryColors` map from `palette.ts`
- Green/red semantic colors for over/under-budget states must be distinct from category colors
**Post-wizard:**
- Auto-create current month budget from template (immediate)
- Show toast: "Your [Month] budget has been created"
- Land on budget view for current month
**Confidence:** MEDIUM — pattern validated by YNAB (beginner template import), EveryDollar (wizard-style), and UX onboarding research. 3-step max is validated by drop-off research (complexity above 3 steps correlates with abandonment).
---
## Inline Add-From-Library Design Notes
The existing Quick Add page uses a library of one-off items (`quick_add_items` table). In v2.0, this interaction moves inline to the budget view.
**Recommended pattern (based on fintech UX research):**
- Trigger: "Add item" button in each category section header on the budget view
- Mechanism: A slide-in panel or modal sheet (not a full page navigation)
- Contents: Category pre-selected (from which section was clicked); searchable list of library items for that category type; amount field; description field
- On confirm: Item added to budget for the month, totals update immediately
- On dismiss: Panel closes, no navigation
**Why panel/sheet over modal:**
- Modals block background context; users lose their place in the budget
- A slide-in sheet (shadcn/ui Sheet component) keeps the budget visible alongside the picker
- Smashing Magazine (2026): "modals work for quick confirmations; sheets work for contextual data entry tasks"
**Why not keep the separate Quick Add page:**
- Two surfaces for the same action creates confusion (which should I use?)
- The separate page breaks the flow — user must navigate away, losing their place
- Inline keeps the budget view as the single place for monthly budget work
---
## Sources
- [Fintech design guide with patterns that build trust — Eleken (2026)](https://www.eleken.co/blog-posts/modern-fintech-design-guide)
- [Finance Dashboard Design Best Practices — F9 Finance](https://www.f9finance.com/dashboard-design-best-practices/)
- [Budget vs Actual Dashboard — Bold BI](https://www.boldbi.com/dashboard-examples/finance/budget-vs-actual-dashboard/)
- [7 Essential Financial Charts for Personal Finance Visualization — Syncfusion](https://www.syncfusion.com/blogs/post/financial-charts-visualization)
- [Fintech dashboard design — Merge Rocks](https://merge.rocks/blog/fintech-dashboard-design-or-how-to-make-data-look-pretty)
- [Dashboard Design UX Patterns Best Practices — Pencil & Paper](https://www.pencilandpaper.io/articles/ux-pattern-analysis-data-dashboards)
- [shadcn/ui Charts — Donut with center text, Bar charts](https://ui.shadcn.com/charts)
- [Bar Charts Best Practices — Nastengraph / Medium](https://nastengraph.medium.com/bar-charts-best-practices-5e81ebc7b340)
- [Best Color Palettes for Financial Dashboards — Phoenix Strategy Group](https://www.phoenixstrategy.group/blog/best-color-palettes-for-financial-dashboards)
- [The Role of Color Theory in Finance Dashboard Design — Extej / Medium](https://medium.com/@extej/the-role-of-color-theory-in-finance-dashboard-design-d2942aec9fff)
- [Skeleton loading screen design — LogRocket](https://blog.logrocket.com/ux-design/skeleton-loading-screen-design/)
- [Empty state UX examples — Eleken](https://www.eleken.co/blog-posts/empty-state-ux)
- [YNAB / Mint / Empower comparison — The State of Personal Finance Apps 2025](https://bountisphere.com/blog/personal-finance-apps-2025-review)
- [Recharts documentation — recharts.org](https://recharts.github.io/en-US/api/Bar/)
- [YNAB Beginner Template and category setup](https://www.ynab.com/templates)
- [YNAB new flexible checklist for mobile (Oct 2025)](https://www.ynab.com/whats-new)
- [YNAB vs Copilot AI comparison 2025 — ZenFinanceAI](https://zenfinanceai.com/ynab-vs-copilot-ai/)
- [Monarch Money budget creation documentation](https://help.monarch.com/hc/en-us/articles/360048883631-Creating-Your-Budget-in-Monarch)
- [Monarch vs EveryDollar comparison — BudgetCoachUSA](https://budgetcoachusa.com/monarch-vs-everydollar/)
- [Top Personal Finance Apps with Customizable Budget Categories 2026 — Quicken](https://www.quicken.com/blog/top-personal-finance-apps-with-customizable-budget-categories/)
- [Best Budget Apps 2026 — NerdWallet](https://www.nerdwallet.com/finance/learn/best-budget-apps)
- [Best Budget Apps 2026 — Engadget](https://www.engadget.com/apps/best-budgeting-apps-120036303.html)
- [How Great Budget App Design Increases User Retention — Onething Design](https://www.onething.design/post/budget-app-design)
- [UX Onboarding Best Practices 2025 — UX Design Institute](https://www.uxdesigninstitute.com/blog/ux-onboarding-best-practices-guide/)
- [Budget App Design Tips from Fintech Experts — Eleken](https://www.eleken.co/blog-posts/budget-app-design)
- [Modal vs. Separate Page: UX Decision Tree — Smashing Magazine](https://www.smashingmagazine.com/2026/03/modal-separate-page-ux-decision-tree/)
- [Actual Budget — self-hosted open source](https://actualbudget.org/)
- [App Onboarding Guide 2026 — UXCam](https://uxcam.com/blog/10-apps-with-great-user-onboarding/)
- [Fintech App Top 20 Financial UX Dos and Don'ts — UXDA](https://theuxda.com/blog/top-20-financial-ux-dos-and-donts-to-boost-customer-experience)
---
*Feature research for: SimpleFinanceDash UI overhaul — presentation layer*
*Researched: 2026-03-16*
*Feature research for: SimpleFinanceDash v2.0 — wizard setup, auto-budget creation, simplified monthly tracking UX*
*Researched: 2026-04-02*