# 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

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

### Spacing Scale

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

### Breakpoints

```css
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

```css
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:**
```html
[⬜ White] [⬛ Black] [🔴 Red] [🔵 Blue]
```

**Size/Text Variations:**
```html
[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:**
```html
<!-- 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:**
```html
<!-- 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:**
```html
<!-- 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:**
```html
<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

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

### Semantic Colors

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

### Sale/Discount

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

### Stock Status

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

### Neutral Scale

```css
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:**
```css
Height:         h-14 (56px)
Padding:        px-6
Font:           text-lg font-bold
Border Radius:  rounded-lg
Shadow:         shadow-lg hover:shadow-xl
```

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

**Quantity Buttons:**
```css
Size:           44x44px minimum (touch target)
Border:         border-2
Icon:           Plus/Minus (20px)
```

### Touch Targets

**Minimum Sizes:**
```css
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:**
```css
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:**
```css
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:**
```css
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:**
```css
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
