diff --git a/docs/research/design-philosophy.md b/docs/research/design-philosophy.md
new file mode 100644
index 0000000..4e3e277
--- /dev/null
+++ b/docs/research/design-philosophy.md
@@ -0,0 +1,80 @@
+# SimpleshopTheme Design Philosophy
+
+This document captures the design principles and research that informed the theme system architecture.
+
+## Core Principles
+
+1. **"One theme, infinite variations"** - Rather than offering multiple themes, we provide one solid foundation with curated customisation options
+2. **Constrained creativity** - Limit choices to prevent poor design outcomes while maintaining perceived variety
+3. **No professional photography required** - Defaults work well with product mockups, not just lifestyle imagery
+4. **Mobile-first** - All features work on touch devices (no hover-only interactions)
+5. **Ethical design** - No dark patterns like countdown timers or fake urgency
+
+## Target Audience
+
+- Solo POD creators (artists, illustrators, designers)
+- Small catalogs (typically <50 products)
+- Non-technical users who found WooCommerce too complex
+- Budget-conscious sellers
+
+## Research Findings: POD Theme Best Practices
+
+### What POD Sellers Actually Use
+- **Free themes dominate**: Dawn, Spotlight, Studio most popular on Shopify
+- **Premium choice**: Streamline ($350) best for growing POD brands
+- **Impulse** is fashion-focused, not ideal POD default
+
+### Key Requirements for POD
+1. Large product imagery (mockups need to shine)
+2. Clean/minimal design (products are the focus)
+3. Quick setup (non-technical users)
+4. Mobile-responsive (60%+ traffic)
+5. Works with small catalogs
+6. No reliance on lifestyle photography
+
+### What to Avoid
+- Countdown timers (dark pattern)
+- Complex promotional systems
+- Hover-only interactions
+- Features requiring professional photography
+- Enterprise complexity
+
+## Preset Design Rationale
+
+Each preset targets a specific aesthetic/use case:
+
+| Preset | Target Use Case |
+|--------|-----------------|
+| Gallery | Art galleries, editorial brands |
+| Studio | Default, versatile, works for most |
+| Boutique | Artisan, handmade goods |
+| Bold | Tech, contemporary, statement brands |
+| Playful | Fun, casual, approachable brands |
+| Minimal | Ultra-clean, luxury positioning |
+| Night | Premium, dramatic, dark mode lovers |
+| Classic | Traditional, established feel |
+
+## Customisation Philosophy
+
+### Parameters Exposed to Users
+- **Font pairing preset** - Enables brand expression without typography expertise
+- **Colour moods** - Warm/Cool/Neutral/Dark covers most brand needs
+- **Shape options** - Sharp/Soft/Round/Pill for personality
+- **Density** - Adjust spacing for catalog size
+- **Accent colours** - Primary brand customisation
+
+### Parameters Locked Down
+- **Line-height ratios** - Users break readability when exposed
+- **Letter-spacing** - Technical, easy to ruin
+- **Type scale ratio** - Mathematical harmony shouldn't be adjustable
+- **Mobile scaling** - Complex responsive logic
+
+The principle: expose choices that are hard to get wrong, lock down choices that require design expertise.
+
+## Combination Count
+
+With current options, the system offers:
+- 4 moods × 7 typographies × 4 shapes × 3 densities × 3 grids × 3 headers = **3,024 base combinations**
+- Plus accent colours, layout width, button styles, shadows, etc.
+
+This provides sufficient variety while keeping all combinations visually coherent.
diff --git a/docs/spec.md b/docs/spec.md
deleted file mode 100644
index 8f09311..0000000
--- a/docs/spec.md
+++ /dev/null
@@ -1,423 +0,0 @@
-# SimpleShop Theme Studio - Complete Implementation Summary
-
-## Overview
-
-This document summarises the complete Theme Studio feature developed for SimpleShop - an open-source POD (print-on-demand) e-commerce platform built with Phoenix/Elixir/LiveView. The Theme Studio allows sellers to customise their shop's appearance through a constrained but flexible system of presets and options.
-
-## Design Philosophy
-
-### Core Principles
-1. **"One theme, infinite variations"** - Rather than offering multiple themes, we provide one solid foundation with curated customisation options
-2. **Constrained creativity** - Limit choices to prevent poor design outcomes while maintaining perceived variety
-3. **No professional photography required** - Defaults work well with product mockups, not just lifestyle imagery
-4. **Mobile-first** - All features work on touch devices (no hover-only interactions)
-5. **Ethical design** - No dark patterns like countdown timers or fake urgency
-
-### Target Audience
-- Solo POD creators (artists, illustrators, designers)
-- Small catalogs (typically <50 products)
-- Non-technical users who found WooCommerce too complex
-- Budget-conscious sellers (£5-10/month target price)
-
-## Feature Architecture
-
-### Preset System
-
-Nine curated presets that combine multiple settings into cohesive looks:
-
-```elixir
-@presets %{
-  gallery: %{
-    mood: "warm",
-    typography: "editorial", 
-    shape: "soft",
-    density: "spacious",
-    grid: "3",
-    header: "centered",
-    accent: "#e85d04"
-  },
-  studio: %{
-    mood: "neutral",
-    typography: "clean",
-    shape: "soft", 
-    density: "balanced",
-    grid: "4",
-    header: "standard",
-    accent: "#3b82f6"
-  },
-  boutique: %{
-    mood: "warm",
-    typography: "classic",
-    shape: "soft",
-    density: "balanced",
-    grid: "3",
-    header: "centered",
-    accent: "#b45309"
-  },
-  bold: %{
-    mood: "neutral",
-    typography: "modern",
-    shape: "sharp",
-    density: "compact",
-    grid: "4",
-    header: "standard",
-    accent: "#dc2626"
-  },
-  playful: %{
-    mood: "neutral",
-    typography: "friendly",
-    shape: "pill",
-    density: "balanced",
-    grid: "4",
-    header: "standard",
-    accent: "#8b5cf6"
-  },
-  minimal: %{
-    mood: "cool",
-    typography: "minimal",
-    shape: "sharp",
-    density: "spacious",
-    grid: "2",
-    header: "minimal",
-    accent: "#171717"
-  },
-  night: %{
-    mood: "dark",
-    typography: "modern",
-    shape: "soft",
-    density: "balanced",
-    grid: "4",
-    header: "standard",
-    accent: "#f97316"
-  },
-  classic: %{
-    mood: "warm",
-    typography: "classic",
-    shape: "soft",
-    density: "spacious",
-    grid: "3",
-    header: "standard",
-    accent: "#166534"
-  },
-  impulse: %{
-    mood: "neutral",
-    typography: "impulse",
-    shape: "sharp",
-    density: "spacious",
-    grid: "3",
-    header: "centered",
-    accent: "#000000",
-    font_size: "medium",
-    heading_weight: "regular",
-    layout_width: "full",
-    button_style: "filled",
-    card_shadow: "none",
-    product_text: "center"
-  }
-}
-```
-
-### Customisation Options
-
-#### Typography Styles
-| Style | Heading Font | Body Font | Weight | Use Case |
-|-------|-------------|-----------|--------|----------|
-| clean | Inter | Inter | 600 | Default, versatile |
-| editorial | Fraunces (serif) | Source Sans | 600 | Art galleries, editorial |
-| modern | Space Grotesk | Space Grotesk | 500 | Tech, contemporary |
-| classic | Libre Baskerville | Source Sans | 400 | Traditional, luxury |
-| friendly | Nunito | Nunito | 700 | Playful, approachable |
-| minimal | Outfit | Outfit | 300 | Ultra-clean, light |
-| impulse | Nunito Sans | Nunito Sans | 300 | Fashion editorial |
-
-#### Colour Moods
-| Mood | Background | Text | Border | Use Case |
-|------|------------|------|--------|----------|
-| neutral | #ffffff | #171717 | #e5e5e5 | Default, works with any accent |
-| warm | #fdf8f3 | #1c1917 | #e7e0d8 | Cosy, artisan, handmade |
-| cool | #f4f7fb | #0f172a | #d4dce8 | Tech, modern, professional |
-| dark | #0a0a0a | #fafafa | #262626 | Premium, dramatic, night mode |
-
-#### Shape Options
-| Shape | Border Radius | Use Case |
-|-------|--------------|----------|
-| sharp | 0 | Modern, editorial, bold |
-| soft | 0.5rem | Default, approachable |
-| round | 0.75-1rem | Friendly, playful |
-| pill | 9999px (buttons) | Fun, casual, rounded |
-
-#### Density Options
-| Density | Multiplier | Use Case |
-|---------|------------|----------|
-| spacious | 1.25x | Editorial, luxury, few products |
-| balanced | 1x | Default, most stores |
-| compact | 0.75x | Large catalogs, utilitarian |
-
-#### Layout Options
-- **Grid columns**: 2, 3, or 4 products per row
-- **Header layout**: Standard (left logo), Centered, Minimal
-- **Layout width**: Contained (1200px), Wide (1400px), Full width
-- **Button style**: Filled, Outline, Soft
-- **Card shadow**: None, Subtle, Pronounced
-- **Product text alignment**: Left, Center
-- **Image aspect ratio**: Square, Portrait, Landscape
-
-### Branding Options
-
-#### Logo Modes
-1. **Text only** - Shop name as styled text
-2. **Logo + text** - Logo image alongside shop name
-3. **Logo only** - Just the logo image
-4. **Header image** - Full-width header background
-5. **Logo + header image** - Both logo and header background
-
-#### Logo Features
-- Upload support (PNG, JPG, WebP, SVG)
-- Size slider (24-120px)
-- SVG recolouring option (change logo colour to match theme)
-
-#### Header Image Features
-- Background image upload
-- Zoom control (100-200%)
-- Horizontal position (0-100%)
-- Vertical position (0-100%)
-
-### Toggle Features
-- Announcement bar (on/off)
-- Sticky header (on/off)
-- Second image on hover (on/off)
-- Quick add button (on/off)
-- Show prices (on/off)
-- Trust badges on PDP (on/off)
-- Reviews section on PDP (on/off)
-- Related products on PDP (on/off)
-
-## Data Model
-
-### Theme Settings Schema
-
-```elixir
-defmodule SimpleShop.Shops.ThemeSettings do
-  use Ecto.Schema
-  import Ecto.Changeset
-
-  embedded_schema do
-    # Core preset (optional - if set, provides defaults)
-    field :preset, :string
-    
-    # Branding
-    field :shop_name, :string
-    field :logo_mode, :string, default: "text-only"
-    field :logo_url, :string
-    field :logo_size, :integer, default: 36
-    field :logo_recolor, :boolean, default: false
-    field :logo_color, :string, default: "#171717"
-    field :header_image_url, :string
-    field :header_zoom, :integer, default: 100
-    field :header_position_x, :integer, default: 50
-    field :header_position_y, :integer, default: 50
-    
-    # Theme tokens
-    field :mood, :string, default: "neutral"
-    field :typography, :string, default: "clean"
-    field :shape, :string, default: "soft"
-    field :density, :string, default: "balanced"
-    field :accent_color, :string, default: "#f97316"
-    field :hover_color, :string
-    field :sale_color, :string, default: "#dc2626"
-    
-    # Layout
-    field :grid_columns, :integer, default: 4
-    field :header_layout, :string, default: "standard"
-    field :layout_width, :string, default: "wide"
-    field :font_size, :string, default: "medium"
-    field :heading_weight, :string, default: "bold"
-    field :button_style, :string, default: "filled"
-    field :card_shadow, :string, default: "none"
-    field :product_text_align, :string, default: "left"
-    field :image_aspect_ratio, :string, default: "square"
-    field :gallery_position, :string, default: "left"
-    
-    # Feature toggles
-    field :announcement_bar, :boolean, default: true
-    field :sticky_header, :boolean, default: false
-    field :hover_image, :boolean, default: true
-    field :quick_add, :boolean, default: true
-    field :show_prices, :boolean, default: true
-    field :pdp_trust_badges, :boolean, default: true
-    field :pdp_reviews, :boolean, default: true
-    field :pdp_related_products, :boolean, default: true
-  end
-end
-```
-
-### CSS Custom Properties
-
-The theme system uses CSS custom properties for real-time updates. Key variables:
-
-```css
-/* Primitives (fixed) */
---p-space-1 through --p-space-24
---p-radius-none through --p-radius-full
---p-font-inter, --p-font-fraunces, etc.
---p-text-xs through --p-text-4xl
-
-/* Theme tokens (dynamic) */
---t-surface-base, --t-surface-raised, --t-surface-sunken
---t-text-primary, --t-text-secondary, --t-text-tertiary
---t-border-default, --t-border-subtle
---t-accent (HSL-based for easy manipulation)
---t-font-heading, --t-font-body
---t-heading-weight, --t-heading-tracking
---t-radius-button, --t-radius-card, --t-radius-input
---t-density (multiplier)
-
-/* Semantic aliases */
---color-page, --color-card, --color-heading, --color-body
---font-heading, --font-body, --weight-heading
---space-xs through --space-2xl
---radius-button, --radius-card
-```
-
-## LiveView Implementation Notes
-
-### Real-time Preview
-
-The theme editor should provide instant visual feedback. In Phoenix LiveView:
-
-```elixir
-defmodule SimpleShopWeb.ThemeEditorLive do
-  use SimpleShopWeb, :live_view
-  
-  def mount(_params, _session, socket) do
-    {:ok, assign(socket, 
-      settings: default_settings(),
-      preview_page: "home"
-    )}
-  end
-  
-  def handle_event("update_setting", %{"key" => key, "value" => value}, socket) do
-    settings = Map.put(socket.assigns.settings, String.to_atom(key), value)
-    {:noreply, assign(socket, settings: settings)}
-  end
-  
-  def handle_event("apply_preset", %{"preset" => preset_name}, socket) do
-    preset = Map.get(@presets, String.to_atom(preset_name))
-    settings = Map.merge(socket.assigns.settings, preset)
-    {:noreply, assign(socket, settings: settings)}
-  end
-  
-  def handle_event("change_preview_page", %{"page" => page}, socket) do
-    {:noreply, assign(socket, preview_page: page)}
-  end
-end
-```
-
-### CSS Generation
-
-Generate CSS custom properties from settings:
-
-```elixir
-defmodule SimpleShop.Theme.CSSGenerator do
-  def generate_css(settings) do
-    """
-    :root {
-      --t-accent-h: #{accent_hue(settings.accent_color)};
-      --t-accent-s: #{accent_saturation(settings.accent_color)}%;
-      --t-accent-l: #{accent_lightness(settings.accent_color)}%;
-      /* ... other properties */
-    }
-    
-    #{mood_css(settings.mood)}
-    #{typography_css(settings.typography)}
-    #{shape_css(settings.shape)}
-    #{density_css(settings.density)}
-    """
-  end
-end
-```
-
-## File Uploads
-
-### Logo Upload
-- Accepted formats: PNG, JPG, WebP, SVG
-- Max size: 2MB recommended
-- SVG special handling: Store raw content for recolouring feature
-- Storage: Local or S3-compatible (user's choice for data sovereignty)
-
-### Header Image Upload
-- Accepted formats: PNG, JPG, WebP
-- Max size: 5MB recommended
-- Responsive serving: Generate multiple sizes
-
-## Preview Pages
-
-The demo includes 7 preview pages to show theme in context:
-
-1. **Home** - Hero, categories, featured products, testimonials
-2. **Collection** - Product grid with filters
-3. **Product (PDP)** - Gallery, details, add to cart, reviews
-4. **Cart** - Line items, totals, checkout button
-5. **About** - Brand story, values
-6. **Contact** - Contact form, details
-7. **Error (404)** - Error state styling
-
-## Research Findings: POD Theme Best Practices
-
-### What POD Sellers Actually Use
-- **Free themes dominate**: Dawn, Spotlight, Studio most popular
-- **Premium choice**: Streamline ($350) best for growing POD brands
-- **Impulse** is fashion-focused, not ideal POD default
-
-### Key Requirements for POD
-1. Large product imagery (mockups need to shine)
-2. Clean/minimal design (products are the focus)
-3. Quick setup (non-technical users)
-4. Mobile-responsive (60%+ traffic)
-5. Works with small catalogs
-6. No reliance on lifestyle photography
-
-### What to Avoid
-- Countdown timers (dark pattern)
-- Complex promotional systems
-- Hover-only interactions
-- Features requiring professional photography
-- Enterprise complexity
-
-## Recommended Next Steps for Phoenix Implementation
-
-### Phase 1: Core Theme System
-1. Create ThemeSettings schema and migrations
-2. Build CSS generator module
-3. Implement preset system
-4. Create basic LiveView editor with sidebar controls
-
-### Phase 2: Branding
-1. Logo upload with LiveView uploads
-2. SVG parsing and recolouring
-3. Header image with positioning controls
-
-### Phase 3: Preview System
-1. Live preview component
-2. Page switching (home/collection/product/etc.)
-3. Mock data for preview products
-
-### Phase 4: Persistence
-1. Save to shop record
-2. Apply to storefront templates
-3. CSS caching strategy
-
-## Prototype File
-
-The complete working HTML prototype is available at:
-- `/home/claude/theme-demo-v28.html`
-- `/mnt/user-data/outputs/theme-demo-v28.html`
-
-This 6,277-line file contains all CSS, HTML structure, and JavaScript logic that can be referenced when building the Phoenix/LiveView implementation.
-
-## Combination Count
-
-With current options, the system offers:
-- 4 moods × 7 typographies × 4 shapes × 3 densities × 3 grids × 3 headers = **3,024 base combinations**
-- Plus accent colours, layout width, button styles, shadows, etc.
-- Marketing claim: "100,000+ possible combinations"