docs: add invoice templates design document

15 visually distinct templates across 4 tiers (Professional Essentials, Creative & Modern, Warm & Distinctive, Premium & Specialized) with template config schema, picker UI design, shared renderer architecture, and business identity support.
2026-02-18 13:07:39 +02:00
parent 291429e1b8
commit 2e4143edc0
1 changed files with 239 additions and 0 deletions
--- a/docs/plans/2026-02-18-invoice-templates-design.md
+++ b/docs/plans/2026-02-18-invoice-templates-design.md
@@ -0,0 +1,239 @@
+# Invoice Templates Design
+
+## Goal
+Add 15 visually distinct invoice templates to ZeroClock with a template picker that shows live previews, replacing the current single hardcoded layout.
+
+## Architecture
+Template Config Objects approach: each template is a config object describing colors, layout, typography, and decorative elements. A single shared renderer reads the config and produces both the Vue preview (HTML/CSS) and jsPDF output. This keeps code DRY — one renderer, 15 configs.
+
+## Tech Stack
+- jsPDF for PDF generation (already installed)
+- Vue 3 Composition API for preview renderer
+- Tailwind CSS v4 for template picker UI
+- No new dependencies required
+
+---
+
+## Template Config Schema
+
+```ts
+interface InvoiceTemplateConfig {
+  id: string
+  name: string
+  category: 'essential' | 'creative' | 'warm' | 'premium'
+  description: string
+
+  // Colors
+  colors: {
+    primary: string      // Main accent color
+    secondary: string    // Secondary accent
+    background: string   // Page background
+    headerBg: string     // Header area background
+    headerText: string   // Header text color
+    bodyText: string     // Body text color
+    tableHeaderBg: string
+    tableHeaderText: string
+    tableRowAlt: string  // Alternating row color
+    tableBorder: string
+    totalHighlight: string
+  }
+
+  // Layout
+  layout: {
+    logoPosition: 'top-left' | 'top-center' | 'top-right'
+    headerStyle: 'full-width' | 'split' | 'minimal' | 'sidebar' | 'gradient' | 'geometric' | 'centered'
+    tableStyle: 'bordered' | 'striped' | 'borderless' | 'minimal-lines' | 'colored-sections'
+    totalsPosition: 'right' | 'center'
+    showDividers: boolean
+    dividerStyle: 'thin' | 'double' | 'thick' | 'none'
+  }
+
+  // Typography
+  typography: {
+    titleSize: number     // Invoice title font size
+    titleWeight: 'bold' | 'normal'
+    headerSize: number    // Section header font size
+    bodySize: number      // Body text font size
+    numberStyle: 'normal' | 'monospace-feel' // For amounts
+  }
+
+  // Decorative
+  decorative: {
+    cornerShape: 'none' | 'colored-block' | 'triangle' | 'diagonal'
+    sidebarWidth: number  // 0 for none
+    sidebarColor: string
+    useGradientHeader: boolean
+    gradientFrom?: string
+    gradientTo?: string
+    backgroundTint: boolean
+    backgroundTintColor?: string
+  }
+}
+```
+
+## 15 Templates
+
+### Tier 1: Professional Essentials
+
+**1. Clean Minimal**
+- White background, single accent line (#3B82F6 blue) under header
+- Left-aligned logo, right-aligned invoice details
+- Thin 1px borders, generous whitespace
+- Inspired by Stripe invoices, Swiss design principles
+
+**2. Corporate Classic**
+- Navy (#1E3A5F) header band with white text
+- Two-column header: business left, invoice meta right
+- Gray alternating rows, bold column headers
+- Inspired by QuickBooks Professional template
+
+**3. Modern Bold**
+- Large colored accent block top-left (#6366F1 indigo)
+- Oversized invoice number, bold typography
+- Borderless table with colored header row
+- Inspired by Invoice Ninja Bold template
+
+**4. Elegant Serif**
+- Charcoal (#374151) with gold (#B8860B) accent lines
+- Centered header layout, refined spacing
+- Thin-rule dividers between sections
+- Inspired by luxury invoicing trends
+
+**5. Simple Two-Tone**
+- Split header: dark left (#1F2937), light right
+- Single-line table dividers only
+- Accent (#10B981 emerald) only on totals
+- Inspired by FreshBooks Modern template
+
+### Tier 2: Creative & Modern
+
+**6. Gradient Header**
+- Full-width gradient header (#667EEA to #764BA2)
+- White text on gradient for business name
+- Striped table rows, generous padding
+- Inspired by 2026 gradient design trends
+
+**7. Sidebar Accent**
+- Narrow (#E11D48 rose) vertical bar left edge, full page height
+- Business info offset from sidebar
+- Modern asymmetric layout
+- Inspired by Invoice Ninja Creative template
+
+**8. Geometric Modern**
+- Colored triangle shape top-right corner (#8B5CF6 violet)
+- Diagonal line element in header area
+- Contemporary, design-forward
+- Inspired by Dribbble geometric invoice designs
+
+**9. Dark Mode**
+- Near-black (#1A1A2E) background
+- Light text (#E2E8F0), cyan (#06B6D4) highlights
+- Inverted table (dark rows, light text)
+- Strong 2025-2026 trend
+
+### Tier 3: Warm & Distinctive
+
+**10. Warm Natural**
+- Warm beige (#FDF6EC) page background
+- Terracotta (#C2703E) accents, olive secondary
+- Soft, organic, approachable feel
+
+**11. Playful Color Block**
+- Teal (#0D9488) and coral (#F97316) blocks
+- Colored backgrounds for different sections
+- Fun but professional balance
+- Inspired by Invoice Ninja Playful template
+
+**12. Retro Professional**
+- Double-rule lines, classic bordered table
+- Warm brown (#78350F) monochrome palette
+- Vintage typography hierarchy
+- Inspired by Invoice Ninja Hipster template
+
+### Tier 4: Premium & Specialized
+
+**13. Tech Minimal**
+- Slate (#475569) with electric green (#22C55E) accents
+- Ultra-clean grid, large numbers
+- Code-editor-inspired aesthetic
+- Inspired by Invoice Ninja Tech template
+
+**14. Executive Premium**
+- Black (#111827) and gold (#D4AF37) scheme
+- Generous margins, premium spacing
+- Luxury feel, restrained decoration
+
+**15. Data-Driven Clean**
+- Deep blue (#1E40AF) primary
+- Large prominent total amount display
+- Emphasis on data hierarchy
+- KPI-style layout for amounts
+
+## Template Picker UI
+
+### Location
+Dropdown/selector in the invoice create form and in the preview dialog header.
+
+### Layout
+Split-pane design:
+- **Left panel** (30%): Scrollable list of template names grouped by category, with small color dot indicators
+- **Right panel** (70%): Live preview of selected template using sample/current invoice data
+- Clicking a template name immediately updates the preview
+
+### Category Headers
+Templates grouped under: "Professional Essentials", "Creative & Modern", "Warm & Distinctive", "Premium & Specialized"
+
+### Preview Rendering
+- Preview uses the same renderer that generates the PDF, but outputs to an HTML canvas/div
+- Shows a scaled-down A4 page with actual template styling
+- Uses sample data (or current invoice data if available)
+
+## Business Identity
+
+### Settings Fields (already partially exist)
+- `business_name` - Company/freelancer name
+- `business_address` - Full address
+- `business_email` - Contact email
+- `business_phone` - Contact phone
+- `business_logo` - Base64-encoded logo image (PNG/JPG)
+
+### Logo Handling
+- Upload via Settings > Business tab
+- Stored as base64 in settings DB
+- Rendered in PDF via `doc.addImage()`
+- Max size: 200x80px (auto-scaled)
+- Position determined by template config
+
+## Shared Renderer Architecture
+
+```
+InvoiceTemplateConfig + InvoiceData + ClientData + Items
+                    ↓
+           Shared Renderer Logic
+           ↓                    ↓
+    Vue HTML Preview      jsPDF Generator
+    (scaled div)          (actual PDF)
+```
+
+### Implementation Approach
+- `src/utils/invoiceTemplates.ts` — 15 template config objects + registry
+- `src/utils/invoicePdfRenderer.ts` — jsPDF renderer that reads config
+- `src/components/InvoicePreview.vue` — Vue component that renders HTML preview from config
+- `src/components/InvoiceTemplatePicker.vue` — Split-pane picker UI
+
+### Renderer Functions
+Each layout/decorative feature maps to a render function:
+- `renderHeader(doc, config, data)` — Handles all header styles
+- `renderLineItems(doc, config, items)` — Handles all table styles
+- `renderTotals(doc, config, totals)` — Handles totals section
+- `renderDecorative(doc, config)` — Handles corners, sidebars, gradients
+- `renderFooter(doc, config, notes)` — Handles notes and footer
+
+## Verification
+1. All 15 templates render correctly in both preview and PDF
+2. Template picker shows all templates with live preview
+3. Each template is visually distinct and professional
+4. Logo renders correctly in templates that support it
+5. Currency/locale formatting works across all templates
+6. Long content (many line items) handles page breaks correctly
+7. PDF export works via Tauri save dialog for all templates