diff --git a/docs/research/design-philosophy.md b/docs/research/design-philosophy.md index a92fd39..1d13244 100644 --- a/docs/research/design-philosophy.md +++ b/docs/research/design-philosophy.md @@ -142,6 +142,78 @@ Research from Baymard Institute (200,000+ hours of UX testing): - **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: diff --git a/docs/research/ux-patterns.md b/docs/research/ux-patterns.md deleted file mode 100644 index 0866aae..0000000 --- a/docs/research/ux-patterns.md +++ /dev/null @@ -1,276 +0,0 @@ -# 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 - -
-
- -
-
-``` - -**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 - -Product - - -Hero -``` - -**Font Loading**: -```html - - -``` - -**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.