zeroclock/docs/plans/2026-02-18-invoice-templates-v2-design.md

# Invoice Templates v2 — Complete Redesign

## Goal

Replace the current invoice template system with genuinely beautiful, typographically correct templates and a two-step UX flow where the user creates the invoice first, then picks a template on a dedicated full-screen page.

## Two Problems Being Solved

1. **UX flow**: Template picker is crammed into the create form. Should be a separate step after invoice data is entered.
2. **Template quality**: All 15 templates look the same — just color swaps of identical layout with tiny unreadable text, spreadsheet-like tables, and no visual hierarchy.

---

## Part 1: UX Flow

### Current Flow (broken)
Single "Create" tab with invoice fields, line items, AND template picker + preview all on one page.

### New Flow — Two Steps

**Step 1: Invoice Form** (the existing "Create" tab, minus template picker)
- Invoice number, client, dates, line items, notes, tax, discount, totals
- "Create Invoice" button saves to DB, then navigates to Step 2

**Step 2: Template Picker** (new full-screen view)
- Route: Invoices view with `view = 'template-picker'` state, receives `invoiceId`
- Also accessible from invoice list (clicking "View" on any existing invoice)
- Layout: narrow sidebar (template list by category with color dots) + large preview area
- Bottom bar: "Export PDF" button + "Save & Close" button
- Template choice saved to invoice via `template_id` column in DB
- Pre-selects previously chosen template when viewing existing invoices

### Data Flow
1. User fills form → "Create Invoice" → invoice + items saved → navigate to template picker with invoiceId
2. Template picker loads invoice + items from DB, renders live preview
3. User browses templates, optionally exports PDF
4. "Save & Close" → saves template_id to invoice → back to list

### Database Change
Add `template_id TEXT DEFAULT 'clean'` column to `invoices` table.
Add `update_invoice_template` Tauri command.

---

## Part 2: Template Design System

### Design Principles (from research)

1. **Total Due is the most prominent number** — 16-20pt bold, highlighted
2. **Maximum 2 font weights** per template; hierarchy through size contrast
3. **Borderless tables** preferred — subtle horizontal rules, not spreadsheet grids
4. **70-20-10 color rule** — 70% white/neutral, 20% primary, 10% secondary
5. **Body text minimum 10pt in PDF** (8pt absolute floor for fine print)
6. **Right-align monetary values**, left-align descriptions
7. **Generous whitespace** between sections (8-12mm in PDF)
8. **ALL CAPS only for short labels** with +0.05em letter-spacing
9. **Line height**: 1.5 for body text, 1.2-1.3 for headers
10. **Tabular numerals** in number columns for perfect alignment

### Typography Scale (PDF, in points)

| Element | Size | Weight | Notes |
|---|---|---|---|
| "INVOICE" title | 24-32pt | Bold | Most visually prominent text |
| Company name | 14-18pt | Semi-bold | Or use logo image |
| Section headers | 11-12pt | Semi-bold | Uppercase + tracked |
| Body text / descriptions | 10-11pt | Regular | Core readability |
| Column headers | 9-10pt | Medium | Uppercase + tracked |
| Total amount | 16-20pt | Bold | Star of the page |
| Due date | 12-14pt | Semi-bold | Second most prominent |
| Footer / notes | 8-9pt | Regular | Minimum legible |

### HTML Preview Typography (scaled for ~300px wide preview)

| Element | Size | Notes |
|---|---|---|
| "INVOICE" title | 18-24px | Bold |
| Company name | 11-14px | Semi-bold |
| Section headers | 8-9px | Uppercase, tracked |
| Body text | 7.5-8px | Regular |
| Column headers | 7-7.5px | Medium, uppercase |
| Total amount | 12-16px | Bold |
| Fine print | 6.5-7px | Regular |

### Information Architecture (top-to-bottom)

```
1. HEADER ZONE — Logo + branding + "INVOICE" title + invoice #/date/due date
2. PARTIES ZONE — From (business) left | Bill To (client) right
3. LINE ITEMS — Table: Description | Qty | Rate | Amount
4. TOTALS — Subtotal, Tax, Discount, TOTAL DUE (prominent)
5. FOOTER — Notes, payment terms, thank you
```

