simpleshop_theme/simpleshop-ux-component-patterns.md

# SimpleShop UX-Optimised Component Patterns

A research-backed guide to component design that avoids common anti-patterns and creates professional, ethical, high-converting e-commerce experiences.

---

## Spacing & Layout System

Building on the 8px grid from the typography guide:

**Spacing Tokens**:
```css
--space-1: 0.25rem;  /* 4px  - tight */
--space-2: 0.5rem;   /* 8px  - compact */
--space-3: 0.75rem;  /* 12px */
--space-4: 1rem;     /* 16px - default */
--space-5: 1.5rem;   /* 24px */
--space-6: 2rem;     /* 32px */
--space-8: 3rem;     /* 48px - section gaps */
--space-10: 4rem;    /* 64px */
--space-12: 6rem;    /* 96px - major sections */
--space-16: 8rem;    /* 128px - hero spacing */
```

**Tailwind Config**:
```javascript
module.exports = {
  theme: {
    spacing: {
      '0': '0',
      '1': '0.25rem',
      '2': '0.5rem',
      '3': '0.75rem',
      '4': '1rem',
      '5': '1.5rem',
      '6': '2rem',
      '8': '3rem',
      '10': '4rem',
      '12': '6rem',
      '16': '8rem',
    }
  }
}
```

**Section Spacing**:
```html
<!-- Page sections use consistent vertical spacing -->
<section class="py-12 md:py-16">
  <div class="container mx-auto px-4">
    <!-- Content -->
  </div>
</section>
```

**Container Widths**:
```css
--container-prose: 65ch;      /* Text content */
--container-content: 80rem;    /* 1280px - main content */
--container-wide: 90rem;       /* 1440px - full layouts */
```

---

## Component States

Every interactive component needs these states defined:

**Button States**:
```
Default    → Base styling
Hover      → Subtle lift/colour shift (200ms ease)
Active     → Pressed state
Focus      → Visible ring (accessibility)
Disabled   → Greyed, no pointer
Loading    → Spinner, disabled
```

**Form Input States**:
```
Default    → Border, background
Focus      → Ring, border colour change
Error      → Red border, error message below
Success    → Green check (optional, for validation)
Disabled   → Greyed background
```

**Card States**:
```
Default    → Base styling
Hover      → Subtle lift (box-shadow increase)
Focus      → Visible ring (if interactive)
```

---

## Accessibility Baseline

Every SimpleShop 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**:
- 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)

---

## Performance Patterns

**Image Loading**:
```html
<!-- Lazy load below-fold images -->
<img 
  src="product.jpg" 
  alt="Product" 
  loading="lazy"
  decoding="async"
  width="400"
  height="533"
/>

<!-- Eager load above-fold images -->
<img 
  src="hero.jpg" 
  alt="Hero" 
  loading="eager"
  fetchpriority="high"
/>
```

**Font Loading**:
```html
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link 
  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" 
  rel="stylesheet"
>
```

**Critical CSS**:
- Inline above-fold styles
- Defer non-critical CSS
- Remove unused styles

---

## Theme Presets

Combining typography pairings with component styling:

### Minimal Modern
- **Fonts**: Manrope + Inter
- **Cards**: No shadows, subtle borders
- **Buttons**: Solid fills, sharp corners (border-radius: 0 or 2px)
- **Spacing**: Generous, airy
- **Colours**: Monochrome with single accent

### Warm Artisan
- **Fonts**: Cormorant Garamond + Proza Libre
- **Cards**: Subtle shadows, rounded corners
- **Buttons**: Rounded, warm fills
- **Spacing**: Comfortable, not sparse
- **Colours**: Warm neutrals, earthy accents

### Bold Editorial
- **Fonts**: Playfair Display + Raleway
- **Cards**: Strong contrast, dramatic shadows
- **Buttons**: High contrast, possibly outlined
- **Spacing**: Dramatic, asymmetric
- **Colours**: Black/white with bold accent

### Playful Quirky
- **Fonts**: Fraunces + Work Sans
- **Cards**: Rounded, possibly with borders
- **Buttons**: Rounded/pill, playful hover states
- **Spacing**: Varied, dynamic
- **Colours**: Bright, fun palette

### Luxury Elegant
- **Fonts**: Cinzel + Fauna One
- **Cards**: Minimal, refined
- **Buttons**: Thin borders, subtle
- **Spacing**: Generous, refined
- **Colours**: Muted, sophisticated

---

## Implementation Checklist

Before shipping any SimpleShop theme, 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**:
- [ ] Accordion sections, not horizontal tabs
- [ ] Images zoomable
- [ ] Price prominent
- [ ] Add to Cart sticky on mobile
- [ ] Trust signals visible

**Checkout**:
- [ ] Guest checkout prominent
- [ ] Progress indicator clear
- [ ] All costs shown upfront
- [ ] Form fields properly labeled
- [ ] Error messages inline
- [ ] Trust signals present

**Ethical**:
- [ ] No fake urgency/scarcity
- [ ] No confirmshaming
- [ ] No hidden costs
- [ ] No exit-intent popups
- [ ] 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
- [ ] LCP under 2.5s
- [ ] No layout shift (CLS < 0.1)

---

## Summary

SimpleShop's component system prioritises:

1. **Honesty over manipulation** — No dark patterns, ever
2. **Clarity over cleverness** — Obvious UI beats novel UI
3. **Research over assumptions** — Patterns backed by testing
4. **Consistency over creativity** — Systems over one-offs
5. **Accessibility over aesthetics** — Everyone can use it

These patterns, combined with the typography and spacing systems, create a foundation for themes that are not just beautiful but genuinely effective—converting browsers into buyers through trust and clarity rather than tricks and pressure.

The result: shops that sellers are proud of and customers enjoy using.