From c47df80b81f40e1cc6c2d5a676ae1e548362691c Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Thu, 12 Mar 2026 10:03:34 +0100 Subject: [PATCH] docs: start milestone v1.1 Usability and Templates Co-Authored-By: Claude Opus 4.6 --- .planning/PROJECT.md | 91 +++++++++++++++++++++++++++----------------- .planning/STATE.md | 30 +++++++-------- 2 files changed, 71 insertions(+), 50 deletions(-) diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 9478b39..e9f391a 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -8,70 +8,91 @@ A self-hosted personal budget dashboard that replaces a manual spreadsheet workf Opening the app should feel like opening a beautifully designed personal spreadsheet — clean pastel colors, clear data layout, approachable and visually delightful. The UI IS the product. +## Current Milestone: v1.1 Usability and Templates + +**Goal:** Make the app actually usable for monthly budgeting — replace the manual copy workflow with a smart template system (fixed/variable/one-off items), add a quick-add library for recurring one-offs, and rethink the dashboard layout for dense, spreadsheet-like data presentation on desktop. + +**Target features:** +- Budget template system with three item tiers (fixed, variable, one-off) +- Auto-generate new month budgets from template on navigate +- Quick-add library for saved one-off expense categories with icons +- Dashboard layout rethink — flatter, denser, less card chrome, more spreadsheet feel +- Desktop-optimized data density + ## Requirements ### Validated - + -- ✓ Local auth (email/password registration, login, logout, JWT sessions) — existing -- ✓ Budget CRUD (create, edit, delete monthly budgets) — existing -- ✓ Budget item management (create, update, delete items per budget) — existing -- ✓ Category CRUD (bill, variable_expense, debt, saving, investment, income types) — existing -- ✓ Copy budget from previous month — existing -- ✓ Server-side budget totals computation — existing -- ✓ REST API with auth middleware — existing -- ✓ i18n support (German + English, user preference stored) — existing -- ✓ Docker deployment (single binary, multi-stage build, compose) — existing -- ✓ Dashboard with financial overview, bills tracker, variable expenses, expense breakdown, debt tracker — existing (rough) +- ✓ Local auth (email/password registration, login, logout, JWT sessions) — v1.0 +- ✓ Budget CRUD (create, edit, delete monthly budgets) — v1.0 +- ✓ Budget item management (create, update, delete items per budget) — v1.0 +- ✓ Category CRUD (bill, variable_expense, debt, saving, investment, income types) — v1.0 +- ✓ Copy budget from previous month — v1.0 (being replaced by templates in v1.1) +- ✓ Server-side budget totals computation — v1.0 +- ✓ REST API with auth middleware — v1.0 +- ✓ i18n support (German + English, user preference stored) — v1.0 +- ✓ Docker deployment (single binary, multi-stage build, compose) — v1.0 +- ✓ Dashboard with financial overview, bills tracker, variable expenses, expense breakdown, debt tracker — v1.0 +- ✓ Pastel design system with oklch tokens and semantic category colors — v1.0 +- ✓ Branded auth screens, sidebar, and navigation — v1.0 +- ✓ Interaction quality: spinners, inline edit affordances, row flash, delete confirmations — v1.0 +- ✓ Empty states, loading skeletons, chart tooltips, locale-aware currency formatting — v1.0 ### Active - + -- [ ] Cohesive pastel design system across all components (not default shadcn) -- [ ] Polished login/register screens with branded look (not generic shadcn defaults) -- [ ] Dashboard layout that feels organized, spacious, and visually appealing -- [ ] Charts that look polished and informative (donut, bar, pie) -- [ ] Consistent color tokens and typography across the entire app -- [ ] Smooth interactions — inline editing, form submissions, transitions -- [ ] Category management page with polished UI -- [ ] Settings page with polished UI -- [ ] Responsive layout (desktop-first, but usable on tablet) -- [ ] Fix any backend bugs discovered during UI testing +- [ ] Budget template system — users define fixed and variable items that carry forward each month +- [ ] Fixed items auto-copied with amounts; variable items copied as category only (amount blank) +- [ ] One-off items added manually per month, not carried forward +- [ ] Auto-generate budget from template when navigating to a month with no budget +- [ ] Quick-add library — saved one-off categories with icons for reuse +- [ ] Replace "copy from previous month" with template-based generation +- [ ] Template management page — add/remove/reorder fixed and variable items +- [ ] Inline tagging of items as fixed/variable/one-off when adding +- [ ] Dashboard layout rethink — move away from heavy card containers toward flatter, integrated layout +- [ ] Increase data density — tighter rows, less padding, more visible without scrolling +- [ ] Fix card top padding above colored headers +- [ ] Desktop-optimized layout (web desktop is the primary target) ### Out of Scope -- CSV/bank import — future feature, not needed for visual polish -- Recurring/automated transactions — future feature +- CSV/bank import — future feature - Shared/household budgets — future feature -- Custom themes/color picker — architecture supports it, but not this milestone +- Custom themes/color picker — architecture supports it, not this milestone - OIDC authentication — stubs exist, implement later - PDF/CSV export — future feature -- Mobile app — web-first +- Mobile app — web desktop is the focus - GraphQL API — REST is sufficient +- Dark mode — light mode pastel system first +- Tablet/mobile responsiveness — desktop only for now ## Context -The codebase was built as an initial implementation but the frontend was not given enough design attention. The backend (Go + PostgreSQL) is functional with proper auth, CRUD operations, and data model. The frontend uses React + shadcn/ui + Tailwind + Recharts but looks like default shadcn with minimal customization. The original vision was a pastel spreadsheet aesthetic — soft blues, pinks, yellows, greens, lavenders with clean data presentation. This milestone is about bringing the UI up to that vision. - -Key reference: PRD.md section 8 (UI/Design) describes the target aesthetic — pastel colors, soft backgrounds, subtle dividers, shadcn components with custom theme tokens. +v1.0 shipped the visual identity — pastel oklch tokens, branded auth screens, sidebar, interaction quality (spinners, flash feedback, delete confirmations), empty states, chart tooltips, and locale-aware formatting. The app looks good but the UX for actually managing a monthly budget is clunky. The "copy from previous month" feature is a blunt instrument — it copies everything including one-off expenses. Users need a smarter template system that understands which expenses are fixed (rent), which recur but vary (groceries), and which are one-time (pharmacy visit). Additionally, the dashboard layout uses heavy card containers with excessive padding — it needs to lean more into the spreadsheet aesthetic with denser data presentation and less visual chrome. Desktop web is the primary and only target. ## Constraints - **Tech stack**: Keep existing Go + React + shadcn/ui + Tailwind + Recharts stack -- **Design system**: Build on shadcn/ui, don't replace it — customize via CSS variables and Tailwind config -- **Backend**: Minimize backend changes — focus is frontend polish +- **Design system**: Build on shadcn/ui, customize via CSS variables and Tailwind config +- **Backend**: Template system requires backend changes (new tables, API endpoints) - **i18n**: All new/changed UI text must have de + en translations - **Package manager**: Use bun for frontend +- **Platform**: Desktop web only — no mobile/tablet optimization ## Key Decisions | Decision | Rationale | Outcome | |----------|-----------|---------| -| Customize shadcn via CSS variables | Maintain upgrade path while achieving unique look | — Pending | -| Pastel palette as primary design language | Matches original spreadsheet inspiration | — Pending | -| Desktop-first responsive | Primary use case is desktop budget management | — Pending | +| Customize shadcn via CSS variables | Maintain upgrade path while achieving unique look | ✓ Good | +| Pastel palette as primary design language | Matches original spreadsheet inspiration | ✓ Good | +| Desktop-first responsive | Primary use case is desktop budget management | ✓ Good | +| Three-tier item model (fixed/variable/one-off) | Matches how users think about recurring vs one-time expenses | — Pending | +| Replace copy-from-previous with templates | Templates are smarter — copy was too blunt, carried one-offs forward | — Pending | +| Auto-generate budget on navigate | Removes friction — user just navigates to a month and it's ready | — Pending | +| Rethink cards as flatter containers | Current card chrome is too heavy — denser, spreadsheet-like layout | — Pending | --- -*Last updated: 2026-03-11 after initialization* +*Last updated: 2026-03-12 after v1.1 milestone start* diff --git a/.planning/STATE.md b/.planning/STATE.md index 1d00d2d..4f13b91 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -1,16 +1,16 @@ --- gsd_state_version: 1.0 -milestone: v1.0 -milestone_name: milestone +milestone: v1.1 +milestone_name: usability-and-templates status: planning -stopped_at: Completed 04-02-PLAN.md -last_updated: "2026-03-12T08:30:44.989Z" -last_activity: 2026-03-11 — Roadmap created from requirements and research +stopped_at: null +last_updated: "2026-03-12" +last_activity: 2026-03-12 — Milestone v1.1 started progress: - total_phases: 4 - completed_phases: 4 - total_plans: 10 - completed_plans: 10 + total_phases: 0 + completed_phases: 0 + total_plans: 0 + completed_plans: 0 percent: 0 --- @@ -18,17 +18,17 @@ progress: ## Project Reference -See: .planning/PROJECT.md (updated 2026-03-11) +See: .planning/PROJECT.md (updated 2026-03-12) **Core value:** Opening the app should feel like opening a beautifully designed personal spreadsheet — clean pastel colors, clear data layout, approachable and visually delightful. The UI IS the product. -**Current focus:** Phase 1 — Design Token Foundation +**Current focus:** Defining requirements for v1.1 ## Current Position -Phase: 1 of 4 (Design Token Foundation) -Plan: 0 of TBD in current phase -Status: Ready to plan -Last activity: 2026-03-11 — Roadmap created from requirements and research +Phase: Not started (defining requirements) +Plan: — +Status: Defining requirements +Last activity: 2026-03-12 — Milestone v1.1 started Progress: [░░░░░░░░░░] 0%