SimpleFinanceDash/.planning/phases/04-full-app-design-consistency/04-03-PLAN.md at 24d071c1f358370f8b7e47cf477a7d19e20df1ac

makiolaj/SimpleFinanceDash

Fork 0

Files

Jean-Luc Makiola fbe01b7372 docs(04): create phase plan — 3 plans for full-app design consistency

2026-03-17 16:04:04 +01:00

18 KiB

Raw Blame History

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase

plan

type

wave

depends_on

files_modified

autonomous

requirements

must_haves

04-full-app-design-consistency

execute

04-02

src/pages/BudgetListPage.tsx

src/pages/BudgetDetailPage.tsx

src/i18n/en.json

src/i18n/de.json

true

UI-BUDGETS-01

UI-RESPONSIVE-01

UI-DESIGN-01

truths

artifacts

key_links

BudgetList page uses PageShell for header with title and New Budget button

BudgetList page shows locale-aware month names (German month names when locale is de)

BudgetList page shows skeleton loading state instead of blank screen

BudgetList dialog month/year labels are translated (not hardcoded English)

BudgetDetail page uses PageShell with locale-aware month heading

BudgetDetail page shows left-border accent group headers matching dashboard style

BudgetDetail page uses semantic color tokens (text-over-budget/text-on-budget) instead of text-green-600/text-red-600

BudgetDetail page uses direction-aware diff logic (spending over when actual > budgeted; income/saving/investment over when actual < budgeted)

BudgetDetail page shows skeleton loading state instead of blank screen

No hardcoded 'en' locale string remains in any budget page

Navigating between all pages produces no jarring visual discontinuity

path	provides	contains
src/pages/BudgetListPage.tsx	PageShell adoption, locale-aware months, skeleton, i18n labels	PageShell

path	provides	contains
src/pages/BudgetDetailPage.tsx	PageShell, semantic tokens, direction-aware diff, group headers, skeleton	text-over-budget

path	provides	contains
src/i18n/en.json	Budget month/year dialog labels and group total i18n key	budgets.month

path	provides	contains
src/i18n/de.json	German budget translations	budgets.month

from	to	via	pattern
src/pages/BudgetDetailPage.tsx	semantic CSS tokens	text-over-budget / text-on-budget classes	text-over-budget\|text-on-budget

from	to	via	pattern
src/pages/BudgetListPage.tsx	i18n.language	Intl.DateTimeFormat locale parameter	Intl.DateTimeFormat

from	to	via	pattern
src/pages/BudgetDetailPage.tsx	i18n.language	Intl.DateTimeFormat locale parameter	Intl.DateTimeFormat

Upgrade BudgetListPage and BudgetDetailPage with PageShell, semantic color tokens, direction-aware diff logic, locale-aware month formatting, and skeleton loading states.

Purpose: These are the most complex pages in the app. BudgetDetailPage currently uses hardcoded text-green-600/text-red-600 color classes that bypass the design token system, a simplified isIncome boolean that mishandles saving/investment types, and a hardcoded "en" locale for month formatting. BudgetListPage has a hardcoded English MONTHS array. This plan migrates both to the established design system patterns from Phases 1-3.

Output: Two fully upgraded budget pages with consistent visual language, correct semantic tokens, and locale-aware formatting.

<execution_context> @/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md @/home/jlmak/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/04-full-app-design-consistency/04-CONTEXT.md @.planning/phases/04-full-app-design-consistency/04-RESEARCH.md From src/components/shared/PageShell.tsx: ```tsx interface PageShellProps { title: string description?: string action?: React.ReactNode children: React.ReactNode } export function PageShell({ title, description, action, children }: PageShellProps) ```

From src/components/dashboard/CategorySection.tsx (direction-aware diff logic to replicate):

const SPENDING_TYPES: CategoryType[] = ["bill", "variable_expense", "debt"]

function isSpendingType(type: CategoryType): boolean {
  return SPENDING_TYPES.includes(type)
}

function computeDiff(budgeted: number, actual: number, type: CategoryType): { diff: number; isOver: boolean } {
  if (isSpendingType(type)) {
    return { diff: budgeted - actual, isOver: actual > budgeted }
  }
  return { diff: actual - budgeted, isOver: actual < budgeted }
}

Semantic color classes (from index.css Phase 1):

text-over-budget -- red, for amounts exceeding budget
text-on-budget -- green, for amounts within budget
text-muted-foreground -- neutral, for zero difference

