# Berrypod 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.

## Typography System

### Type Scale Rationale

We use the **Major Third (1.25) ratio** for our type scale. Common ratios and their use cases:

| Ratio | Name | Best Use Case |
|-------|------|---------------|
| 1.125 | Major Second | Dense UIs, dashboards |
| **1.25** | **Major Third** | **E-commerce (our choice)** |
| 1.333 | Perfect Fourth | Editorial, content-heavy |
| 1.5 | Perfect Fifth | High-contrast headlines |
| 1.618 | Golden Ratio | Luxury, creative projects |

Major Third provides sufficient hierarchy without oversized mobile headings.

### Line-Height Guidelines

Line-height follows an inverse relationship with font size—larger text needs tighter leading:

| Context | Line-height |
|---------|-------------|
| Large headings (32px+) | 1.1–1.2 |
| Subheadings (20–28px) | 1.2–1.3 |
| Body text | 1.5–1.6 (WCAG minimum) |
| Small text (<14px) | 1.4–1.5 |

### Font Pairing Categories

Our 7 typography presets draw from these research-backed pairing styles:

| Style | Heading Font | Body Font | Use Case |
|-------|-------------|-----------|----------|
| Clean | Manrope | Inter | Default, versatile |
| Editorial | Playfair Display | Raleway | Fashion, magazines |
| Modern | Space Grotesk | Inter | Tech, contemporary |
| Classic | Cormorant Garamond | Source Serif | Traditional, luxury |
| Friendly | Fraunces | Work Sans | Playful, approachable |
| Minimal | DM Sans | Source Serif | Ultra-clean |
| Impulse | Raleway | Inter | Fashion editorial |

**Key research finding**: Serif fonts increase perceived quality by 13% and reliability by 9% (Monotype/Neurons research). We use serifs for editorial and classic presets.

### Spacing System

We use an **8px baseline grid** (Material Design, iOS standard):
- Most screen sizes divide evenly by 8
- Scales cleanly to @1x, @2x, @3x resolutions
- Reduces decisions to: 8, 16, 24, 32, 40, 48px

Body text at 16px with 1.5 line-height = 24px (3 × 8), keeping text on the grid.

## E-commerce Typography Patterns

Research from Baymard Institute (200,000+ hours of UX testing):

### Product Page Hierarchy
- **Product title**: Largest text (20–28px), semi-bold to bold
- **Price**: High prominence near Add to Cart, 4.5:1 minimum contrast
- **CTA buttons**: Clean sans-serif, 14–16px, action verbs ("Add to basket")
- **Body descriptions**: 16–18px, 1.5 line-height, structured with subheadings

### Mobile Requirements
- **Touch targets**: 44×44px minimum (WCAG AAA)
- **Body text**: 16px minimum (prevents iOS input zoom)
- **Avoid horizontal tabs**—27% of users overlook them

### Scanning Patterns
- **F-pattern** (product pages): Horizontal top, shorter line below, vertical down left
- **Z-pattern** (landing pages): Top-left → top-right → diagonal → bottom-right

## Accessibility Baseline

Every theme must meet WCAG 2.1 AA:

### Colour Contrast
- Normal text: 4.5:1 minimum
- Large text (18px+ or 14px bold): 3:1 minimum
- UI components and graphics: 3:1 minimum

### Focus Indicators
- Visible focus ring on all interactive elements
- Never remove outline without replacement
- Ring should have 3:1 contrast with adjacent colours

### Touch Targets
- Minimum 44×44px for touch targets
- 8px minimum spacing between targets

### Screen Reader Support
- Semantic HTML (button for buttons, not div)
- Alt text on all images
- ARIA labels where needed
- Skip links for keyboard navigation
- Logical heading hierarchy (h1 → h2 → h3)

## Quality Checklist

Before shipping, verify:

### Layout
- [ ] Mobile-first responsive design
- [ ] No horizontal scroll on any viewport
- [ ] Content readable at 320px minimum
- [ ] Touch targets 44×44px minimum

### Navigation
- [ ] Logo links to homepage
- [ ] Cart always accessible
- [ ] Current page indicated
- [ ] Mobile menu works smoothly

### Product Cards
- [ ] Consistent aspect ratios
- [ ] Price clearly visible
- [ ] Hover state provides value
- [ ] Links are obvious

### Product Page
- [ ] Images zoomable
- [ ] Price prominent
- [ ] Add to Cart visible on mobile
- [ ] Trust signals visible

### Ethical Design
- [ ] No fake urgency/scarcity
- [ ] No confirmshaming
- [ ] No hidden costs
- [ ] Clear, neutral options
- [ ] Honest product information

### Accessibility
- [ ] Colour contrast passes WCAG AA
- [ ] Focus rings visible
- [ ] Semantic HTML
- [ ] Alt text on images
- [ ] Keyboard navigable

### Performance
- [ ] Images lazy loaded (except hero)
- [ ] Fonts preloaded
- [ ] No layout shift

## 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.
