# 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
$79.00 $99.00 SAVE 20%
$99.00 ``` **Stock Status:** ```html
✓ In Stock - Ships Today
✗ Out of Stock
``` **Add to Cart Button:** ```html ``` **Trust Badges:** ```html
🚚

Free Shipping

On orders over $50

↩

30-Day Returns

Money-back guarantee

🔒

Secure Checkout

SSL encrypted payment

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