### Whitespace (PDF, in mm)

| Area | Value |
|---|---|
| Page margins | 20mm all sides |
| Between major sections | 8-12mm |
| Table cell padding | 3mm vertical, 4mm horizontal |
| Between label and value | 2mm |
| Logo max height | 16mm |

### Table Design Rules

- **Preferred**: Borderless with thin horizontal rules (0.3pt, light gray)
- **No vertical borders** in any template
- Column headers distinguished by weight + bottom border (1pt)
- Zebra striping: alternate between white and barely-gray (#f8fafc)
- Right-align Qty, Rate, Amount columns
- Generous row height (8-10mm)

---

## The 15 Templates

### Tier 1: Professional Essentials

**1. Clean**
- Header: Logo top-left, biz name below, "INVOICE" in slate with thin accent line (30% width)
- From/To in two columns below
- Table: Borderless, thin gray bottom borders per row, light gray header bg
- Totals: Right-aligned, total in bold slate
- Color: Monochrome slate (#1e293b) with blue accent (#3b82f6) only on the total
- Vibe: Stripe invoices. Swiss minimalism. Maximum breathing room.

**2. Professional**
- Header: Full-width navy (#1e3a5f) band across top ~50mm. White "INVOICE" large. Biz name white right side. Invoice meta in white below title.
- Below band: From/To section
- Table: Navy header row, light gray zebra stripes, no borders
- Totals: Right-aligned, navy total
- Vibe: QuickBooks polished. Corporate trust.

**3. Bold**
- Header: Large indigo (#4f46e5) rectangle top-left ~55% width × 50mm. "INVOICE" massive white inside. Invoice # white below title. Biz info outside block to the right in dark text.
- Below: "FROM" and "TO" labels (uppercase, tracked) with info in two columns
- Table: Indigo header row, no borders at all, generous 10mm row height
- Totals: Large indigo total (18pt), prominent
- Vibe: Design agency. Confident and modern.

**4. Minimal**
- Header: Everything centered. Logo centered. Thin rule. "INVOICE" centered in charcoal. Biz name centered. Thin rule.
- Below rules: From/To in two columns
- Table: No backgrounds anywhere. Whitespace-only row separation (generous padding). Header distinguished only by bold weight.
- Totals: Centered, total in dark bold
- Color: Pure monochrome charcoal (#18181b). No accent color at all.
- Vibe: Whisper-quiet. Dieter Rams.

**5. Classic**
- Header: Traditional two-column. Biz info top-left, "INVOICE" + meta top-right. Serif-inspired feel (use helvetica bold with wider tracking to suggest formality).
- Thin burgundy (#7f1d1d) rule below header
- Table: Light bordered grid (all cells), burgundy header bg with white text. Warm gray alternating rows.
- Totals: Right-aligned, burgundy total
- Vibe: Traditional accounting. Established firm.

### Tier 2: Creative & Modern

**6. Modern**
- Header: Asymmetric — "INVOICE" large at top-left. Invoice # and date directly below in smaller text. Biz info block pushed to the right side, vertically centered to the title.
- Thin teal (#0d9488) line separating header from body
- From/To below in two columns
- Table: Borderless, thin teal bottom borders per row, teal header text (not bg fill)
- Totals: Teal total with subtle teal bg strip behind total row
- Vibe: Trendy tech startup.

**7. Elegant**
- Header: Centered. Gold (#a16207) double-rule line at top (two thin lines 1.5mm apart). "INVOICE" centered below. Biz name centered below. Another gold double-rule.
- Below: From/To in two columns
- Table: No colored header bg. Gold double-rule above and below header text. Single thin gold rule between each row. Clean, refined.
- Totals: Right-aligned, gold total
- Vibe: Luxury stationery. Calligraphy studio.

**8. Creative**
- Decorative: Narrow purple (#7c3aed) sidebar on left, full page height, ~6mm wide
- Header: Content offset past sidebar. Logo near sidebar. "INVOICE" in purple.
- From/To below
- Table: Each row styled as a subtle card (very faint bg + tiny border-radius visual feel via padding). Purple-tinted header text.
- Totals: Purple total
- Vibe: Creative agency portfolio.

**9. Compact**
- Header: Single-line inline — biz name left, "INVOICE #XXX" right, all on one line. Date/due below.
- From/To: Two columns, tight spacing
- Table: Tight zebra stripes (6mm rows), no borders. Efficient use of space.
- Totals: Right-aligned, subtle
- Color: Slate (#475569) accent
- Vibe: Accountant's no-nonsense. Data-dense but clean.

### Tier 3: Warm & Distinctive

**10. Dark**
- Entire page: Near-black (#0f172a) background
- All text: Light (#e2e8f0). "INVOICE" in cyan (#06b6d4). Thin cyan accent line.
- Table: Very dark header (#020617) with cyan column names. Alternating dark rows.
- Totals: Cyan total on dark bg
- Vibe: IDE/terminal aesthetic.

**11. Vibrant**
- Header: Full-width gradient band (coral #ea580c to warm orange #f97316), ~45mm. White "INVOICE" + biz info inside.
- Below: From/To
- Table: Light warm-tinted header, borderless, light warm row tints
- Totals: Coral total
- Vibe: SaaS marketing. Warm and energetic.

**12. Corporate**
- Header: Deep blue (#1e40af) band across top ~45mm with white text. Below band: a thin lighter blue info bar with invoice meta.
- From/To below bars
- Table: Light bordered (thin gray on all cells), blue header row
- Totals: Blue total
- Vibe: Enterprise. Annual report.

### Tier 4: Premium & Specialized

**13. Fresh**
- Header: Logo left. Large invoice number right side (oversized, light sky blue text as a background watermark effect). "INVOICE" smaller above the number.
- From/To below
- Table: Sky blue (#0284c7) header bg, light blue zebra stripes
- Totals: Sky blue total
- Vibe: Startup friendly. Light and airy.

**14. Natural**
- Entire page: Warm beige (#fdf6ec) background
- "INVOICE" in terracotta (#c2703e). Biz info in warm brown.
- Table: Terracotta header, warm cream alternating rows on beige
- Totals: Terracotta total
- Vibe: Artisan workshop. Organic soap shop.

**15. Statement**
- Header: "INVOICE" normal size top-left. But the TOTAL AMOUNT is displayed massively (32pt+) in the top-right as the hero element, with "TOTAL DUE" label above it.
- Below: Standard From/To, invoice meta
- Table: Clean, whitespace-only separation. No borders, no stripes. Just generous padding.
- Totals: Already displayed prominently at top. Bottom totals section is a simple summary.
- Color: Monochrome with rose (#be123c) accent on the big total
- Vibe: "Pay me" energy. Total-forward design.

---

## Files to Change

### Modify
- `src/views/Invoices.vue` — Remove template picker from create tab, add new 'template-picker' view state, change handleCreate to navigate to picker after save
- `src/utils/invoiceTemplates.ts` — Rewrite configs with new template IDs and color palettes
- `src/components/InvoicePreview.vue` — Complete rewrite with 15 genuinely unique layouts following typography research
- `src/utils/invoicePdfRenderer.ts` — Complete rewrite with 15 matching PDF render functions using proper type scale
- `src-tauri/src/database.rs` — Add `template_id` column to invoices table
- `src-tauri/src/commands.rs` — Add `update_invoice_template` command

### Keep as-is
- `src/utils/invoicePdf.ts` — Thin wrapper, just update signature if needed
- `src/components/InvoiceTemplatePicker.vue` — The split-pane layout is fine, may adjust sizing for full-screen use
- `src/stores/invoices.ts` — May need minor update for template_id field

## Verification
1. Create an invoice → lands on template picker with actual data
2. All 15 templates render with correct typography scale and unique layouts
3. Each template is immediately visually distinguishable from the others
4. Total amount is the most prominent element in every template
5. PDF export matches the HTML preview for all templates
6. Template choice persists — reopen an invoice and it remembers
7. No text below 10pt in PDF (8pt for fine print only)
8. Tables use borderless/subtle-rule design (no spreadsheet grids)