WooNooW/STORE_UI_UX_GUIDE.md

WooNooW Store UI/UX Guide

Official Design System & Standards

Version: 1.0
Last Updated: November 26, 2025
Status: Living Document (Updated by conversation)

---

📋 Purpose

This document serves as the single source of truth for all UI/UX decisions in WooNooW Customer SPA. All design and implementation decisions should reference this guide.

Philosophy: Pragmatic, not dogmatic. Follow convention when strong, follow research when clear, use hybrid when beneficial.

---

🎯 Core Principles

1. Convention Over Innovation - Users expect familiar patterns
2. Research-Backed Decisions - When convention is weak or wrong
3. Mobile-First Approach - Design for mobile, enhance for desktop
4. Performance Matters - Fast > Feature-rich
5. Accessibility Always - WCAG 2.1 AA minimum

---

📐 Layout Standards

Container Widths

Mobile:    100% (with padding)
Tablet:    768px max-width
Desktop:   1200px max-width
Wide:      1400px max-width

Spacing Scale

xs:  0.25rem (4px)
sm:  0.5rem  (8px)
md:  1rem    (16px)
lg:  1.5rem  (24px)
xl:  2rem    (32px)
2xl: 3rem    (48px)

Breakpoints

sm:  640px
md:  768px
lg:  1024px
xl:  1280px
2xl: 1536px

---

🎨 Typography

Hierarchy

H1 (Product Title):     28-32px, bold
H2 (Section Title):     24-28px, bold
H3 (Subsection):        20-24px, semibold
Price (Primary):        24-28px, bold
Price (Sale):           24-28px, bold, red
Price (Regular):        18-20px, line-through, gray
Body:                   16px, regular
Small:                  14px, regular
Tiny:                   12px, regular

Font Stack

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 
             Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;

Rules

