From 6a4a55cb9c88cf394fd5f246da75838e2e4c6294 Mon Sep 17 00:00:00 2001
From: lorentz <lorentz@wulfconsulting.com>
Date: Sun, 3 May 2026 19:41:38 -0400
Subject: [PATCH] docs(05): UI design contract

---
 .../phases/05-finance-restyle/05-UI-SPEC.md     | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/.planning/phases/05-finance-restyle/05-UI-SPEC.md b/.planning/phases/05-finance-restyle/05-UI-SPEC.md
index 85db1cc..4b386a6 100644
--- a/.planning/phases/05-finance-restyle/05-UI-SPEC.md
+++ b/.planning/phases/05-finance-restyle/05-UI-SPEC.md
@@ -48,7 +48,7 @@ Declared values (multiples of 4). Mirrors Phase 4 UI-SPEC exactly [D-10, D-11].
 
 | Token | Value | Usage in this phase |
 |-------|-------|---------------------|
-| xs | 4px | Icon gaps (`gap-1`), badge padding (`px-1.5 py-0.5`) |
+| xs | 4px | Icon gaps (`gap-1`), badge padding (`px-2 py-1`) |
 | sm | 8px | Row internal gaps (`gap-2`), section-header gap (`gap-2`) |
 | sm+ | 12px (3 × 4) | Between rows in a list (`space-y-3`), card internal gap (`gap-3`) [D-11] |
 | md | 16px | Horizontal page padding (`px-4`), vertical page padding (`py-4`) [D-10] |
@@ -56,7 +56,7 @@ Declared values (multiples of 4). Mirrors Phase 4 UI-SPEC exactly [D-10, D-11].
 | xl | 32px | Empty/error-state vertical padding (`py-8`) |
 | 2xl | 48px | Large empty-state full-screen centering (`py-12`) |
 
-Touch-target exception: Refresh and Sync QBO icon buttons must reach a minimum 44 × 44 px tap target — use `p-2.5` or `min-h-[44px]` [D-14].
+Touch-target exception: Refresh and Sync QBO icon buttons must reach a minimum 44 × 44 px tap target — use `p-3` or `min-h-[44px]` [D-14].
 
 Exceptions: None beyond the 44 px touch target rule.
 
@@ -68,7 +68,7 @@ Two weights only: `font-normal` (400) and `font-semibold` (600). `font-medium` (
 
 | Role | Size class | Weight | Line Height | Font | Usage |
 |------|-----------|--------|-------------|------|-------|
-| KPI dollar value | `text-xl` / `text-2xl` (4 summary tiles only) | `font-semibold` (600) | `leading-tight` (1.25) | IBM Plex Sans | Total AR / Current / Overdue / Paid MTD tile values [D-02, D-04] |
+| KPI dollar value | `text-2xl` (24px) (4 summary tiles only) | `font-semibold` (600) | `leading-tight` (1.25) | IBM Plex Sans | Total AR / Current / Overdue / Paid MTD tile values [D-02, D-04] |
 | Row primary line | `text-sm` (14px) | `font-semibold` (600) | `leading-snug` (1.375) | IBM Plex Sans | Customer name (left) + amount (right) in invoice/payment/customer rows [D-06, D-07] |
 | Row secondary / metadata | `text-xs` (12px) | `font-normal` (400) | `leading-normal` (1.5) | IBM Plex Sans | Invoice #, doc number, date, status chip, "Xd overdue" label [D-06] |
 | KPI tile label | `text-xs` (12px) | `font-semibold` (600) | `leading-none` | IBM Plex Sans | "TOTAL AR", "CURRENT", etc. — uppercase tracking-wider [D-02] |
@@ -190,7 +190,7 @@ Same 2-line row structure as invoice rows but without the right-side date:
 
 Each row:
 ```
-[px-4 py-2.5 flex items-center justify-between]
+[px-4 py-3 flex items-center justify-between]
   [left: month label — text-sm font-semibold]
   [right: revenue — text-sm font-semibold + count — text-xs text-muted-foreground]
 ```
@@ -203,9 +203,9 @@ Visible only when `monthly_revenue.length > 0`.
 
 Use shadcn `Collapsible` + `CollapsibleTrigger` + `CollapsibleContent`. Replace existing bare `<button onClick>` pattern.
 
-Trigger bar: `w-full flex items-center justify-between px-4 py-3.5 hover:bg-muted/50 transition-colors`
+Trigger bar: `w-full flex items-center justify-between px-4 py-4 hover:bg-muted/50 transition-colors`
 
-Left slot: icon (`h-4 w-4 text-muted-foreground`) + section label (`text-sm font-semibold`) + count badge (`text-xs bg-muted rounded-full px-2 py-0.5 font-mono`)
+Left slot: icon (`h-4 w-4 text-muted-foreground`) + section label (`text-sm font-semibold`) + count badge (`text-xs bg-muted rounded-full px-2 py-1 font-mono`)
 
 Right slot: `ChevronDown` (open) / `ChevronRight` (closed), `h-4 w-4 text-muted-foreground`
 
@@ -224,10 +224,10 @@ Labels: `"Overdue ({N})"` / `"Current ({N})"`
 
 Replace existing control row with icon-button + labeled action pattern:
 
-**Refresh button:** `<button aria-label="Refresh finance data">` — `p-2.5 rounded-full hover:bg-muted/50 transition-colors disabled:opacity-40`
+**Refresh button:** `<button aria-label="Refresh finance data">` — `p-3 rounded-full hover:bg-muted/50 transition-colors disabled:opacity-40`
 - Icon: `RefreshCw h-4 w-4` (adds `animate-spin` class when `loading`)
 
-**Sync QBO button:** `<button aria-label="Sync from QuickBooks">` — `flex items-center gap-1.5 px-3 py-2 rounded-xl bg-primary text-primary-foreground text-xs font-semibold disabled:opacity-50 hover:bg-primary/90 transition-colors`
+**Sync QBO button:** `<button aria-label="Sync from QuickBooks">` — `flex items-center gap-2 px-3 py-2 rounded-xl bg-primary text-primary-foreground text-xs font-semibold disabled:opacity-50 hover:bg-primary/90 transition-colors`
 - Icon: `CloudDownload h-3.5 w-3.5` (adds `animate-pulse` when `syncing`)
 - Label: `"Sync QBO"` (idle) / `"Syncing…"` (in-flight)
 
@@ -419,6 +419,7 @@ Per D-20 through D-23 and phase boundary:
 
 *Phase: 05-finance-restyle*
 *UI-SPEC created: 2026-05-03*
+*UI-SPEC revised: 2026-05-03 (checker blocking fixes — typography 5→4 sizes, spacing non-multiples-of-4, iteration 2 — badge px-1.5/py-0.5 → px-2/py-1, gap-1.5 → gap-2)*
 *Source decisions: 05-CONTEXT.md D-01 through D-23 (all locked)*
 *Typography/spacing mirrors: 04-UI-SPEC.md (Phase 4 Tickets Restyle)*
 *KPI tile pattern mirrors: 03-01-SUMMARY.md (KpiCardMobile, Phase 3)*