Group header pattern (established in Plan 02):

<div
  className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
  style={{ borderLeftColor: categoryColors[type] }}
>
  <span className="text-sm font-semibold">{t(`categories.types.${type}`)}</span>
</div>

Locale-aware month formatting pattern:

const { i18n } = useTranslation()
const locale = i18n.language
// Replace hardcoded MONTHS array:
const monthItems = useMemo(
  () => Array.from({ length: 12 }, (_, i) => ({
    value: i + 1,
    label: new Intl.DateTimeFormat(locale, { month: "long" }).format(new Date(2000, i, 1)),
  })),
  [locale]
)
// Replace hardcoded "en" in toLocaleDateString:
function budgetHeading(startDate: string, locale: string): string {
  const [year, month] = startDate.split("-").map(Number)
  return new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }).format(
    new Date(year ?? 0, (month ?? 1) - 1, 1)
  )
}

Task 1: Upgrade BudgetListPage with PageShell, locale-aware months, skeleton, and i18n labels src/pages/BudgetListPage.tsx, src/i18n/en.json, src/i18n/de.json **BudgetListPage.tsx changes:**

Import PageShell, Skeleton, useMemo: Add:

import { useState, useMemo } from "react"
import { PageShell } from "@/components/shared/PageShell"
import { Skeleton } from "@/components/ui/skeleton"

Remove hardcoded MONTHS array: Delete the entire const MONTHS = [...] constant (lines 36-49).
Add locale-aware month generation: Inside the component, after the existing hooks and state, add:
```
const { t, i18n } = useTranslation()
const locale = i18n.language

const monthItems = useMemo(
  () =>
    Array.from({ length: 12 }, (_, i) => ({
      value: i + 1,
      label: new Intl.DateTimeFormat(locale, { month: "long" }).format(
        new Date(2000, i, 1)
      ),
    })),
  [locale]
)
```
Update the existing useTranslation() call to also destructure i18n: change const { t } = useTranslation() to const { t, i18n } = useTranslation().

Rules of Hooks: The useMemo must be declared BEFORE the if (loading) check. Since useTranslation is already before it, just place useMemo right after the state declarations and before if (loading).

Fix budgetLabel to use locale: Replace the budgetLabel helper function to use locale:

function budgetLabel(budget: Budget, locale: string): string {
  const [year, month] = budget.start_date.split("-").map(Number)
  return new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }).format(
    new Date(year ?? 0, (month ?? 1) - 1, 1)
  )
}

Update all call sites to pass locale: budgetLabel(budget, locale) and budgetLabel(result, locale).

