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:

--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:

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:

<!-- 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:

--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:

<!-- 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:

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