• ✅ Title > Price in hierarchy (we're not a marketplace)
• ✅ Use weight and color for emphasis, not just size
• ✅ Line height: 1.5 for body, 1.2 for headings
• ❌ Don't use more than 3 font sizes per section

---

🖼️ Product Page Standards

Image Gallery

Desktop:

Layout:
┌─────────────────────────────────────┐
│        [Main Image]                 │
│        (Large, square)              │
└─────────────────────────────────────┘
[▭] [▭] [▭] [▭] [▭] ← Thumbnails (96-112px)

Rules:

• ✅ Thumbnails: 96-112px (24-28 in Tailwind)
• ✅ Horizontal scrollable if >4 images
• ✅ Active thumbnail: Primary border + ring
• ✅ Main image: object-contain with padding
• ✅ Click thumbnail → change main image
• ✅ Click main image → fullscreen lightbox

Mobile:

Layout:
┌─────────────────────────────────────┐
│        [Main Image]                 │
│        (Full width, square)         │
│         ● ○ ○ ○ ○                   │
└─────────────────────────────────────┘

Rules:

• ✅ Dots only (NO thumbnails)
• ✅ Swipe gesture for navigation
• ✅ Dots: 8-10px, centered below image
• ✅ Active dot: Primary color, larger
• ✅ Image counter optional (e.g., "1/5")
• ❌ NO thumbnails (redundant with dots)

Rationale: Convention (Amazon, Tokopedia, Shopify all use dots only on mobile)

---

Variation Selectors

Pattern: Pills/Buttons (NOT Dropdowns)

Color Variations:

[⬜ White] [⬛ Black] [🔴 Red] [🔵 Blue]

Size/Text Variations:

[36] [37] [38] [39] [40] [41]

Rules:

• ✅ All options visible at once
• ✅ Pills: min 44x44px (touch target)
• ✅ Active state: Primary background + white text
• ✅ Hover state: Border color change
• ✅ Disabled state: Gray + opacity 50%
• ❌ NO dropdowns (hides options, poor UX)

Rationale: Convention + Research align (Nielsen Norman Group)

---

Product Information Sections

Pattern: Vertical Accordions

Desktop & Mobile:

┌─────────────────────────────────────┐
│ ▼ Product Description               │ ← Auto-expanded
│   Full description text...          │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ ▶ Specifications                    │ ← Collapsed
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ ▶ Customer Reviews                  │ ← Collapsed
└─────────────────────────────────────┘

Rules:

• ✅ Description: Auto-expanded on load
• ✅ Other sections: Collapsed by default
• ✅ Arrow icon: Rotates on expand/collapse
• ✅ Smooth animation: 200-300ms
• ✅ Full-width clickable header
• ❌ NO horizontal tabs (27% overlook rate)

Rationale: Research (Baymard: vertical > horizontal)

---

Specifications Table

Pattern: Scannable Two-Column Table

┌─────────────────────────────────────┐
│ Material      │ 100% Cotton         │
│ Weight        │ 250g                │
│ Color         │ Black, White, Gray  │
│ Size          │ S, M, L, XL         │
└─────────────────────────────────────┘

Rules:

• ✅ Label column: 33% width, bold, gray background
• ✅ Value column: 67% width, regular weight
• ✅ Padding: py-4 px-6
• ✅ Border: Bottom border on each row
• ✅ Last row: No border
• ❌ NO plain table (hard to scan)

Rationale: Research (scannable > plain)

---

Buy Section

Desktop & Mobile:

Structure:

1. Product Title (H1)
2. Price (prominent, but not overwhelming)
3. Stock Status (badge with icon)
4. Short Description (if exists)
5. Variation Selectors (pills)
6. Quantity Selector (large buttons)
7. Add to Cart (prominent CTA)
8. Wishlist Button (secondary)
9. Trust Badges (shipping, returns, secure)
10. Product Meta (SKU, categories)

Price Display:

<!-- On Sale -->
<div>
  <span class="text-2xl font-bold text-red-600">$79.00</span>
  <span class="text-lg text-gray-400 line-through">$99.00</span>
  <span class="bg-red-600 text-white px-3 py-1 rounded">SAVE 20%</span>
</div>

<!-- Regular -->
<span class="text-2xl font-bold">$99.00</span>

Stock Status:

<!-- In Stock -->
<div class="bg-green-50 text-green-700 px-4 py-2.5 rounded-lg border border-green-200">
  <svg>✓</svg>
  <span>In Stock - Ships Today</span>
</div>

<!-- Out of Stock -->
<div class="bg-red-50 text-red-700 px-4 py-2.5 rounded-lg border border-red-200">
  <svg>✗</svg>
  <span>Out of Stock</span>
</div>

Add to Cart Button:

<!-- Desktop & Mobile -->
<button class="w-full h-14 text-lg font-bold bg-primary text-white rounded-lg shadow-lg hover:shadow-xl">
  <ShoppingCart /> Add to Cart
</button>

Trust Badges:

<div class="space-y-3 border-t-2 pt-4">
  <!-- Free Shipping -->
  <div class="flex items-center gap-3">
    <svg class="w-6 h-6 text-green-600">🚚</svg>
    <div>
      <p class="font-semibold">Free Shipping</p>
      <p class="text-xs text-gray-600">On orders over $50</p>
    </div>
  </div>
  
  <!-- Returns -->
  <div class="flex items-center gap-3">
    <svg class="w-6 h-6 text-blue-600">↩</svg>
    <div>
      <p class="font-semibold">30-Day Returns</p>
      <p class="text-xs text-gray-600">Money-back guarantee</p>
    </div>
  </div>
  
  <!-- Secure -->
  <div class="flex items-center gap-3">
    <svg class="w-6 h-6 text-gray-700">🔒</svg>
    <div>
      <p class="font-semibold">Secure Checkout</p>
      <p class="text-xs text-gray-600">SSL encrypted payment</p>
    </div>
  </div>
</div>

---

Mobile-Specific Patterns

Sticky Bottom Bar (Optional - Future Enhancement)

┌─────────────────────────────────────┐
│ $79.00          [Add to Cart]       │
└─────────────────────────────────────┘

Rules:

• ✅ Fixed at bottom on scroll
• ✅ Shows price + CTA
• ✅ Appears after scrolling past buy section
• ✅ z-index: 50 (above content)
• ✅ Shadow for depth

Rationale: Convention (Tokopedia does this)

---

🎨 Color System

Primary Colors

Primary:        #222222 (dark gray/black)
Primary Hover:  #000000
Primary Light:  #F5F5F5

Semantic Colors

Success:        #10B981 (green)
Error:          #EF4444 (red)
Warning:        #F59E0B (orange)
Info:           #3B82F6 (blue)

Sale/Discount

Sale Price:     #DC2626 (red-600)
Sale Badge:     #DC2626 bg, white text
Savings:        #DC2626 text

Stock Status

In Stock:       #10B981 (green-600)
Low Stock:      #F59E0B (orange-500)
Out of Stock:   #EF4444 (red-500)

Neutral Scale

Gray 50:   #F9FAFB
Gray 100:  #F3F4F6
Gray 200:  #E5E7EB
Gray 300:  #D1D5DB
Gray 400:  #9CA3AF
Gray 500:  #6B7280
Gray 600:  #4B5563
Gray 700:  #374151
Gray 800:  #1F2937
Gray 900:  #111827

---

🔘 Interactive Elements

Buttons

Primary CTA:

Height:         h-14 (56px)
Padding:        px-6
Font:           text-lg font-bold
Border Radius:  rounded-lg
Shadow:         shadow-lg hover:shadow-xl

Secondary:

Height:         h-12 (48px)
Padding:        px-4
Font:           text-base font-semibold
Border:         border-2

Quantity Buttons:

Size:           44x44px minimum (touch target)
Border:         border-2
Icon:           Plus/Minus (20px)

Touch Targets

Minimum Sizes:

Mobile:   44x44px (WCAG AAA)
Desktop:  40x40px (acceptable)

Rules:

• ✅ All interactive elements: min 44x44px on mobile
• ✅ Adequate spacing between targets (8px min)
• ✅ Visual feedback on tap/click
• ✅ Disabled state clearly indicated

---

🖼️ Images

Product Images

Main Image:

Aspect Ratio:   1:1 (square)
Object Fit:     object-contain (shows full product)
Padding:        p-4 (breathing room)
Background:     white or light gray
Border:         border-2 border-gray-200
Shadow:         shadow-lg

Thumbnails:

Desktop:        96-112px (w-24 md:w-28)
Mobile:         N/A (use dots)
Aspect Ratio:   1:1
Object Fit:     object-cover
Border:         border-2
Active:         border-primary ring-4 ring-primary

Rules:

• ✅ Always use !h-full to override WooCommerce styles
• ✅ Lazy loading for performance
• ✅ Alt text for accessibility
• ✅ WebP format when possible
• ❌ Never use object-cover for main image (crops product)

---

📱 Responsive Behavior

Grid Layout

Product Page:

Mobile:    grid-cols-1 (single column)
Desktop:   grid-cols-2 (image | info)
Gap:       gap-8 lg:gap-12

Image Gallery

Desktop:

• Thumbnails: Horizontal scroll if >4 images
• Arrows: Show when >4 images
• Layout: Main image + thumbnail strip below

Mobile:

• Dots: Always visible
• Swipe: Primary interaction
• Counter: Optional (e.g., "1/5")

Typography

Responsive Sizes:

Title:   text-2xl md:text-3xl
Price:   text-2xl md:text-2xl (same)
Body:    text-base (16px, no change)
Small:   text-sm md:text-sm (same)

---

♿ Accessibility

WCAG 2.1 AA Requirements

Color Contrast:

• Text: 4.5:1 minimum
• Large text (18px+): 3:1 minimum
• Interactive elements: 3:1 minimum

Keyboard Navigation:

• ✅ All interactive elements focusable
• ✅ Visible focus indicators
• ✅ Logical tab order
• ✅ Skip links for main content

Screen Readers:

• ✅ Semantic HTML (h1, h2, nav, main, etc.)
• ✅ Alt text for images
• ✅ ARIA labels for icons
• ✅ Live regions for dynamic content

Touch Targets:

• ✅ Minimum 44x44px on mobile
• ✅ Adequate spacing (8px min)

---

🚀 Performance

Loading Strategy

Critical:

• Hero image (main product image)
• Product title, price, CTA
• Variation selectors

Deferred:

• Thumbnails (lazy load)
• Description content
• Reviews section
• Related products

Rules:

• ✅ Lazy load images below fold
• ✅ Skeleton loading states
• ✅ Optimize images (WebP, compression)
• ✅ Code splitting for routes
• ❌ No layout shift (reserve space)

---

📋 Component Checklist

Product Page Must-Haves

Above the Fold:

• Breadcrumb navigation
• Product title (H1)
• Price display (with sale if applicable)
• Stock status badge
• Main product image
• Image navigation (thumbnails/dots)
• Variation selectors (pills)
• Quantity selector
• Add to Cart button
• Trust badges

Below the Fold:

• Product description (auto-expanded)
• Specifications table (collapsed)
• Reviews section (collapsed)
• Product meta (SKU, categories)
• Related products (future)

Mobile Specific:

• Dots for image navigation
• Large touch targets (44x44px)
• Responsive text sizes
• Collapsible sections
• Optional: Sticky bottom bar

Desktop Specific:

• Thumbnails for image navigation
• Hover states
• Larger layout (2-column grid)

---

🎯 Decision Log

Image Gallery

• Decision: Dots only on mobile, thumbnails on desktop
• Rationale: Convention (Amazon, Tokopedia, Shopify)
• Date: Nov 26, 2025

Variation Selectors

• Decision: Pills/buttons, not dropdowns
• Rationale: Convention + Research align (NN/g)
• Date: Nov 26, 2025

Typography Hierarchy

• Decision: Title > Price (28-32px > 24-28px)
• Rationale: Context (we're not a marketplace)
• Date: Nov 26, 2025

Description Pattern

• Decision: Auto-expanded accordion
• Rationale: Research (don't hide primary content)
• Date: Nov 26, 2025

Tabs vs Accordions

• Decision: Vertical accordions, not horizontal tabs
• Rationale: Research (27% overlook tabs)
• Date: Nov 26, 2025

---

📚 References

Research Sources

• Baymard Institute UX Research
• Nielsen Norman Group Guidelines
• WCAG 2.1 Accessibility Standards

Convention Sources

• Amazon (marketplace reference)
• Tokopedia (marketplace reference)
• Shopify (e-commerce reference)

---

🔄 Version History

v1.0 - Nov 26, 2025

• Initial guide created
• Product page standards defined
• Decision framework established

---

Status: ✅ Active
Maintenance: Updated by conversation
Owner: WooNooW Development Team