Replace MONTHS usage in dialog: In the month Select, replace MONTHS.map((m) => with monthItems.map((m) =>. The shape is identical ({ value, label }).
Replace hardcoded "Month" and "Year" labels: Replace the <Label>Month</Label> and <Label>Year</Label> in the new budget dialog with:
```
<Label>{t("budgets.month")}</Label>
// and
<Label>{t("budgets.year")}</Label>
```

Replace header with PageShell: Remove the <div className="mb-6 flex items-center justify-between"> header block. Wrap the return in:

<PageShell
  title={t("budgets.title")}
  action={
    <Button onClick={openDialog} size="sm">
      <Plus className="mr-1 size-4" />
      {t("budgets.newBudget")}
    </Button>
  }
>
  {/* empty state + table + dialog */}
</PageShell>

Skeleton loading: Replace if (loading) return null with:

if (loading) return (
  <PageShell title={t("budgets.title")}>
    <div className="space-y-1">
      {[1, 2, 3, 4].map((i) => (
        <div key={i} className="flex items-center gap-4 px-4 py-3 border-b border-border">
          <Skeleton className="h-4 w-40" />
          <Skeleton className="h-4 w-12" />
          <Skeleton className="ml-auto h-4 w-4" />
        </div>
      ))}
    </div>
  </PageShell>
)

i18n additions (en.json): Add inside the "budgets" object:

"month": "Month",
"year": "Year",
"total": "{{label}} Total"

i18n additions (de.json): Add inside the "budgets" object:

"month": "Monat",
"year": "Jahr",
"total": "{{label}} Gesamt"

cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build BudgetListPage uses PageShell, shows locale-aware month names via Intl.DateTimeFormat (no hardcoded English MONTHS array), dialog labels use i18n keys, skeleton replaces null loading state, budgetLabel uses i18n.language locale. Both en.json and de.json have month/year/total keys. Build passes. Task 2: Upgrade BudgetDetailPage with semantic tokens, direction-aware diff, PageShell, group headers, and skeleton src/pages/BudgetDetailPage.tsx **BudgetDetailPage.tsx changes:**

Import additions: Add:

import { cn } from "@/lib/utils"
import { PageShell } from "@/components/shared/PageShell"
import { Skeleton } from "@/components/ui/skeleton"

Add direction-aware diff logic: At module level (above the component), add the same SPENDING_TYPES pattern from CategorySection:

const SPENDING_TYPES: CategoryType[] = ["bill", "variable_expense", "debt"]

function isSpendingType(type: CategoryType): boolean {
  return SPENDING_TYPES.includes(type)
}

Rewrite DifferenceCell: Replace the entire DifferenceCell component. Change its props: remove isIncome, add type: CategoryType:

function DifferenceCell({
  budgeted,
  actual,
  currency,
  type,
}: {
  budgeted: number
  actual: number
  currency: string
  type: CategoryType
}) {
  const isOver = isSpendingType(type)
    ? actual > budgeted
    : actual < budgeted
  const diff = isSpendingType(type)
    ? budgeted - actual
    : actual - budgeted

  return (
    <TableCell
      className={cn(
        "text-right tabular-nums",
        isOver ? "text-over-budget" : diff !== 0 ? "text-on-budget" : "text-muted-foreground"
      )}
    >
      {formatCurrency(Math.abs(diff), currency)}
      {diff < 0 ? " over" : ""}
    </TableCell>
  )
}

Update DifferenceCell call sites: In the grouped.map render:
- Remove the const isIncome = type === "income" line.
- Change <DifferenceCell budgeted={...} actual={...} currency={currency} isIncome={isIncome} /> to <DifferenceCell budgeted={...} actual={...} currency={currency} type={type} /> in BOTH places (per-item row and group footer).
Remove TierBadge from BudgetDetailPage: Per research recommendation, remove the tier column from BudgetDetailPage to reduce visual noise and align with CategorySection display. This is Claude's discretion per CONTEXT.md.
- Remove the TierBadge component definition from BudgetDetailPage (keep it in TemplatePage where it belongs).
- Remove the <TableHead>{t("categories.type")}</TableHead> column from the table header.
- Remove the <TableCell><TierBadge tier={item.item_tier} /></TableCell> from each table row.
- Update the TableFooter colSpan accordingly: the first footer cell changes from colSpan={2} to no colSpan (or colSpan={1}), and the last footer cell changes appropriately.
- Remove the Badge import if no longer used elsewhere in this file.

Group header upgrade: Replace the dot+h2 pattern in grouped.map with:

<div
  className="mb-2 flex items-center gap-3 rounded-sm border-l-4 bg-muted/30 px-3 py-2"
  style={{ borderLeftColor: categoryColors[type] }}
>
  <span className="text-sm font-semibold">{t(`categories.types.${type}`)}</span>
</div>

Fix locale for headingLabel: Update the headingLabel function. Destructure i18n from useTranslation: change const { t } = useTranslation() to const { t, i18n } = useTranslation(). Then:

function headingLabel(): string {
  if (!budget) return ""
  const [year, month] = budget.start_date.split("-").map(Number)
  return new Intl.DateTimeFormat(i18n.language, { month: "long", year: "numeric" }).format(
    new Date(year ?? 0, (month ?? 1) - 1, 1)
  )
}

Fix overall totals section: The overall totals box at the bottom uses hardcoded text-green-600/text-red-600. Replace with semantic tokens:
```
<p
  className={cn(
    "text-lg font-semibold tabular-nums",
    totalBudgeted - totalActual >= 0 ? "text-on-budget" : "text-over-budget"
  )}
>
```
This replaces the inline ternary with text-green-600 dark:text-green-400 / text-red-600 dark:text-red-400.

Fix group footer "Total" label: The group footer currently has hardcoded English Total:

<TableCell colSpan={2} className="font-medium">
  {t(`categories.types.${type}`)} Total
</TableCell>

Replace with i18n:

<TableCell className="font-medium">
  {t("budgets.total", { label: t(`categories.types.${type}`) })}
</TableCell>

The budgets.total key was added in Task 1's i18n step: "total": "{{label}} Total" / "total": "{{label}} Gesamt".

Replace header with PageShell: Replace the back link + header section. Keep the back link as a child of PageShell:

<PageShell
  title={headingLabel()}
  action={
    <Button onClick={openAddDialog} size="sm">
      <Plus className="mr-1 size-4" />
      {t("budgets.addItem")}
    </Button>
  }
>
  <Link
    to="/budgets"
    className="-mt-4 inline-flex items-center gap-1 text-sm text-muted-foreground hover:text-foreground"
  >
    <ArrowLeft className="size-4" />
    {t("budgets.title")}
  </Link>
  {/* rest of content */}
</PageShell>

The -mt-4 on the back link compensates for PageShell's gap-6, pulling it closer to the header.

Skeleton loading: Replace if (loading) return null with:

if (loading) return (
  <PageShell title="">
    <div className="space-y-6">
      <Skeleton className="h-4 w-24" />
      {[1, 2, 3].map((i) => (
        <div key={i} className="space-y-2">
          <div className="flex items-center gap-3 rounded-sm border-l-4 border-muted bg-muted/30 px-3 py-2">
            <Skeleton className="h-4 w-28" />
          </div>
          {[1, 2].map((j) => (
            <div key={j} className="flex items-center gap-4 px-4 py-2.5 border-b border-border">
              <Skeleton className="h-4 w-32" />
              <Skeleton className="ml-auto h-4 w-20" />
              <Skeleton className="h-4 w-20" />
              <Skeleton className="h-4 w-16" />
            </div>
          ))}
        </div>
      ))}
      <Skeleton className="h-20 w-full rounded-md" />
    </div>
  </PageShell>
)

IMPORTANT VERIFICATION after changes: Ensure NO instances of text-green-600, text-red-600, text-green-400, or text-red-400 remain in BudgetDetailPage.tsx. All color coding must use text-over-budget, text-on-budget, or text-muted-foreground. cd /home/jlmak/Projects/jlmak/SimpleFinanceDash && bun run build && grep -c "text-green-600|text-red-600|text-green-400|text-red-400" src/pages/BudgetDetailPage.tsx || echo "CLEAN: no hardcoded color classes" BudgetDetailPage uses semantic color tokens (text-over-budget/text-on-budget) with zero instances of text-green-600 or text-red-600. Direction-aware diff logic handles all 6 category types correctly (spending types over when actual > budgeted, income/saving/investment over when actual < budgeted). Left-border accent group headers replace dot headers. Tier badge column removed for cleaner display. Locale-aware month heading. Skeleton loading state. PageShell wraps the page. Overall totals box uses semantic tokens. Group footer total label uses i18n interpolation. Build passes.

- `bun run build` compiles without TypeScript errors - `bun run lint` passes (or pre-existing errors only) - `grep -c "text-green-600\|text-red-600" src/pages/BudgetDetailPage.tsx` returns 0 (semantic tokens only) - `grep -c "text-over-budget\|text-on-budget" src/pages/BudgetDetailPage.tsx` returns at least 2 - `grep -c "return null" src/pages/BudgetListPage.tsx src/pages/BudgetDetailPage.tsx` returns 0 for both - `grep -c 'toLocaleDateString("en"' src/pages/BudgetDetailPage.tsx src/pages/BudgetListPage.tsx` returns 0 (no hardcoded English locale) - `grep -c "Intl.DateTimeFormat" src/pages/BudgetListPage.tsx src/pages/BudgetDetailPage.tsx` returns at least 1 for each - `grep -c "PageShell" src/pages/BudgetListPage.tsx src/pages/BudgetDetailPage.tsx` returns at least 1 for each - `grep "budgets.month" src/i18n/en.json src/i18n/de.json` returns matches in both

<success_criteria>

BudgetListPage: PageShell header, locale-aware month names in dialog and table, skeleton loading, i18n month/year labels
BudgetDetailPage: PageShell header, semantic color tokens (no hardcoded green/red), direction-aware diff for all 6 category types, left-border accent group headers, no tier column, locale-aware heading, skeleton loading, i18n group total label
No hardcoded English locale strings ("en") remain in budget page formatting
No hardcoded Tailwind color classes (text-green-600, text-red-600) remain
All 9 app pages now use consistent header layout (PageShell or equivalent)
German locale shows fully translated text on both pages
bun run build passes </success_criteria>

After completion, create `.planning/phases/04-full-app-design-consistency/04-03-SUMMARY.md`

18 KiB Raw Blame History

18 KiB

Raw Blame History