Initial commit
This commit is contained in:
@@ -0,0 +1,380 @@
|
||||
# Account Pages Layout
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Account Dashboard](#account-dashboard)
|
||||
- [Order Management](#order-management)
|
||||
- [Saved Addresses](#saved-addresses)
|
||||
- [Payment Methods](#payment-methods)
|
||||
- [Profile and Security](#profile-and-security)
|
||||
- [Email Preferences](#email-preferences)
|
||||
- [Navigation and Layout](#navigation-and-layout)
|
||||
- [Mobile Considerations](#mobile-considerations)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
Account pages allow customers to manage orders, save addresses, update preferences, and view order history. Well-designed account pages improve repeat purchase rates and reduce support inquiries.
|
||||
|
||||
**Backend Integration (CRITICAL):**
|
||||
|
||||
All customer data (orders, addresses, profile, payment methods) must be fetched from the ecommerce backend. Change this based on backend integrated. Never hardcode or mock account data. Consult backend documentation for:
|
||||
- Customer data endpoints (profile, preferences)
|
||||
- Order history and details endpoints
|
||||
- Address CRUD operations
|
||||
- Payment method storage (if supported)
|
||||
- Authentication requirements
|
||||
|
||||
### Key Ecommerce Requirements
|
||||
|
||||
- Order history with status tracking (builds trust)
|
||||
- Saved addresses (checkout optimization - reduces friction)
|
||||
- Reorder functionality (increases repeat purchases)
|
||||
- Order tracking integration
|
||||
- Email preference controls (compliance and user control)
|
||||
- Secure authentication and session management
|
||||
|
||||
### Purpose
|
||||
|
||||
**Primary ecommerce functions:**
|
||||
- Reduce checkout friction (saved addresses, payment methods)
|
||||
- Increase repeat purchases (order history, reorder button)
|
||||
- Reduce support load (order tracking, self-service returns)
|
||||
- Build trust (order transparency, delivery updates)
|
||||
- Retain customers (easy account management)
|
||||
|
||||
## Account Dashboard
|
||||
|
||||
Landing page after login. Purpose: Quick access to recent activity and common actions.
|
||||
|
||||
**Display (prioritize recent orders):**
|
||||
- Welcome message with customer name
|
||||
- Recent orders (3-5 most recent with status)
|
||||
- Quick actions: Track order, Reorder, Manage addresses
|
||||
- Account summary (saved addresses count, loyalty points)
|
||||
|
||||
**Reorder functionality (CRITICAL for repeat purchases):**
|
||||
- Check first that feature is available in the admin.
|
||||
- "Reorder" button on each order card
|
||||
- Adds same items to cart (check stock availability first)
|
||||
- Success feedback (cart updated with X items)
|
||||
- Don't navigate away (stay on dashboard)
|
||||
|
||||
**Example dashboard:**
|
||||
```
|
||||
Welcome back, Sarah!
|
||||
|
||||
Recent Orders
|
||||
- Order #12345 - Delivered (Jan 28) - $89.99 [Reorder]
|
||||
- Order #12344 - In Transit (Jan 27) - $124.50 [Track Order]
|
||||
- Order #12343 - Processing (Jan 26) - $45.00
|
||||
|
||||
[View All Orders →]
|
||||
|
||||
Quick Actions
|
||||
[Track Order] [Manage Addresses] [Contact Support]
|
||||
```
|
||||
|
||||
## Order Management
|
||||
|
||||
### Order History
|
||||
|
||||
Display all past orders with filtering and search.
|
||||
|
||||
**Order card essentials:**
|
||||
- Order number (clickable to details page)
|
||||
- Order date and status badge (Processing, Shipped, Delivered)
|
||||
- Total amount
|
||||
- First 2-3 product thumbnails
|
||||
- Quick actions: Track, View Details, Reorder, Invoice
|
||||
|
||||
**Status indicators (color-coded):**
|
||||
- Processing: Yellow/Orange
|
||||
- Shipped: Blue
|
||||
- Delivered: Green
|
||||
- Cancelled: Gray/Red
|
||||
|
||||
**Filtering and search:**
|
||||
- Date range (Last 30 days, Last 6 months, All time)
|
||||
- Status filter (All, Processing, Shipped, Delivered)
|
||||
- Search by order number or product name
|
||||
|
||||
**Sorting:**
|
||||
- Most recent first (default)
|
||||
- Oldest first
|
||||
- Highest/lowest price
|
||||
|
||||
**Pagination:**
|
||||
Show 10-20 orders per page with pagination controls. Alternative: "Load More" button (better mobile UX).
|
||||
|
||||
### Order Details View
|
||||
|
||||
Full order information page.
|
||||
|
||||
**Display:**
|
||||
- Order number, date, status with progress timeline
|
||||
- Tracking number with carrier link (if shipped)
|
||||
- Estimated delivery date
|
||||
|
||||
**Status timeline (builds trust):**
|
||||
```
|
||||
✓ Order Placed (Jan 27, 9:45 AM)
|
||||
✓ Processing (Jan 27, 10:30 AM)
|
||||
✓ Shipped (Jan 28, 2:15 PM)
|
||||
○ Out for Delivery
|
||||
○ Delivered
|
||||
```
|
||||
|
||||
**Order information:**
|
||||
- Items ordered (image, name, variant, quantity, price)
|
||||
- Pricing breakdown (subtotal, shipping, tax, discounts, total)
|
||||
- Shipping address and method
|
||||
- Billing address
|
||||
- Payment method (last 4 digits)
|
||||
|
||||
**Order actions:**
|
||||
- Track shipment (link to carrier tracking page)
|
||||
- Download invoice/receipt (PDF)
|
||||
- Request return (if eligible and backend supports)
|
||||
- Reorder items
|
||||
- Contact support about order
|
||||
|
||||
### Reorder Functionality (Ecommerce-Specific)
|
||||
|
||||
**Purpose**: Increase repeat purchases by making it easy to reorder past purchases.
|
||||
|
||||
**Implementation:**
|
||||
- "Reorder" button on order cards and order details
|
||||
- Check stock availability before adding to cart
|
||||
- Handle discontinued products gracefully (skip or notify)
|
||||
- Add all available items to cart
|
||||
- Success message: "5 items added to cart" (or "3 of 5 items added - 2 unavailable")
|
||||
- Stay on current page (don't navigate away)
|
||||
|
||||
**Tradeoff**: Auto-add to cart (friction-free) vs redirect to cart page (let user review first). Recommend auto-add with clear success feedback.
|
||||
|
||||
## Saved Addresses
|
||||
|
||||
**Purpose (CRITICAL)**: Reduce checkout friction and increase conversion. Saved addresses make repeat purchases faster and easier.
|
||||
|
||||
### Why Addresses Matter
|
||||
|
||||
**Conversion optimization:**
|
||||
- Saved addresses reduce checkout time by 50%+ (no retyping)
|
||||
- Default address selection streamlines checkout flow
|
||||
- Reduces form abandonment (fewer fields to fill)
|
||||
- Increases repeat purchase rate (easier checkout)
|
||||
|
||||
**Backend integration:**
|
||||
Fetch, create, update, and delete addresses via backend API. Do this based on backend integrated.
|
||||
|
||||
### Address Book Display
|
||||
|
||||
**Saved addresses list:**
|
||||
- All saved addresses
|
||||
- Default address indicator (badge: "Default Shipping" or star icon)
|
||||
- Address preview: Name, street, city, state, zip
|
||||
- Quick actions: Edit, Delete, Set as Default
|
||||
|
||||
**Default address behavior:**
|
||||
- One default shipping address
|
||||
- One default billing address (separate or same)
|
||||
- Used automatically at checkout (user can change)
|
||||
- Setting new default updates previous default
|
||||
|
||||
### Add/Edit Address Form
|
||||
|
||||
Collect standard shipping information. Key considerations:
|
||||
|
||||
**Required fields:**
|
||||
- Full name (or first + last)
|
||||
- Address line 1
|
||||
- City, State/Province, ZIP/Postal code
|
||||
- Country
|
||||
- Phone number (recommended for delivery coordination)
|
||||
|
||||
**Optional enhancements:**
|
||||
- Address label (Home, Work) for easy identification
|
||||
- Address autocomplete API (Google Places) for accuracy
|
||||
- "Set as default" checkbox
|
||||
|
||||
**Validation:**
|
||||
Real-time validation, especially for ZIP/postal code format based on country.
|
||||
|
||||
## Payment Methods
|
||||
|
||||
**Note**: Payment method storage is optional. Only implement if:
|
||||
- Backend securely handles tokenized payment data
|
||||
- PCI DSS compliance requirements are met
|
||||
- Payment gateway supports tokenization (Stripe, Braintree)
|
||||
|
||||
**Security (CRITICAL):**
|
||||
- Never store full card numbers (tokenize with payment gateway)
|
||||
- Display last 4 digits only
|
||||
- Don't store CVV
|
||||
- Use payment gateway hosted forms (Stripe Elements, etc.)
|
||||
- Show "Securely stored" badge for trust
|
||||
|
||||
**Saved payment display:**
|
||||
- Card type logo (Visa, Mastercard)
|
||||
- Last 4 digits
|
||||
- Expiration date
|
||||
- Default indicator
|
||||
- Actions: Edit (update expiration/billing address), Delete, Set as Default
|
||||
|
||||
**Tradeoff**: Saved payment methods increase convenience but require PCI compliance. If not implemented, users enter payment at checkout each time (more friction but simpler backend).
|
||||
|
||||
## Profile and Security
|
||||
|
||||
### Profile Information
|
||||
|
||||
Display and edit customer information.
|
||||
|
||||
**Standard fields:**
|
||||
- Full name
|
||||
- Email (with verification status)
|
||||
- Phone number
|
||||
- Optional: Date of birth, gender
|
||||
|
||||
**Edit functionality:**
|
||||
Inline editing or separate form, real-time validation, success confirmation.
|
||||
|
||||
**Email verification:**
|
||||
If unverified, show warning with "Resend verification email" button. If verified, show checkmark badge.
|
||||
|
||||
### Security Settings
|
||||
|
||||
**Password change:**
|
||||
- Require current password (optional)
|
||||
- New password with strength indicator
|
||||
- Confirm new password
|
||||
- Password requirements display (8+ chars, uppercase, number)
|
||||
|
||||
**Two-factor authentication (optional):**
|
||||
Enable/disable 2FA, setup instructions, backup codes. Only implement if backend supports.
|
||||
|
||||
## Email Preferences
|
||||
|
||||
Ecommerce-specific email controls.
|
||||
|
||||
**Preference categories:**
|
||||
|
||||
1. **Transactional emails** (order updates, shipping) - Recommended always enabled, may be legally required
|
||||
2. **Marketing emails** (sales, promotions, new products) - User choice
|
||||
3. **Newsletter** (weekly roundup, content) - User choice
|
||||
|
||||
**Display:**
|
||||
Checkbox list or toggle switches with clear descriptions. Save button at bottom.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Email Preferences
|
||||
|
||||
[✓] Order and shipping updates
|
||||
Receive confirmations and tracking info
|
||||
|
||||
[ ] Marketing emails
|
||||
Sales, promotions, and new products
|
||||
|
||||
[ ] Newsletter
|
||||
Weekly roundup and articles
|
||||
|
||||
[Save Preferences]
|
||||
```
|
||||
|
||||
**Unsubscribe:**
|
||||
Individual opt-outs per type, "Unsubscribe from all marketing" button. Keep transactional emails enabled (required for order fulfillment).
|
||||
|
||||
## Navigation and Layout
|
||||
|
||||
### Layout Pattern Decision
|
||||
|
||||
Choose based on account complexity:
|
||||
|
||||
**Sidebar Navigation (Recommended):**
|
||||
- **Use when**: 6+ account sections, complex account features
|
||||
- Desktop: Vertical sidebar (20-25% width) with section links
|
||||
- Mobile: Collapse to hamburger menu or dropdown
|
||||
- Benefits: Persistent navigation, professional, accommodates many sections
|
||||
|
||||
**Tab Navigation:**
|
||||
- **Use when**: 4-6 account sections, simpler account structure
|
||||
- Horizontal tabs at top, active tab highlighted
|
||||
- Mobile: Horizontal scroll or dropdown
|
||||
- Benefits: Modern, clean, quick switching
|
||||
|
||||
**Account Hub (Mobile-First):**
|
||||
- **Use when**: Mobile-heavy traffic, simple account
|
||||
- Landing page with section cards (2-column grid)
|
||||
- Tap card to enter section, back button returns to hub
|
||||
- Benefits: Touch-friendly, intuitive, minimal hierarchy
|
||||
|
||||
### Section Organization
|
||||
|
||||
**Recommended order (most to least used):**
|
||||
1. Dashboard (landing page)
|
||||
2. Orders (most accessed)
|
||||
3. Addresses (important for checkout)
|
||||
4. Payment Methods (if implemented)
|
||||
5. Profile
|
||||
6. Security
|
||||
7. Email Preferences
|
||||
8. Logout
|
||||
|
||||
## Mobile Considerations
|
||||
|
||||
**Mobile-specific patterns:**
|
||||
|
||||
**Navigation:**
|
||||
Account hub with section cards (2 columns), or bottom navigation with 4-5 key sections (Orders, Addresses, Profile, More).
|
||||
|
||||
**Forms:**
|
||||
One field per row, larger inputs (48px height), appropriate keyboard types (email, phone, numeric), autofill enabled.
|
||||
|
||||
**Order history:**
|
||||
Simplified order cards, full-width buttons, "Load More" pagination (better than numbered pages on mobile).
|
||||
|
||||
**Saved addresses:**
|
||||
Stacked address cards, full-width, 48px touch targets for edit/delete.
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential features:**
|
||||
|
||||
- [ ] Account dashboard with recent orders (3-5)
|
||||
- [ ] Reorder button (adds items to cart, stays on page)
|
||||
- [ ] Order history with status indicators
|
||||
- [ ] Filter orders by date range and status
|
||||
- [ ] Search orders by number or product name
|
||||
- [ ] Order details page with tracking info
|
||||
- [ ] Status timeline (Order Placed → Processing → Shipped → Delivered)
|
||||
- [ ] Track shipment button (links to carrier)
|
||||
- [ ] Download invoice/receipt option
|
||||
- [ ] Saved addresses list with default indicator
|
||||
- [ ] Add/edit/delete addresses with validation
|
||||
- [ ] Set default address option
|
||||
- [ ] Profile information edit
|
||||
- [ ] Email verification status display
|
||||
- [ ] Password change with strength indicator
|
||||
- [ ] Current password required to change password
|
||||
- [ ] Email preferences (transactional vs marketing)
|
||||
- [ ] Account deletion option
|
||||
- [ ] Logout button clearly visible
|
||||
- [ ] Clear navigation between sections
|
||||
- [ ] Mobile-responsive (single column, 48px touch targets)
|
||||
- [ ] Backend integration (all data fetched from API)
|
||||
- [ ] Success confirmations after saves
|
||||
- [ ] Error handling with clear messages
|
||||
- [ ] Keyboard accessible
|
||||
- [ ] ARIA labels on navigation sections
|
||||
- [ ] Order status announcements for screen readers
|
||||
|
||||
**Optional features:**
|
||||
|
||||
- [ ] Saved payment methods (if PCI compliant backend)
|
||||
- [ ] Two-factor authentication
|
||||
- [ ] Wishlist integration
|
||||
- [ ] Loyalty points/rewards display
|
||||
- [ ] Returns management section
|
||||
- [ ] Address autocomplete API
|
||||
@@ -0,0 +1,316 @@
|
||||
# Cart Page
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Layout Patterns](#layout-patterns)
|
||||
- [Cart Items Display](#cart-items-display)
|
||||
- [Quantity Updates](#quantity-updates)
|
||||
- [Order Summary](#order-summary)
|
||||
- [Promo Code Input](#promo-code-input)
|
||||
- [Checkout Button](#checkout-button)
|
||||
- [Empty Cart State](#empty-cart-state)
|
||||
- [Backend Integration](#backend-integration)
|
||||
- [Mobile Cart](#mobile-cart)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
The cart page displays all items a customer has added to their shopping cart. Purpose: Review items, modify cart, apply promotions, proceed to checkout. Critical conversion point.
|
||||
|
||||
**⚠️ CRITICAL: Always display variant details (size, color, material, etc.) for each cart item, not just product titles.**
|
||||
|
||||
### Key Ecommerce Functions
|
||||
|
||||
- Review items before purchase (reduces buyer's remorse)
|
||||
- Update quantities or remove items (cart management)
|
||||
- Apply promotional codes (increase order value)
|
||||
- View pricing breakdown (transparency builds trust)
|
||||
- Proceed to checkout (conversion path)
|
||||
- Continue shopping if needed (reduce abandonment)
|
||||
|
||||
## Layout Patterns
|
||||
|
||||
### Two-Column Pattern (Desktop)
|
||||
|
||||
**Most common:**
|
||||
- Left column (60-70%): Cart items list
|
||||
- Right column (30-40%): Order summary (sticky)
|
||||
- Below items: Promo code input, continue shopping
|
||||
- Order summary stays visible during scroll
|
||||
|
||||
### Mobile Layout
|
||||
|
||||
Single column (stacked):
|
||||
- Cart items
|
||||
- Order summary
|
||||
- Promo code input
|
||||
- Checkout button (sticky at bottom)
|
||||
- Continue shopping
|
||||
|
||||
## Cart Items Display
|
||||
|
||||
### Cart Item Card
|
||||
|
||||
**CRITICAL: Always display variant details for each cart item.**
|
||||
|
||||
Products with variants (size, color, material, style, etc.) must show the selected variant options. Without this, customers can't confirm they have the correct items in their cart.
|
||||
|
||||
**Essential information per item:**
|
||||
- Product image (thumbnail, 80-120px desktop, 60-80px mobile)
|
||||
- Product title (linked to product page)
|
||||
- **Variant details (REQUIRED)**: Size, color, material, or other variant options selected
|
||||
- Format: "Size: Large, Color: Black" or "Large / Black"
|
||||
- Display below title, smaller gray text
|
||||
- Show ALL selected variant options
|
||||
- Unit price
|
||||
- Quantity selector
|
||||
- Line total (unit price × quantity)
|
||||
- Remove button (X icon)
|
||||
|
||||
**Layout:**
|
||||
Horizontal card (image left, details right), clear visual separation between items, adequate spacing (16-24px).
|
||||
|
||||
**Why variant details are critical:**
|
||||
- Customer confirmation before checkout
|
||||
- Prevents returns from wrong variant purchases
|
||||
- Allows easy correction if wrong variant in cart
|
||||
- Essential for clothing, shoes, configurable products
|
||||
|
||||
### Price Display
|
||||
|
||||
**Medusa pricing (CRITICAL):**
|
||||
Medusa stores prices as-is (not in cents). Display prices directly without dividing by 100. Example: If Medusa returns 49.99, display $49.99 (not $0.4999). Different from Stripe which stores prices in cents.
|
||||
|
||||
**Sale prices:**
|
||||
Show original price (strikethrough) and sale price prominently if on sale.
|
||||
|
||||
**Line total:**
|
||||
Total for item (price × quantity), bold or larger font, update dynamically when quantity changes.
|
||||
|
||||
## Quantity Updates
|
||||
|
||||
### Quantity Selector
|
||||
|
||||
Standard +/- buttons with number display:
|
||||
```
|
||||
[-] [2] [+]
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Min: 1 (can't go below, or remove item instead)
|
||||
- Max: Stock available or cart limit
|
||||
- Manual input allowed (type number)
|
||||
- Update on change (blur or button click)
|
||||
- Show loading state briefly
|
||||
- Update line total immediately
|
||||
|
||||
### Auto-Update (Recommended)
|
||||
|
||||
Changes apply immediately, no "Update Cart" button needed. Better UX, less friction. Show brief loading indicator. Update order summary automatically.
|
||||
|
||||
**Error handling:**
|
||||
"Only X available" if exceeds stock, reset to max available quantity, show error message near item.
|
||||
|
||||
## Order Summary
|
||||
|
||||
### Summary Card
|
||||
|
||||
Position: Right column on desktop (sticky), below cart items on mobile, fixed width (300-400px desktop).
|
||||
|
||||
### Price Breakdown
|
||||
|
||||
**Line items:**
|
||||
```
|
||||
Subtotal (3 items): $149.97
|
||||
Shipping: $9.99
|
||||
Tax: $12.00
|
||||
─────────────────────
|
||||
Total: $171.96
|
||||
```
|
||||
|
||||
**Subtotal:**
|
||||
Sum of all cart items with item count.
|
||||
|
||||
**Shipping:**
|
||||
Estimated shipping cost, or "Calculated at checkout" (if address needed), or "Free shipping" (if applicable). Show free shipping threshold progress (see promotions.md).
|
||||
|
||||
**Tax:**
|
||||
Estimated tax or "Calculated at checkout" (if address needed).
|
||||
|
||||
**Total:**
|
||||
Grand total (bold, larger font), most prominent number.
|
||||
|
||||
### Savings Display
|
||||
|
||||
If discounts applied:
|
||||
- Show total savings: "You saved $20.00" (green text)
|
||||
- Or: Discount line item in breakdown
|
||||
- Positive reinforcement
|
||||
|
||||
## Promo Code Input
|
||||
|
||||
### Input Field Design
|
||||
|
||||
**Layout:**
|
||||
Label ("Promo code" or "Discount code"), text input (200-280px desktop, full-width mobile), "Apply" button inline or stacked (mobile). Positioned below cart items or in order summary.
|
||||
|
||||
**Auto-uppercase:**
|
||||
On submit (codes usually uppercase).
|
||||
|
||||
**Expandable pattern (optional):**
|
||||
"Have a promo code?" link that expands to show input. Saves vertical space.
|
||||
|
||||
### Success and Error States
|
||||
|
||||
**Success:**
|
||||
- Green checkmark or success message: "Code applied: WELCOME10"
|
||||
- Discount shown in order summary: "Discount (WELCOME10) -$10.00"
|
||||
- Remove option: X icon or "Remove" link
|
||||
- Update cart total immediately
|
||||
|
||||
**Error:**
|
||||
- Red error message below input: "Invalid code", "Code expired", or "Minimum purchase not met"
|
||||
- Input remains visible for retry
|
||||
- Don't clear input field
|
||||
|
||||
**See also:** [promotions.md](../features/promotions.md) for detailed promo code patterns.
|
||||
|
||||
## Checkout Button
|
||||
|
||||
### Button Design
|
||||
|
||||
**Prominence:**
|
||||
Large, full-width button, brand primary color (high contrast), 48-56px height (easy to tap). Text: "Proceed to Checkout" or "Checkout". Icon optional (lock or arrow).
|
||||
|
||||
**Position:**
|
||||
Bottom of order summary (desktop), fixed at bottom of screen (mobile, optional), always visible during scroll.
|
||||
|
||||
**States:**
|
||||
Default enabled, hover with slight color change, loading with spinner, disabled if cart empty or error.
|
||||
|
||||
**Security Indicators (optional):**
|
||||
Lock icon with "Secure Checkout", payment badges (Visa, Mastercard, PayPal), "SSL Encrypted" message near button.
|
||||
|
||||
## Empty Cart State
|
||||
|
||||
### Display
|
||||
|
||||
When cart is empty:
|
||||
- Centered content
|
||||
- Icon or illustration (empty shopping bag)
|
||||
- Heading: "Your cart is empty"
|
||||
- Subtext: "Start adding items to your cart"
|
||||
- CTA button: "Continue Shopping" or "Browse Products"
|
||||
|
||||
**Additional elements:**
|
||||
- Link to popular categories
|
||||
- Recently viewed products (if available)
|
||||
- Bestsellers or featured products
|
||||
|
||||
## Backend Integration
|
||||
|
||||
### Data Source (CRITICAL)
|
||||
|
||||
**Fetch from ecommerce backend:**
|
||||
Cart stored in backend (persistent), fetch on page load, sync with backend on changes.
|
||||
|
||||
**When to fetch:**
|
||||
- Page load (initial cart data)
|
||||
- After adding/updating/removing items
|
||||
- After applying promo codes
|
||||
|
||||
### State Management
|
||||
|
||||
**Client-side cart state:**
|
||||
Store cart data in global state (React Context), keep cart ID in localStorage, update state after API responses, share cart state across components (page, popup, header badge).
|
||||
|
||||
**Cart ID persistence:**
|
||||
```javascript
|
||||
localStorage.setItem('cart_id', cartId)
|
||||
```
|
||||
|
||||
Send cart ID with every cart API request, create new cart if ID doesn't exist, clear cart ID on checkout completion.
|
||||
|
||||
### TanStack Query for Cart Data
|
||||
|
||||
**Recommended** for efficient caching and revalidation:
|
||||
|
||||
**Benefits:**
|
||||
Built-in caching with automatic revalidation, optimistic updates support, automatic refetching on focus/reconnect, loading and error states handled, query invalidation for cart updates.
|
||||
|
||||
**Configuration:**
|
||||
Use `useQuery` for fetching cart data, set `staleTime` to 30-60 seconds, use `queryClient.invalidateQueries(['cart'])` after updates.
|
||||
|
||||
**See also:** [connecting-to-backend.md](../connecting-to-backend.md) for detailed backend integration patterns.
|
||||
|
||||
### Medusa Integration
|
||||
|
||||
Use `@medusajs/medusa-js` SDK:
|
||||
- Cart endpoints: `/store/carts`, `/store/carts/{id}`
|
||||
- Add to cart: POST `/store/carts/{id}/line-items`
|
||||
- Update quantity: POST `/store/carts/{id}/line-items/{lineId}`
|
||||
- Remove item: DELETE `/store/carts/{id}/line-items/{lineId}`
|
||||
- Apply discount: POST `/store/carts/{id}/promotions`
|
||||
|
||||
**Response data:**
|
||||
Cart ID, items (product details, variants, quantities), subtotal, tax, shipping, total, applied discounts, item availability status.
|
||||
|
||||
**Error handling:**
|
||||
Network errors (show retry option), invalid cart ID (create new cart), out of stock (show error, prevent adding), API errors (user-friendly message).
|
||||
|
||||
## Mobile Cart
|
||||
|
||||
### Mobile Layout
|
||||
|
||||
**Structure:**
|
||||
Full-width cart items (stacked), simplified item cards, order summary below items, sticky checkout button at bottom.
|
||||
|
||||
**Cart item cards:**
|
||||
Smaller product images (60-80px), truncated product titles (1-2 lines), essential info only, quantity selector (smaller, 36-40px), remove button visible.
|
||||
|
||||
### Sticky Checkout Bar
|
||||
|
||||
**Bottom sticky bar:**
|
||||
Fixed at bottom of screen, total amount visible, "Checkout" button (full-width), appears after scrolling (optional), always accessible.
|
||||
|
||||
**Design:**
|
||||
```
|
||||
[Total: $171.96] [Checkout]
|
||||
```
|
||||
|
||||
**Touch-friendly:**
|
||||
44px minimum touch targets, adequate spacing between buttons, large remove buttons (40px).
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential elements:**
|
||||
|
||||
- [ ] **CRITICAL: Cart items display variant details (size, color, etc.) - not just product title**
|
||||
- [ ] Cart items with images, titles, variant options, prices
|
||||
- [ ] Quantity selector (+/- buttons, 40-44px minimum)
|
||||
- [ ] Remove button per item (X icon, clearly visible)
|
||||
- [ ] Order summary (subtotal, shipping, tax, total)
|
||||
- [ ] Promo code input with "Apply" button
|
||||
- [ ] Applied discount displayed in summary
|
||||
- [ ] "Remove" option for applied code
|
||||
- [ ] Prominent "Checkout" button (48-56px height)
|
||||
- [ ] Continue shopping link
|
||||
- [ ] Empty cart state (icon, message, CTA)
|
||||
- [ ] Trust signals (secure checkout, payment badges)
|
||||
- [ ] Auto-update quantities (no "Update Cart" button)
|
||||
- [ ] Undo option after removing item (toast notification)
|
||||
- [ ] Mobile: Sticky checkout button at bottom
|
||||
- [ ] Mobile: Simplified cart item cards
|
||||
- [ ] Backend integration (fetch cart from API)
|
||||
- [ ] Cart ID persistence (localStorage)
|
||||
- [ ] Real-time price updates
|
||||
- [ ] Loading states (skeleton or spinner)
|
||||
- [ ] Optimistic updates for quantity changes
|
||||
- [ ] Stock availability warnings (if low stock)
|
||||
- [ ] Free shipping threshold progress (if applicable)
|
||||
- [ ] Keyboard accessible (Tab, Enter, Arrow keys)
|
||||
- [ ] ARIA labels on quantity controls and buttons
|
||||
- [ ] Screen reader announcements (aria-live)
|
||||
- [ ] High contrast text (4.5:1 minimum)
|
||||
- [ ] Error handling for failed updates
|
||||
@@ -0,0 +1,486 @@
|
||||
# Checkout Page Layout
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Decision: Single-Page vs Multi-Step](#decision-single-page-vs-multi-step)
|
||||
- [Guest vs Logged-In Checkout](#guest-vs-logged-in-checkout)
|
||||
- [Component Architecture](#component-architecture-recommended)
|
||||
- [Checkout Flow](#checkout-flow)
|
||||
- [Key Ecommerce Considerations](#key-ecommerce-considerations)
|
||||
- [Backend Integration](#backend-integration)
|
||||
- [Mobile Checkout](#mobile-checkout)
|
||||
- [Trust and Conversion Optimization](#trust-and-conversion-optimization)
|
||||
- [Error Handling](#error-handling)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
Final step in conversion funnel where customers provide shipping and payment information. Must be optimized for completion with minimal friction.
|
||||
|
||||
**⚠️ CRITICAL: Always fetch shipping methods AND payment methods from backend. Users must be able to select from available options - never skip payment method selection.**
|
||||
|
||||
### Key Requirements
|
||||
|
||||
- Clear steps and progress indication
|
||||
- Guest checkout option (if backend supports it)
|
||||
- Shipping address and method selection
|
||||
- **Shipping methods fetched from backend (vary by address/region)**
|
||||
- **Payment methods fetched from backend (user must select preferred method)**
|
||||
- Payment processing
|
||||
- Order review before submission
|
||||
- Trust signals throughout
|
||||
- Mobile-optimized (60%+ traffic is mobile)
|
||||
- Fast loading and submission
|
||||
|
||||
## Decision: Single-Page vs Multi-Step
|
||||
|
||||
**Use Single-Page Checkout when:**
|
||||
- Simple products with few shipping options
|
||||
- Mobile-heavy traffic (>60% mobile users)
|
||||
- Fewer form fields required (<15 total)
|
||||
- Startup or new store (minimize friction)
|
||||
- Fast checkout is prioritized
|
||||
- Low average order value (<$50)
|
||||
|
||||
**Benefits:**
|
||||
- Fewer clicks (no step navigation)
|
||||
- User sees full scope upfront
|
||||
- Faster on mobile (no page loads)
|
||||
- Lower perceived friction
|
||||
|
||||
**Use Multi-Step Checkout when:**
|
||||
- Complex shipping (international, multiple carriers)
|
||||
- B2B customers (need detailed information)
|
||||
- Many form fields required (>15 total)
|
||||
- High-value products (>$100, thoroughness expected)
|
||||
- Established brand (customers trust process)
|
||||
- Need clear progress indication
|
||||
|
||||
**Benefits:**
|
||||
- Less overwhelming (one step at a time)
|
||||
- Progress indicator reduces anxiety
|
||||
- Easier step-by-step validation
|
||||
- Better for complex forms
|
||||
|
||||
**Recommended: Hybrid Approach**
|
||||
- Single-page scroll layout on desktop
|
||||
- Accordion-based sections on mobile (expand/collapse)
|
||||
- Progressive disclosure of sections
|
||||
- Best of both worlds
|
||||
|
||||
**Common steps:**
|
||||
1. Shipping Information (address)
|
||||
2. Delivery (shipping method selection)
|
||||
3. Payment (payment method and details)
|
||||
4. Review (final review before submission)
|
||||
|
||||
## Guest vs Logged-In Checkout
|
||||
|
||||
**IMPORTANT:** Guest checkout availability depends on backend support.
|
||||
|
||||
**Guest checkout (recommended if backend supports it):**
|
||||
- Reduces friction (no signup barrier)
|
||||
- "Checkout as Guest" option prominent
|
||||
- Email required for order confirmation
|
||||
- Optional "Create account?" checkbox after order
|
||||
- Don't force account creation
|
||||
|
||||
**Logged-in checkout:**
|
||||
- Pre-fill saved addresses and payment methods
|
||||
- "Returning customer? Log in" link at top
|
||||
- Allow seamless switch between guest/login
|
||||
|
||||
## Component Architecture (RECOMMENDED)
|
||||
|
||||
**Build separate components for each checkout step for better maintainability and reusability.**
|
||||
|
||||
✅ **Create individual step components:**
|
||||
- `ShippingInformationStep` - Contact and shipping address form
|
||||
- `DeliveryMethodStep` - Shipping method selection
|
||||
- `PaymentInformationStep` - Payment method and details
|
||||
- `OrderReviewStep` - Final review before submission
|
||||
|
||||
**Benefits of component separation:**
|
||||
- **Maintainability**: Fix bugs or update one step without affecting others
|
||||
- **Reusability**: Reuse shipping address component in account settings, checkout, etc.
|
||||
- **Testability**: Test each step independently
|
||||
- **Code organization**: Clearer separation of concerns (validation, submission logic per step)
|
||||
- **Easier debugging**: Isolate issues to specific steps
|
||||
- **Flexibility**: Easy to reorder steps or add/remove steps based on requirements
|
||||
- **Performance**: Lazy load steps or split bundles for faster initial load
|
||||
|
||||
**What to separate:**
|
||||
- Main checkout page/container component
|
||||
- Individual step components (ShippingInformationStep, DeliveryMethodStep, etc.)
|
||||
- Reusable order summary component (shown on all steps)
|
||||
|
||||
**Component communication:**
|
||||
Each step component should accept:
|
||||
- Current step data (form values)
|
||||
- Callback to update data (e.g., `onShippingUpdate`)
|
||||
- Callback to proceed to next step (e.g., `onContinue`)
|
||||
- Loading/error states
|
||||
- Validation errors
|
||||
|
||||
**Shared components:**
|
||||
- Address form (used in shipping and billing)
|
||||
- Payment method selector
|
||||
- Order summary (sidebar, shown on all steps)
|
||||
|
||||
**Works for both single-page and multi-step:**
|
||||
- Single-page: Render all steps at once, scroll-based navigation
|
||||
- Multi-step: Show one component at a time, controlled by step state
|
||||
- Accordion: Expand/collapse components as sections
|
||||
|
||||
**Common mistake:**
|
||||
- ❌ Building entire checkout as one massive component with all form fields, logic, and validation mixed together
|
||||
- ✅ Separate components for each step, shared state management in parent
|
||||
|
||||
## Checkout Flow
|
||||
|
||||
### Complete Checkout Flow Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ CHECKOUT PROCESS │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ Optional: Guest Checkout vs Login │
|
||||
│ • Guest: Enter email only │
|
||||
│ • Logged-in: Pre-fill saved data │
|
||||
└────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ STEP 1: Shipping Information │
|
||||
│ ├─ Contact: Email, Phone │
|
||||
│ ├─ Shipping Address: Name, Address, City, etc. │
|
||||
│ └─ Billing Address: □ Same as shipping / Different │
|
||||
└────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ STEP 2: Delivery │
|
||||
│ • Fetch shipping methods from backend │
|
||||
│ • Display: Standard, Express, Overnight │
|
||||
│ • Show: Cost + Delivery estimate │
|
||||
│ • Update order total │
|
||||
└────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ STEP 3: Payment Information │
|
||||
│ • Fetch payment methods from backend │
|
||||
│ • Options: Card, PayPal, Apple Pay, etc. │
|
||||
│ • Enter: Card details (tokenized) │
|
||||
│ • Use billing address from Step 1 │
|
||||
└────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ STEP 4: Order Review │
|
||||
│ • Review: Items, addresses, shipping, payment │
|
||||
│ • Optional: □ Agree to Terms and Conditions │
|
||||
│ • Click: [Place Order] Button │
|
||||
│ → Payment processing triggered │
|
||||
└────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ Loading: Processing payment... │
|
||||
│ • Authorize/capture payment via gateway │
|
||||
│ • Create order in backend │
|
||||
│ • Send confirmation email │
|
||||
└────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
┌────┴────┐
|
||||
│ │
|
||||
Success Failure
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────────────┐ ┌──────────────────────┐
|
||||
│ Order Confirmation│ │ Show Error Message │
|
||||
│ • Order number │ │ • Retry payment │
|
||||
│ • Details │ │ • Keep form data │
|
||||
│ • Tracking link │ │ • Suggest solutions │
|
||||
└───────────────────┘ └──────────────────────┘
|
||||
```
|
||||
|
||||
## Key Ecommerce Considerations
|
||||
|
||||
### Shipping Address Collection
|
||||
|
||||
Collect:
|
||||
- Required: email, name, address, city, state/zip, country
|
||||
- Optional: phone.
|
||||
|
||||
**Key ecommerce considerations:**
|
||||
- Email placement: First if guest checkout (identifies customer)
|
||||
- Country placement: Early if shipping methods vary by country (affects available shipping)
|
||||
- Phone: Optional to reduce friction, but recommended for delivery coordination
|
||||
- Billing address: "Same as shipping" checkbox (default checked)
|
||||
|
||||
**For Medusa backends:**
|
||||
- Country dropdown: Show only countries from cart's region (don't show all countries globally)
|
||||
- Get countries from: `cart.region.countries` or `sdk.store.region.retrieve(cart.region_id)`
|
||||
- Medusa regions contain specific countries - limiting options ensures correct pricing and shipping
|
||||
- If user needs different country, they must change region first (typically via country selector component)
|
||||
|
||||
### Shipping Method Selection
|
||||
|
||||
**Fetch from backend after address provided** (shipping methods vary by address/region):
|
||||
- Display as radio buttons with cost + delivery estimate
|
||||
- Update order total immediately when method changes
|
||||
- Highlight free shipping if available
|
||||
- Show "Add $X for free shipping" if close to threshold
|
||||
- Handle unavailable shipping: show message, suggest alternatives
|
||||
|
||||
### Payment Method Selection
|
||||
|
||||
**CRITICAL: Always fetch payment methods from backend and allow user to select from available options.**
|
||||
|
||||
Payment methods vary by store configuration (backend settings). NEVER assume which payment methods are available or hardcode payment options. Users MUST be able to choose their preferred payment method.
|
||||
|
||||
**Fetch available methods from backend:**
|
||||
```typescript
|
||||
// ALWAYS fetch payment providers from backend
|
||||
// For Medusa:
|
||||
const { payment_providers } = await sdk.store.payment.listPaymentProviders()
|
||||
|
||||
// For other backends:
|
||||
// Change based on the integrated backend
|
||||
const paymentMethods = await fetch(`${apiUrl}/payment-methods`)
|
||||
// Returns: card, paypal, apple_pay, google_pay, stripe, etc.
|
||||
```
|
||||
|
||||
**Display payment method selection UI:**
|
||||
- Show all enabled payment providers returned by backend
|
||||
- Allow user to select their preferred method (radio buttons or cards)
|
||||
- Don't skip selection step - user must actively choose
|
||||
- Map backend codes to display names in the storefront. For example `pp_system_manual` -> `Manual payment`.
|
||||
- Common options: Credit/Debit Card, PayPal, Apple Pay, Google Pay, Buy Now Pay Later
|
||||
|
||||
**Available payment methods (examples, actual options come from backend):**
|
||||
- Credit/Debit Card (most common, via Stripe/Braintree/other gateway)
|
||||
- PayPal (redirect or in-context)
|
||||
- Apple Pay (Safari, iOS only)
|
||||
- Google Pay (Chrome, Android)
|
||||
- Buy Now Pay Later (Affirm, Klarna - if enabled by store)
|
||||
- Manual payment (bank transfer, cash on delivery - if enabled)
|
||||
|
||||
**Why backend fetching is required:**
|
||||
- Store admin controls which payment providers are enabled
|
||||
- Payment methods vary by region, currency, order value
|
||||
- Test vs production mode affects available methods
|
||||
- Can't assume all stores use the same payment gateway
|
||||
|
||||
**For Medusa backends - Payment flow:**
|
||||
|
||||
1. **List available payment providers:**
|
||||
```typescript
|
||||
const { payment_providers } = await sdk.store.payment.listPaymentProviders({
|
||||
region_id: cart.region_id // Required to get region-specific providers
|
||||
})
|
||||
```
|
||||
|
||||
2. **Display providers and allow user to select:**
|
||||
Show payment providers as radio buttons or cards. User must actively select one.
|
||||
|
||||
3. **Initialize payment session after selection:**
|
||||
```typescript
|
||||
// When user selects a provider
|
||||
await sdk.store.payment.initiatePaymentSession(cart, {
|
||||
provider_id: selectedProvider.id // e.g., "pp_stripe_stripe", "pp_system_default"
|
||||
})
|
||||
|
||||
// Re-fetch cart to get updated payment session data
|
||||
const { cart: updatedCart } = await sdk.store.cart.retrieve(cart.id)
|
||||
```
|
||||
|
||||
4. **Render provider-specific UI:**
|
||||
- Stripe providers (`pp_stripe_*`): Render Stripe Elements card UI
|
||||
- Manual payment (`pp_system_default`): No additional UI needed
|
||||
- Other providers: Implement according to provider requirements
|
||||
|
||||
**Important:** Payment provider IDs are returned from the backend (e.g., `pp_stripe_stripe`, `pp_system_manual`). Map these to user-friendly display names in your UI.
|
||||
|
||||
**Digital wallets (mobile priority):**
|
||||
- Apple Pay / Google Pay should be prominent on mobile
|
||||
- One-click payment (pre-filled shipping)
|
||||
- Significantly faster checkout
|
||||
- Higher conversion on mobile
|
||||
|
||||
**Card payment:**
|
||||
- Use payment gateway (Stripe Elements, Braintree)
|
||||
- Never handle raw card data (PCI compliance)
|
||||
- Tokenize card data before submission
|
||||
- Auto-detect card type (show logo)
|
||||
|
||||
### Order Review
|
||||
|
||||
**Display for final confirmation:**
|
||||
Cart items, addresses, shipping method/cost, payment method, order total breakdown.
|
||||
|
||||
**Key elements:**
|
||||
- "Edit" link next to each section (returns to step or edits inline)
|
||||
- Terms checkbox (if required): "I agree to Terms and Conditions"
|
||||
- Place Order button: Large (48-56px), shows total, loading state on submit
|
||||
|
||||
### Order Summary Sidebar
|
||||
|
||||
**Desktop:** Sticky sidebar with items, prices, totals. Updates in real-time.
|
||||
**Mobile:** Collapsible at top ("Show order summary" toggle). Keeps focus on form.
|
||||
|
||||
## Backend Integration
|
||||
|
||||
**Address validation (optional):**
|
||||
- Use address lookup APIs (Google, SmartyStreets) for higher accuracy
|
||||
- Tradeoff: accuracy vs friction. Consider for high-value orders.
|
||||
|
||||
**Payment processing flow:**
|
||||
1. Frontend tokenizes payment (Stripe Elements, Braintree)
|
||||
2. Send token + order details to backend
|
||||
3. Backend authorizes/captures payment & creates order
|
||||
4. Redirect to confirmation page
|
||||
|
||||
**Never:** Send raw card data, store cards without PCI compliance, process payments client-side.
|
||||
|
||||
**On payment failure:** Show specific error, keep form data, allow retry without re-entering.
|
||||
|
||||
### Order Completion and Cart Cleanup (CRITICAL)
|
||||
|
||||
**After order is successfully placed, you MUST reset the cart state:**
|
||||
|
||||
**Common issue:** Cart popup and cart state still show old cart content after order is placed. This happens because the global cart state (Context, Zustand, Redux) isn't cleared after checkout completion.
|
||||
|
||||
**Required actions on successful order:**
|
||||
|
||||
1. **Clear cart from global state:**
|
||||
- Reset cart state in Context/Zustand/Redux to null or empty
|
||||
- Update cart count to 0 in navbar
|
||||
- Prevent old cart items from showing in cart popup
|
||||
|
||||
2. **Clear localStorage cart ID:**
|
||||
- Remove cart ID from localStorage: `localStorage.removeItem('cart_id')`
|
||||
- Or create new cart and update cart ID in localStorage
|
||||
- Ensures fresh cart for next shopping session
|
||||
|
||||
3. **Invalidate cart queries (if using TanStack Query):**
|
||||
- `queryClient.invalidateQueries({ queryKey: ['cart'] })`
|
||||
- Or `queryClient.removeQueries({ queryKey: ['cart', cartId] })`
|
||||
- Prevents stale cart data from cache
|
||||
|
||||
4. **Redirect to order confirmation page:**
|
||||
- Navigate to `/order-confirmation/[order_id]` or `/thank-you/[order_id]`
|
||||
- Show order details, tracking info, confirmation
|
||||
|
||||
**Pattern:**
|
||||
```typescript
|
||||
// After successful order placement
|
||||
async function onOrderSuccess(order) {
|
||||
// 1. Clear cart state
|
||||
setCart(null) // or clearCart() from context
|
||||
|
||||
// 2. Clear localStorage
|
||||
localStorage.removeItem('cart_id')
|
||||
|
||||
// 3. Invalidate queries (if using TanStack Query)
|
||||
queryClient.invalidateQueries({ queryKey: ['cart'] })
|
||||
|
||||
// 4. Redirect to confirmation
|
||||
router.push(`/order-confirmation/${order.id}`)
|
||||
}
|
||||
```
|
||||
|
||||
**Why this is critical:**
|
||||
- Without clearing cart state, cart popup shows old items after order
|
||||
- User sees "phantom cart" if they click cart icon after checkout
|
||||
- Creates confusion and poor UX
|
||||
- May prevent user from starting new shopping session
|
||||
|
||||
## Mobile Checkout
|
||||
|
||||
**Key optimizations:**
|
||||
- Digital wallets prominent (Apple Pay/Google Pay) - significantly faster checkout
|
||||
- Single-column layout, 44-48px touch targets
|
||||
- Appropriate keyboard types, autocomplete attributes enabled
|
||||
- Collapsible order summary at top (shows total, expands on tap)
|
||||
- Sticky Place Order button at bottom (always accessible, shows total)
|
||||
- Accordion sections (one step at a time, reduces cognitive load)
|
||||
|
||||
**For detailed mobile patterns and safe area insets**, see `reference/mobile-responsiveness.md`.
|
||||
|
||||
## Trust and Conversion Optimization
|
||||
|
||||
**Trust signals (critical for conversion):**
|
||||
- "Secure Checkout" badge, payment provider logos (Visa, Mastercard)
|
||||
- Return policy link visible, customer support contact
|
||||
- Near Place Order: "100% secure checkout", guarantees/free returns if offered
|
||||
- For new brands: Customer review count, social proof
|
||||
|
||||
**Reduce abandonment:**
|
||||
- Progress indicator (shows steps remaining)
|
||||
- Auto-save form data, clear pricing (no surprise fees)
|
||||
- Minimal required fields, smart defaults, autocomplete enabled
|
||||
|
||||
**Reduce perceived friction:**
|
||||
- "No account required" (guest checkout)
|
||||
- "Free shipping" highlighted
|
||||
- Time estimate: "Less than 2 minutes"
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Form validation:**
|
||||
- Validate on blur, show error below field
|
||||
- User-friendly messages ("Please enter a valid email address")
|
||||
- Scroll to first error on submit
|
||||
|
||||
**Payment errors:**
|
||||
- Card declined: "Your card was declined. Please try another payment method."
|
||||
- Keep form data, suggest alternatives (try another card, PayPal)
|
||||
- Network timeout: Show retry option without re-entering data
|
||||
|
||||
**Stock availability errors:**
|
||||
- Out of stock: Remove item, recalculate, allow continue with remaining items
|
||||
- Quantity reduced: Update automatically, show message, allow continue
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential checkout features:**
|
||||
|
||||
- [ ] **RECOMMENDED: Separate components created for each checkout step**
|
||||
- [ ] Components: ShippingInformationStep, DeliveryMethodStep, PaymentInformationStep, OrderReviewStep
|
||||
- [ ] Decision made: Single-page or multi-step (based on complexity)
|
||||
- [ ] Guest checkout option (if backend supports it)
|
||||
- [ ] Email field first (if guest checkout)
|
||||
- [ ] Shipping address form with autocomplete attributes
|
||||
- [ ] "Billing same as shipping" checkbox (default checked)
|
||||
- [ ] Shipping methods fetched from backend dynamically
|
||||
- [ ] Shipping cost updates order total in real-time
|
||||
- [ ] **CRITICAL: Payment methods fetched from backend (NEVER assume or hardcode)**
|
||||
- [ ] **CRITICAL: Payment method selection UI shown to user (user must select from available options)**
|
||||
- [ ] Payment methods: show only enabled providers returned by backend
|
||||
- [ ] For Medusa: Payment session initialized after user selects provider (sdk.store.payment.initiatePaymentSession)
|
||||
- [ ] For Medusa: Country dropdown limited to cart's region countries
|
||||
- [ ] Digital wallets prominent on mobile (Apple Pay, Google Pay)
|
||||
- [ ] Payment tokenization (never send raw card data)
|
||||
- [ ] Order review section before submission
|
||||
- [ ] Order summary sidebar (sticky on desktop, collapsible on mobile)
|
||||
- [ ] Promo code input (if not applied in cart)
|
||||
- [ ] Trust signals throughout (secure checkout, return policy)
|
||||
- [ ] Terms and conditions checkbox (if required)
|
||||
- [ ] Place Order button prominent (48-56px, shows total)
|
||||
- [ ] Loading state during payment processing
|
||||
- [ ] Progress indicator (if multi-step)
|
||||
- [ ] Clear error messages for validation failures
|
||||
- [ ] Error handling for payment failures (keep form data)
|
||||
- [ ] Stock availability check before order creation
|
||||
- [ ] Mobile optimized (44-48px touch targets, single column)
|
||||
- [ ] Autocomplete enabled on all form fields
|
||||
- [ ] Keyboard accessible (tab through fields, enter to submit)
|
||||
- [ ] ARIA labels on form fields (aria-required, aria-invalid)
|
||||
- [ ] Redirect to order confirmation on success
|
||||
- [ ] **CRITICAL: Clear cart state after successful order** (reset cart in Context/Zustand, remove cart ID from localStorage, invalidate cart queries)
|
||||
- [ ] Cart popup shows empty cart after order completion (not old items)
|
||||
@@ -0,0 +1,264 @@
|
||||
# Homepage Layout
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Essential Homepage Sections](#essential-homepage-sections)
|
||||
- [Hero Section](#hero-section)
|
||||
- [Featured Categories](#featured-categories)
|
||||
- [Product Sections](#product-sections)
|
||||
- [Value Propositions](#value-propositions)
|
||||
- [Newsletter Signup](#newsletter-signup)
|
||||
- [Content Hierarchy](#content-hierarchy)
|
||||
- [Mobile Considerations](#mobile-considerations)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
The homepage is the primary landing page for an ecommerce store. Purpose: Strong first impression, guide users to products, communicate value, drive conversions.
|
||||
|
||||
**Backend Integration (CRITICAL):**
|
||||
|
||||
All content (categories, products, promotions) must be fetched from the ecommerce backend. Do this based on backend integrated. Never hardcode homepage content. Fetch featured products, bestsellers, new arrivals, and categories dynamically.
|
||||
|
||||
### Key Ecommerce Functions
|
||||
|
||||
- Create strong first impression (builds trust)
|
||||
- Guide users to products they want (reduce bounce rate)
|
||||
- Showcase featured products and promotions (increase conversion)
|
||||
- Communicate value propositions (free shipping, returns)
|
||||
- Capture email addresses (build marketing list)
|
||||
- Drive conversions and sales
|
||||
|
||||
## Essential Homepage Sections
|
||||
|
||||
### Must-Have Sections
|
||||
|
||||
**Critical for every homepage:**
|
||||
1. Hero section (above the fold)
|
||||
2. Category navigation (product discovery)
|
||||
3. Featured/bestselling products (social proof)
|
||||
4. Footer (contact, legal, navigation)
|
||||
|
||||
**Strongly recommended:**
|
||||
1. Value propositions (free shipping, returns, etc.)
|
||||
2. Social proof (reviews, testimonials, trust badges)
|
||||
3. New arrivals or sale section
|
||||
4. Newsletter signup
|
||||
|
||||
### Content Hierarchy Decision
|
||||
|
||||
**Above the fold (first screen):**
|
||||
- Hero section with main message
|
||||
- Primary call-to-action
|
||||
- Key value propositions (optional)
|
||||
|
||||
**Middle sections:**
|
||||
- Featured categories
|
||||
- Product sections (bestsellers, new arrivals, sale)
|
||||
- Promotional banners
|
||||
- Social proof
|
||||
|
||||
**Bottom sections:**
|
||||
- Newsletter signup
|
||||
- Footer
|
||||
|
||||
## Hero Section
|
||||
|
||||
Large banner at top of homepage, first thing users see (above the fold). Communicates main message or promotion.
|
||||
|
||||
**Content options:**
|
||||
- Seasonal campaign or sale
|
||||
- New product arrivals
|
||||
- Brand message or value proposition
|
||||
- Featured product category
|
||||
- Multiple rotating slides (carousel) - max 3-4 slides
|
||||
|
||||
**See also:** [hero.md](../components/hero.md) for detailed hero section guidelines including carousel patterns, mobile optimization, and performance.
|
||||
|
||||
## Featured Categories
|
||||
|
||||
### Purpose and Display
|
||||
|
||||
**Purpose**: Help users browse by category, reduce clicks to reach products, quick access to main product types.
|
||||
|
||||
**Category selection:**
|
||||
- 4-8 main categories
|
||||
- Most popular or seasonal categories
|
||||
- Balanced representation
|
||||
- **Fetch from backend dynamically** (never hardcode)
|
||||
|
||||
### Display Patterns
|
||||
|
||||
**Pattern 1: Category Grid with Images**
|
||||
3-6 category tiles with images, category name overlay, click to navigate. Equal-sized tiles in grid layout (3-4 columns desktop, 2 mobile).
|
||||
|
||||
**Pattern 2: Category Cards**
|
||||
Card layout with category image, name, and item count ("120 products"). "Shop [Category]" button on each card. 2-4 columns on desktop, 2 on mobile.
|
||||
|
||||
**Pattern 3: Category Slider**
|
||||
Horizontal scrollable categories showing 4-6 at once. Arrows for navigation. See [product-slider.md](../components/product-slider.md).
|
||||
|
||||
## Product Sections
|
||||
|
||||
### Bestsellers Section (CRITICAL)
|
||||
|
||||
**Purpose**: Showcase popular products, build social proof, guide uncertain shoppers.
|
||||
|
||||
**Product selection (backend-driven):**
|
||||
- Sort by total sales volume
|
||||
- Update regularly (weekly or monthly)
|
||||
- Mix of categories (not all one type)
|
||||
- Show 8-15 products
|
||||
|
||||
**Layout:**
|
||||
Product slider or grid, product cards with image, title, price, rating (if available). "View All" link to full bestsellers page.
|
||||
|
||||
### New Arrivals Section
|
||||
|
||||
**Purpose**: Highlight latest products, create sense of freshness, encourage repeat visits.
|
||||
|
||||
**Product selection:**
|
||||
- Most recently added products (last 30 days)
|
||||
- Sorted by newest first
|
||||
- Exclude out-of-stock items
|
||||
- Show 10-20 products
|
||||
|
||||
**Layout:**
|
||||
Product slider, optional "New" badge on products. "Shop New Arrivals" link.
|
||||
|
||||
### Sale/Promotional Products
|
||||
|
||||
**Purpose**: Drive urgency and conversions, clear excess inventory.
|
||||
|
||||
**Product selection:**
|
||||
- Products with active sale prices from backend
|
||||
- Sorted by discount percentage
|
||||
- Limited time or seasonal sales
|
||||
|
||||
**Display:**
|
||||
Product slider with sale badges, strikethrough pricing, optional countdown timer (if time-limited sale).
|
||||
|
||||
## Value Propositions
|
||||
|
||||
### Trust & Convenience Features
|
||||
|
||||
**Purpose**: Build trust quickly, address common concerns (shipping cost, returns), differentiate from competitors.
|
||||
|
||||
**Common value propositions:**
|
||||
- Free shipping (over threshold or always)
|
||||
- Free returns (30/60/90 days)
|
||||
- Secure checkout
|
||||
- Customer support (24/7, phone, chat)
|
||||
- Fast shipping (2-day, same-day)
|
||||
- Quality guarantee or warranty
|
||||
|
||||
### Display Pattern
|
||||
|
||||
**Icon Row (most common):**
|
||||
3-4 icons with text below hero section. Icon + short text (truck icon + "Free Shipping"). Single row, centered. 100-150px per item.
|
||||
|
||||
**Placement:**
|
||||
Below hero section (most common) or above footer.
|
||||
|
||||
## Newsletter Signup
|
||||
|
||||
### Email Capture Section
|
||||
|
||||
**⚠️ IMPORTANT: Check footer first - don't duplicate newsletter forms.**
|
||||
|
||||
If your footer already includes a newsletter signup form, **do NOT add another newsletter section on the homepage**. Two newsletter forms on the same page:
|
||||
- Creates confusion (which one to use?)
|
||||
- Looks unprofessional and repetitive
|
||||
- Reduces conversion (decision fatigue)
|
||||
- Wastes valuable homepage space
|
||||
|
||||
**Decision:**
|
||||
- Footer has newsletter? → Skip homepage newsletter section, use that space for other content
|
||||
- Footer doesn't have newsletter? → Add homepage newsletter section (recommended placement: mid-page)
|
||||
- Want both? → Only if they serve different purposes (e.g., footer = general newsletter, homepage = specific campaign/offer)
|
||||
|
||||
**Purpose**: Grow email list for marketing, offer incentive to build relationship.
|
||||
|
||||
**Design essentials:**
|
||||
- Heading: "Stay in the Loop", "Get 10% Off"
|
||||
- Subheading: Benefit of subscribing (don't just say "subscribe")
|
||||
- Email input field
|
||||
- Submit button
|
||||
- Privacy note (optional): "We respect your privacy"
|
||||
|
||||
**Incentive (CRITICAL):**
|
||||
- 10% off first order (most common)
|
||||
- Early access to sales
|
||||
- Exclusive content or products
|
||||
- Free shipping code
|
||||
|
||||
**Layout options:**
|
||||
- Full-width section (dedicated section, background color, centered)
|
||||
- Inline form (between sections, smaller)
|
||||
- Footer newsletter (part of footer) - see footer.md
|
||||
|
||||
**Placement:**
|
||||
Mid-page (after 2-3 sections) or above footer.
|
||||
|
||||
## Content Hierarchy
|
||||
|
||||
### Section Order Recommendation
|
||||
|
||||
**Typical homepage structure:**
|
||||
1. Hero section
|
||||
2. Value propositions (free shipping, returns)
|
||||
3. Featured categories
|
||||
4. Bestsellers or Featured Products
|
||||
5. Promotional banner (mid-page, optional)
|
||||
6. New Arrivals
|
||||
7. Newsletter signup (skip if footer already has newsletter form)
|
||||
8. Footer
|
||||
|
||||
### Visual Rhythm
|
||||
|
||||
**Vary section types:**
|
||||
Product section → Banner → Product section. Avoid monotony (all product sections in a row). Mix text-heavy and image-heavy sections.
|
||||
|
||||
**Spacing:**
|
||||
Generous padding between sections (64-120px desktop, 40-60px mobile). Consistent spacing. Section backgrounds to create separation.
|
||||
|
||||
## Mobile Considerations
|
||||
|
||||
**Responsive layout:**
|
||||
Single column for most sections, stack elements vertically, larger touch targets (44px minimum), simplified navigation.
|
||||
|
||||
**Product sections:**
|
||||
Horizontal sliders with swipe gestures, or stacked product grids (2 columns). Smaller product cards optimized for mobile.
|
||||
|
||||
**Hero section:**
|
||||
Portrait aspect ratio (2:3 or 3:4), vertical text placement (center/bottom). See [hero.md](../components/hero.md) for mobile hero details.
|
||||
|
||||
**Performance:**
|
||||
Lazy load below-fold images, optimize hero image (<200KB), use WebP format. Mobile-first approach.
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential elements:**
|
||||
|
||||
- [ ] Hero section with clear message and CTA
|
||||
- [ ] Featured categories (4-8 categories with images)
|
||||
- [ ] Categories fetched from backend dynamically
|
||||
- [ ] Bestsellers or Featured Products section
|
||||
- [ ] New Arrivals section
|
||||
- [ ] Value propositions (free shipping, returns, etc.)
|
||||
- [ ] Social proof (reviews, ratings, testimonials)
|
||||
- [ ] Newsletter signup form (only if footer doesn't have one - check footer first)
|
||||
- [ ] No duplicate newsletter forms (homepage + footer)
|
||||
- [ ] Footer with navigation and legal links
|
||||
- [ ] Mobile-responsive layout (single column, 44px touch targets)
|
||||
- [ ] Fast loading time (<3 seconds)
|
||||
- [ ] Optimized images (<200KB, WebP format)
|
||||
- [ ] Lazy loading for below-fold content
|
||||
- [ ] Backend integration (all content fetched from API)
|
||||
- [ ] Semantic HTML (main, section, h1, h2)
|
||||
- [ ] Proper heading hierarchy (h1 → h2 → h3)
|
||||
- [ ] Keyboard accessible
|
||||
- [ ] ARIA labels on sections
|
||||
- [ ] High contrast text (4.5:1 minimum)
|
||||
- [ ] Clear CTAs on every section
|
||||
@@ -0,0 +1,231 @@
|
||||
# Order Confirmation Page
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Essential Information](#essential-information)
|
||||
- [Order Details Display](#order-details-display)
|
||||
- [Next Steps Section](#next-steps-section)
|
||||
- [Layout Patterns](#layout-patterns)
|
||||
- [Call-to-Action Buttons](#call-to-action-buttons)
|
||||
- [Mobile Considerations](#mobile-considerations)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
The order confirmation page displays immediately after successful checkout. Purpose: Confirm purchase, provide order details, guide customers on next steps, build post-purchase confidence.
|
||||
|
||||
**Backend Integration:**
|
||||
|
||||
Fetch order details from backend API immediately after checkout completes. Do this based on backend integrated. Never hardcode or mock order data.
|
||||
|
||||
### Key Ecommerce Functions
|
||||
|
||||
- Confirm successful purchase (reduces anxiety)
|
||||
- Provide order reference number (for tracking and support)
|
||||
- Set delivery expectations (reduces "where's my order" inquiries)
|
||||
- Guide customer on next steps (reduces support load)
|
||||
- Encourage repeat purchases (continue shopping CTA)
|
||||
- Build post-purchase confidence (reduces buyer's remorse)
|
||||
|
||||
## Essential Information
|
||||
|
||||
### Success Message (CRITICAL)
|
||||
|
||||
**Confirmation headline:**
|
||||
Large, prominent heading, positive reassuring message, success icon (green checkmark), immediately visible above fold.
|
||||
|
||||
**Example messages:**
|
||||
- "Order Confirmed!"
|
||||
- "Thank you for your order!"
|
||||
- "Success! Your order is confirmed"
|
||||
|
||||
**Subheading:**
|
||||
Brief reassurance, email confirmation mention, delivery timeframe preview.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
✓ Order Confirmed!
|
||||
|
||||
Thank you for your purchase! We've sent a confirmation
|
||||
email to customer@example.com with your order details.
|
||||
```
|
||||
|
||||
### Order Number
|
||||
|
||||
**Display requirements:**
|
||||
- Very prominent
|
||||
- Clearly labeled "Order Number:" or "Order #"
|
||||
- Easy to select and copy (selectable text)
|
||||
- Monospace or sans-serif font
|
||||
- High contrast for visibility
|
||||
- Optional: Copy button next to number
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Order Number: #ORD-123456789
|
||||
```
|
||||
|
||||
### Email Confirmation Notice
|
||||
|
||||
Confirmation email was sent, email address used, check spam folder reminder (optional), resend email option (optional).
|
||||
|
||||
## Order Details Display
|
||||
|
||||
### Ordered Items List
|
||||
|
||||
Display per item:
|
||||
- Product image (thumbnail, 60-80px)
|
||||
- Product title (full name)
|
||||
- Variant information (size, color, etc.)
|
||||
- Quantity ("× 2")
|
||||
- Unit price
|
||||
- Line total (quantity × price)
|
||||
|
||||
### Order Summary (Pricing)
|
||||
|
||||
**Price breakdown:**
|
||||
- Subtotal (sum of items)
|
||||
- Shipping cost (with method name)
|
||||
- Tax (if applicable)
|
||||
- Discount/promo code (if used, show savings)
|
||||
- **Order Total** (bold, larger font)
|
||||
|
||||
**Medusa pricing note:**
|
||||
Medusa stores prices as-is (not in cents). Display prices directly without dividing by 100. Example: If backend returns 49.99, display $49.99.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Subtotal: $139.97
|
||||
Shipping (Express): $5.99
|
||||
Tax: $11.20
|
||||
Discount (SAVE10): -$14.00
|
||||
─────────────────────────────
|
||||
Order Total: $143.16
|
||||
```
|
||||
|
||||
### Shipping and Billing Information
|
||||
|
||||
**Shipping address:**
|
||||
Recipient name, complete address, phone number, shipping method selected, estimated delivery date.
|
||||
|
||||
**Billing address:**
|
||||
If same as shipping: "Same as shipping address". If different: Show full billing address.
|
||||
|
||||
**Payment information:**
|
||||
Payment method type, last 4 digits (if card), alternative methods (PayPal email, Apple Pay). **Never show full card number.**
|
||||
|
||||
## Next Steps Section
|
||||
|
||||
### What Happens Next (CRITICAL)
|
||||
|
||||
**Timeline guidance:**
|
||||
Order processing information, shipment timeline, when tracking becomes available, expected delivery date.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
What's Next?
|
||||
|
||||
1. Order Processing (1-2 business days)
|
||||
We're carefully preparing your items for shipment.
|
||||
|
||||
2. Shipment Notification
|
||||
You'll receive an email with tracking information
|
||||
when your order ships.
|
||||
|
||||
3. Delivery (By January 30)
|
||||
Your package will arrive at your address.
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
Sets clear expectations, reduces "where's my order" inquiries, builds confidence in process.
|
||||
|
||||
## Layout Patterns
|
||||
|
||||
### Single Column Layout (Recommended)
|
||||
|
||||
Full-width content, centered on page, all sections stacked vertically. Mobile-friendly by default.
|
||||
|
||||
**Section order:**
|
||||
1. Success message and order number
|
||||
2. Email confirmation notice
|
||||
3. Order items list
|
||||
4. Order summary (pricing)
|
||||
5. Shipping address
|
||||
6. Billing address
|
||||
7. Payment method
|
||||
8. Next steps/timeline
|
||||
9. CTAs (continue shopping, print, track)
|
||||
|
||||
### Two-Column Layout (Desktop Alternative)
|
||||
|
||||
- Left column (60-70%): Main content (success, order number, items, addresses, next steps)
|
||||
- Right column (30-40%): Sidebar (order summary, CTAs, tracking)
|
||||
- Mobile: Collapses to single column
|
||||
|
||||
## Call-to-Action Buttons
|
||||
|
||||
### Primary Actions
|
||||
|
||||
**Continue Shopping (MOST IMPORTANT):**
|
||||
Large, prominent button (primary color), returns to homepage or shop page. Text: "Continue Shopping" or "Back to Store". Encourages repeat visits.
|
||||
|
||||
### Secondary Actions
|
||||
|
||||
**Create Account (for guest orders):**
|
||||
Encourage account creation, pre-fill email from order, benefits messaging ("Track orders easily"). Optional, not required.
|
||||
|
||||
**Print Receipt:**
|
||||
Print-friendly CSS, button to print page.
|
||||
|
||||
**Contact Support:**
|
||||
Link to support page or contact form, phone number (if available), help with order questions.
|
||||
|
||||
**Button layout:**
|
||||
Primary action prominent (filled button), secondary actions less prominent (outline or link), adequate spacing (16-24px), mobile full-width.
|
||||
|
||||
## Mobile Considerations
|
||||
|
||||
**Single column only:**
|
||||
Full-width sections, generous padding (16-20px), larger text for important info, touch-friendly buttons.
|
||||
|
||||
**Order number:**
|
||||
Extra large (28-36px), highly visible, easy to read and reference, tap to copy (if implemented).
|
||||
|
||||
**Buttons:**
|
||||
Full-width or near full-width (min 90%), 48-56px height (touch-friendly), 16px spacing between buttons.
|
||||
|
||||
**Quick actions:**
|
||||
- Tap phone number to call support
|
||||
- Tap to copy order number
|
||||
- Add delivery date to calendar
|
||||
- Share order details
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential elements:**
|
||||
|
||||
- [ ] Large success message (32-48px heading)
|
||||
- [ ] Green checkmark or success icon
|
||||
- [ ] Prominent order number (24-32px, selectable)
|
||||
- [ ] Email confirmation notice
|
||||
- [ ] Order items list with images
|
||||
- [ ] Item details (title, variant, quantity, price)
|
||||
- [ ] Order summary (subtotal, shipping, tax, total)
|
||||
- [ ] Shipping address displayed
|
||||
- [ ] Billing address (or "same as shipping")
|
||||
- [ ] Payment method (last 4 digits only)
|
||||
- [ ] Estimated delivery date
|
||||
- [ ] Shipping method name
|
||||
- [ ] "What's Next" section (timeline)
|
||||
- [ ] Continue Shopping button (primary CTA)
|
||||
- [ ] Print receipt button
|
||||
- [ ] Contact support link
|
||||
- [ ] Guest orders: Create account CTA (optional)
|
||||
- [ ] Backend integration (fetch order from API)
|
||||
- [ ] Mobile-responsive (single column, full-width buttons)
|
||||
- [ ] Semantic HTML (main, section, h1, h2)
|
||||
- [ ] ARIA labels on sections
|
||||
- [ ] Live region announcing success
|
||||
- [ ] Keyboard navigation supported
|
||||
- [ ] High contrast text (4.5:1 minimum)
|
||||
@@ -0,0 +1,527 @@
|
||||
# Product Detail Page Layout
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Layout Structure](#layout-structure)
|
||||
- [Price Display and Medusa Integration](#price-display-and-medusa-integration)
|
||||
- [Variant Selection (Critical)](#variant-selection-critical)
|
||||
- [Stock Availability](#stock-availability)
|
||||
- [Add to Cart Behavior](#add-to-cart-behavior)
|
||||
- [Product Details Organization](#product-details-organization)
|
||||
- [Related Products Strategy](#related-products-strategy)
|
||||
- [Trust Signals and Conversion](#trust-signals-and-conversion)
|
||||
- [Mobile Optimization](#mobile-optimization)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
Most critical page for conversion. Customers make purchase decisions here based on product information, images, reviews, and trust signals.
|
||||
|
||||
### Key Requirements
|
||||
|
||||
- High-quality product images with zoom capability
|
||||
- Clear price display (handle variant price changes)
|
||||
- Variant selection (size, color, material)
|
||||
- Stock availability indicators
|
||||
- Prominent "Add to Cart" with proper feedback
|
||||
- Product details (description, specifications)
|
||||
- Customer reviews and ratings
|
||||
- Related product recommendations
|
||||
- Trust signals (shipping, returns, secure checkout)
|
||||
- Mobile-optimized (60%+ traffic)
|
||||
|
||||
### Routing Pattern
|
||||
|
||||
**CRITICAL: Always use dynamic routes, NEVER static pages.**
|
||||
|
||||
Product detail pages must use dynamic routes that accept a parameter (handle, slug, or ID):
|
||||
|
||||
**Correct examples:**
|
||||
- Next.js App Router: `app/products/[handle]/page.tsx`
|
||||
- Next.js Pages Router: `pages/products/[handle].tsx`
|
||||
- SvelteKit: `routes/products/[handle]/+page.svelte`
|
||||
- TanStack Start: `routes/products/$handle.tsx`
|
||||
- Remix: `routes/products.$handle.tsx`
|
||||
|
||||
**Wrong examples:**
|
||||
- ❌ `pages/products/blue-shirt.tsx` (static file per product)
|
||||
- ❌ `pages/products/red-shoes.tsx` (doesn't scale)
|
||||
|
||||
Fetch product data in the dynamic route based on the handle/ID parameter from the URL.
|
||||
|
||||
## Layout Structure
|
||||
|
||||
**Desktop (two-column):**
|
||||
- Left: Product images (50-60% width)
|
||||
- Right: Product info, variants, add to cart (40-50%)
|
||||
- Below: Product details, reviews, related products (full-width)
|
||||
|
||||
**Mobile (stacked):**
|
||||
- Images at top (full-width, swipeable)
|
||||
- Product info below (title, price, rating)
|
||||
- Variants and add to cart
|
||||
- Accordion for product details
|
||||
- Reviews section
|
||||
- Related products
|
||||
- Sticky "Add to Cart" bar at bottom
|
||||
|
||||
**Sticky sidebar option (desktop):**
|
||||
- Product info column stays visible during scroll
|
||||
- Add to cart always accessible
|
||||
- Useful for long product descriptions
|
||||
- Improves conversion
|
||||
|
||||
## Price Display
|
||||
|
||||
### Standard Price Display
|
||||
|
||||
**Current price:**
|
||||
- Large, bold font (28-36px)
|
||||
- Currency symbol included ($49.99)
|
||||
- Primary color or black
|
||||
|
||||
**Sale pricing:**
|
||||
- Original price with strikethrough: ~~$79.99~~ $49.99
|
||||
- Sale price in red or brand color
|
||||
- "Save X%" badge nearby
|
||||
- Example: Save 37%
|
||||
|
||||
**Variant price changes:**
|
||||
- **When no variant selected**: Show "From $X" where X is the minimum variant price across all variants
|
||||
- **When variant selected**: Update price dynamically to show the exact variant price
|
||||
- No page reload required
|
||||
- Show price change clearly (highlight briefly on change)
|
||||
- Example: Product with variants priced at $29.99, $34.99, $39.99 → Show "From $29.99" initially
|
||||
|
||||
### Medusa Pricing (CRITICAL)
|
||||
|
||||
**Important difference from Stripe:**
|
||||
- Medusa stores prices as-is (e.g., 49.99)
|
||||
- Display directly: If API returns 49.99, show $49.99
|
||||
- **DON'T divide by 100** (unlike Stripe which stores in cents)
|
||||
- Example: Medusa 49.99 → Display $49.99 (NOT $0.4999)
|
||||
|
||||
**Multi-currency (Medusa):**
|
||||
- Medusa supports multi-region pricing
|
||||
- Display price in user's region currency
|
||||
- Fetch pricing from selected region
|
||||
- Show currency code (usd, eur, etc.)
|
||||
|
||||
## Variant Selection (Critical)
|
||||
|
||||
This is a complex ecommerce-specific challenge. Variants affect price, stock, and images.
|
||||
|
||||
### Variant Complexity
|
||||
|
||||
**Key challenges:**
|
||||
- Multiple variant types (size, color, material)
|
||||
- Variant availability varies (some sizes out of stock)
|
||||
- Prices may differ by variant
|
||||
- Images change by color variant
|
||||
- Stock levels per variant
|
||||
- Combinations may not exist (size M + color Red might not exist)
|
||||
|
||||
**Fetch from backend:**
|
||||
```typescript
|
||||
// Get all variants for product
|
||||
// Change this based on the backend integrated
|
||||
const product = await fetch(`/products/${id}?fields=*variants`)
|
||||
// Returns variants with: id, sku, options, calculated_price, inventory_quantity
|
||||
```
|
||||
|
||||
### Variant Selection Patterns
|
||||
|
||||
**Use Button Group when:**
|
||||
- 2-8 options per variant type
|
||||
- Size selection (XS, S, M, L, XL)
|
||||
- Simple color options (5-6 colors)
|
||||
- Users need to see all options at once
|
||||
|
||||
**Benefits:**
|
||||
- Visible options (no click to reveal)
|
||||
- Faster selection
|
||||
- Clear visual feedback
|
||||
- Better UX
|
||||
|
||||
**Use Dropdown when:**
|
||||
- 10+ options per variant type
|
||||
- Material/style options with long names
|
||||
- Space-constrained layouts
|
||||
- Mobile optimization needed
|
||||
|
||||
**Benefits:**
|
||||
- Saves space
|
||||
- Works better for many options
|
||||
- Mobile-friendly
|
||||
|
||||
**Use Visual Swatches when:**
|
||||
- Color or pattern variations
|
||||
- Material with visual differences
|
||||
- Visual is key to decision
|
||||
- Fashion, home decor, customizable products
|
||||
|
||||
**Implementation:**
|
||||
- Circular/square swatches (40-48px)
|
||||
- Border on selected
|
||||
- Show product image in that color when selected
|
||||
- Color name on hover
|
||||
- Gray out unavailable colors
|
||||
|
||||
### Variant Selection Flow
|
||||
|
||||
**Critical sequence:**
|
||||
1. User selects first variant type (e.g., Color: Blue)
|
||||
2. **Update available options** for other variant types
|
||||
3. Show only size options available for Blue color
|
||||
4. Gray out/disable unavailable combinations
|
||||
5. Update price if variant price differs
|
||||
6. Update main product image to show selected variant
|
||||
7. Update stock availability
|
||||
8. Enable/disable "Add to Cart" based on availability
|
||||
|
||||
**Example: Two variants (Color + Size)**
|
||||
```typescript
|
||||
// When color selected
|
||||
// Change this based on the backend integrated
|
||||
onColorSelect(color) {
|
||||
// Find selected variant
|
||||
const selectededVariant = product.variants.find((variant) => variant.options?.every(
|
||||
(optionValue) => optionValue.id === selectedOptions[optionValue.option_id!]
|
||||
))
|
||||
|
||||
// Check if size is selected and update price
|
||||
if (selectededVariant) {
|
||||
const variant = findVariant(color, selectedSize)
|
||||
updatePrice(variant.price)
|
||||
updateStock(variant.inventory_quantity)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Validation and Error Handling
|
||||
|
||||
**Prevent adding without selection:**
|
||||
- Disable "Add to Cart" until all required variants selected
|
||||
- Or: Show error message "Please select a size"
|
||||
- Highlight missing selection (red border around options)
|
||||
- Scroll to variant selection on error
|
||||
|
||||
**Handle out of stock variants:**
|
||||
- Gray out unavailable options
|
||||
- "Out of stock" text on hover
|
||||
- Don't allow selection of out of stock variants
|
||||
- Suggest alternative variants if available
|
||||
|
||||
**Handle variant not found:**
|
||||
- When combination doesn't exist (Size M + Color Red)
|
||||
- Disable second option when first selected
|
||||
- Show only valid combinations
|
||||
- Or: Show "This combination is not available"
|
||||
|
||||
## Stock Availability
|
||||
|
||||
**Display patterns:**
|
||||
|
||||
**In stock:**
|
||||
- Green indicator (✓ or dot)
|
||||
- "In stock" or "Available"
|
||||
- Quantity if low: "Only 3 left"
|
||||
- Encourages urgency without being pushy
|
||||
|
||||
**Out of stock:**
|
||||
- Red indicator (✗ or dot)
|
||||
- "Out of stock" message
|
||||
- Disable "Add to Cart" button (grayed out)
|
||||
- Offer "Notify me when available"
|
||||
- Email capture for restock notifications (if supported by backend)
|
||||
|
||||
**Low stock warning:**
|
||||
- "Only X left in stock"
|
||||
- Shows scarcity (increases urgency)
|
||||
- Typically show when <= 5 items
|
||||
- Orange/yellow color
|
||||
|
||||
**Pre-order:**
|
||||
- "Pre-order now" status
|
||||
- Expected availability date: "Ships on [Date]"
|
||||
- Different button text: "Pre-order" instead of "Add to Cart"
|
||||
- Charge now or later (specify)
|
||||
|
||||
**Backend integration:**
|
||||
```typescript
|
||||
// Fetch stock for selected variant
|
||||
const stock = selectedVariant.inventory_quantity
|
||||
|
||||
if (stock === 0) {
|
||||
showOutOfStock()
|
||||
} else if (stock <= 5) {
|
||||
showLowStock(stock) // "Only 3 left"
|
||||
} else {
|
||||
showInStock()
|
||||
}
|
||||
```
|
||||
|
||||
## Add to Cart Behavior
|
||||
|
||||
**Button states:**
|
||||
- Default: Enabled (after variant selected)
|
||||
- Hover: Slight color change or scale
|
||||
- Loading: Spinner inside button (during API call)
|
||||
- Success: Checkmark briefly, then revert
|
||||
- Disabled: Grayed out (no variant or out of stock)
|
||||
|
||||
**Click behavior (Critical):**
|
||||
1. Show loading state (disable button, show spinner)
|
||||
2. Call API to add item to cart (backend)
|
||||
3. **Optimistic UI**: Update cart count immediately (before API response)
|
||||
4. Show success feedback (toast, checkmark, or cart popup)
|
||||
5. Update cart count in navbar header
|
||||
6. **DON'T navigate away** - stay on product page
|
||||
7. Handle errors: restore count if API fails
|
||||
|
||||
**Success feedback options:**
|
||||
- Toast notification: "Added to cart" (top-right)
|
||||
- Cart popup: Show mini cart with items (see cart-popup.md)
|
||||
- Checkmark in button briefly, then revert
|
||||
- All three combined (checkmark + toast or cart popup)
|
||||
|
||||
**Error handling:**
|
||||
```typescript
|
||||
async function addToCart(variantId, quantity) {
|
||||
try {
|
||||
// Optimistic update
|
||||
updateCartCountUI(+quantity)
|
||||
|
||||
// API call
|
||||
// Change this based on the backend integrated
|
||||
await fetch(`/store/carts/${cartId}/line-items`, {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ variant_id: variantId, quantity })
|
||||
})
|
||||
|
||||
// Success feedback
|
||||
showToast('Added to cart')
|
||||
showCartPopup() // Optional
|
||||
} catch (error) {
|
||||
// Revert optimistic update
|
||||
updateCartCountUI(-quantity)
|
||||
|
||||
// Show error
|
||||
if (error.message === 'OUT_OF_STOCK') {
|
||||
showError('Sorry, this item is now out of stock')
|
||||
updateStockStatus('out_of_stock')
|
||||
} else {
|
||||
showError('Failed to add to cart. Please try again.')
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Buy Now button (optional):**
|
||||
- Skip cart, go directly to checkout
|
||||
- Useful for: high-value items, single-item stores, decisive customers
|
||||
- Secondary button below "Add to Cart"
|
||||
- Text: "Buy Now" or "Buy It Now"
|
||||
- Add to cart + redirect to checkout in one action
|
||||
|
||||
## Product Details Organization
|
||||
|
||||
### Decision: Tabs vs Accordion
|
||||
|
||||
**Use Tabs (desktop) when:**
|
||||
- 3-5 distinct sections
|
||||
- Each section has substantial content
|
||||
- Users may want to compare sections
|
||||
- Desktop has screen space
|
||||
- Examples: Description, Specifications, Shipping, Reviews
|
||||
|
||||
**Use Accordion (mobile) always:**
|
||||
- Saves vertical space
|
||||
- Users expand what they need
|
||||
- Standard mobile pattern
|
||||
- Collapses after reading
|
||||
|
||||
**Hybrid approach (recommended):**
|
||||
- Tabs on desktop (horizontal navigation)
|
||||
- Accordion on mobile (vertical expansion)
|
||||
- Same content, different presentation
|
||||
- Best of both worlds
|
||||
|
||||
### Common Sections
|
||||
|
||||
**Description:**
|
||||
- Product overview (2-4 paragraphs)
|
||||
- Key features (bullet points)
|
||||
- Use cases
|
||||
- Materials and craftsmanship
|
||||
|
||||
**Specifications:**
|
||||
- Technical details (table format)
|
||||
- Dimensions, weight, materials
|
||||
- Care instructions
|
||||
- Compatibility information
|
||||
|
||||
**Shipping & Returns:**
|
||||
- Shipping options and costs
|
||||
- Delivery timeframes
|
||||
- Return policy (30 days, 60 days)
|
||||
- Return process
|
||||
- Link to full policy page
|
||||
|
||||
**Reviews:**
|
||||
- Embedded in tab/accordion
|
||||
- Or: Separate section below
|
||||
- Filter by rating, sort by date
|
||||
- Review submission form
|
||||
|
||||
## Related Products Strategy
|
||||
|
||||
**Types of recommendations:**
|
||||
|
||||
**"You May Also Like" (Similar products):**
|
||||
- Same category, similar price point
|
||||
- Algorithm: category match + price range
|
||||
- Goal: Show alternatives if unsure about current product
|
||||
|
||||
**"Frequently Bought Together" (Complementary):**
|
||||
- Products commonly purchased together
|
||||
- Algorithm: order history analysis
|
||||
- Goal: Increase average order value
|
||||
- Example: Phone + Case + Screen Protector
|
||||
- Show bundle discount if available
|
||||
|
||||
**"Recently Viewed" (Browsing history):**
|
||||
- User's browsing history (session or logged-in)
|
||||
- Helps users return to products they liked
|
||||
- Goal: Reduce decision paralysis
|
||||
|
||||
**"Customers Also Viewed":**
|
||||
- Products viewed by others who viewed this
|
||||
- Algorithm: co-viewing patterns
|
||||
- Goal: Discovery and alternatives
|
||||
|
||||
### Display Pattern
|
||||
|
||||
**Product slider:**
|
||||
- 4-6 products visible (desktop)
|
||||
- 2-3 visible (mobile)
|
||||
- Horizontal scrolling (swipe on mobile)
|
||||
- Product cards: image, title, price, rating
|
||||
- Optional: Quick "Add to Cart" on hover
|
||||
|
||||
**Placement:**
|
||||
- Below product details and reviews
|
||||
- Above footer
|
||||
- Full-width section
|
||||
- Clear heading for each type
|
||||
|
||||
**Backend integration:**
|
||||
```typescript
|
||||
// Fetch recommendations
|
||||
// Change this based on the backend integrated
|
||||
const recommendations = await fetch(`/products/${id}/recommendations`)
|
||||
// Returns: similar, bought_together, recently_viewed
|
||||
```
|
||||
|
||||
## Trust Signals and Conversion
|
||||
|
||||
**Essential trust signals:**
|
||||
|
||||
**Near Add to Cart:**
|
||||
- Free shipping badge (if applicable)
|
||||
- Free returns icon + text
|
||||
- Secure checkout icon
|
||||
- Money-back guarantee
|
||||
- Warranty information (if applicable)
|
||||
|
||||
**Below product title:**
|
||||
- Customer rating and review count (4.8 ★ 324 reviews)
|
||||
- Link to reviews section
|
||||
- "Best seller" or "Top rated" badge
|
||||
|
||||
**Payment methods:**
|
||||
- Accepted payment icons (Visa, Mastercard, PayPal, Apple Pay)
|
||||
- Small icons (40px)
|
||||
- Below "Add to Cart" or in footer
|
||||
- Shows payment options available
|
||||
|
||||
**For new/unknown brands:**
|
||||
- Customer testimonials
|
||||
- "Join 10,000+ happy customers"
|
||||
- Security badges (if legitimate - don't fake)
|
||||
- Social proof (Instagram photos, user content)
|
||||
- Clear contact information
|
||||
|
||||
**For high-value products:**
|
||||
- Detailed specifications
|
||||
- Professional photography
|
||||
- Video demonstrations
|
||||
- Warranty details prominently displayed
|
||||
- Customer service contact visible
|
||||
|
||||
## Mobile Optimization
|
||||
|
||||
**Critical mobile patterns:**
|
||||
|
||||
**Sticky "Add to Cart" bar:**
|
||||
- Fixed at bottom of screen
|
||||
- Always accessible (no scrolling needed)
|
||||
- Shows: Price + "Add to Cart" button
|
||||
- Appears after scrolling past fold
|
||||
- Higher conversion rates
|
||||
|
||||
**Image gallery:**
|
||||
- Full-width swipeable carousel
|
||||
- Pinch to zoom
|
||||
- Dot indicators (1/5, 2/5)
|
||||
- Tap to open full-screen view
|
||||
|
||||
**Variant selection:**
|
||||
- Large touch targets (44-48px)
|
||||
- Visual swatches easier than dropdowns
|
||||
- Clear selected state
|
||||
- Error messages visible
|
||||
|
||||
**Accordion for details:**
|
||||
- Description, Specs, Shipping as accordion
|
||||
- Starts collapsed (save space)
|
||||
- User expands what they need
|
||||
- Clear expand/collapse indicators
|
||||
|
||||
**Reviews section:**
|
||||
- Expandable (start with 2-3 reviews)
|
||||
- "Show more" button
|
||||
- Filter by rating
|
||||
- Star rating distribution chart
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential product detail page features:**
|
||||
|
||||
- [ ] High-quality product images with zoom
|
||||
- [ ] Price displayed correctly (Medusa: use value as-is, not divided)
|
||||
- [ ] Price shows "From $X" when no variant selected (X = minimum variant price)
|
||||
- [ ] Variant selection required before adding to cart
|
||||
- [ ] Variant selection updates: price, stock, image
|
||||
- [ ] Disable unavailable variant options (gray out)
|
||||
- [ ] Stock availability indicator (in stock, low stock, out of stock)
|
||||
- [ ] "Only X left" shown when stock is low (<=5)
|
||||
- [ ] Add to Cart disabled until variant selected
|
||||
- [ ] Optimistic UI update (cart count updates immediately)
|
||||
- [ ] Success feedback (toast, cart popup, or checkmark)
|
||||
- [ ] Stay on product page after adding (don't navigate away)
|
||||
- [ ] Error handling (out of stock, API failure)
|
||||
- [ ] Product description and specifications
|
||||
- [ ] Customer reviews and ratings
|
||||
- [ ] Related products recommendations (similar, bought together)
|
||||
- [ ] Trust signals (free shipping, returns, secure checkout)
|
||||
- [ ] Payment method icons displayed
|
||||
- [ ] Breadcrumb navigation
|
||||
- [ ] Mobile: Swipeable image gallery
|
||||
- [ ] Mobile: Accordion for product details
|
||||
- [ ] Mobile: Sticky Add to Cart bar (optional but effective)
|
||||
- [ ] Tabs on desktop, accordion on mobile (hybrid)
|
||||
- [ ] Fast loading (<2s, optimize images)
|
||||
- [ ] Keyboard accessible (tab through options, enter to add)
|
||||
- [ ] ARIA labels on variant selection (role="group", aria-label)
|
||||
@@ -0,0 +1,520 @@
|
||||
# Product Listing Page Layout
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Reusable Component Architecture](#reusable-component-architecture-recommended)
|
||||
- [Decision: Pagination vs Infinite Scroll vs Load More](#decision-pagination-vs-infinite-scroll-vs-load-more)
|
||||
- [Decision: Filter Pattern Selection](#decision-filter-pattern-selection)
|
||||
- [Product Grid Layout](#product-grid-layout)
|
||||
- [Filtering Strategy](#filtering-strategy)
|
||||
- [Sorting Strategy](#sorting-strategy)
|
||||
- [Backend Integration](#backend-integration)
|
||||
- [Empty and No Results States](#empty-and-no-results-states)
|
||||
- [Performance Optimization](#performance-optimization)
|
||||
- [Mobile Optimization](#mobile-optimization)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
Primary browsing interface where users compare products, apply filters, and navigate to product details. Critical for product discovery and conversion.
|
||||
|
||||
### Key Requirements
|
||||
|
||||
- Responsive product grid (3-4 columns desktop, 2 mobile)
|
||||
- Filtering (categories, price, attributes)
|
||||
- Sorting options (price, popularity, newest)
|
||||
- Pagination, infinite scroll, or load more
|
||||
- Results count and active filter indicators
|
||||
- Clear "no results" state with suggestions
|
||||
- Fast loading and filtering (<1s filter updates)
|
||||
- Backend integration for dynamic filtering
|
||||
|
||||
### Reusable Component Architecture (RECOMMENDED)
|
||||
|
||||
**Build product listing as a reusable component that works across multiple pages:**
|
||||
|
||||
✅ **Use the same product listing component for:**
|
||||
- "Shop All" page (all products, no category filter)
|
||||
- Category pages (filtered by specific category)
|
||||
- Search results page (filtered by search query)
|
||||
- Sale/Promotion pages (filtered by discount/promotion)
|
||||
- Collection pages (curated product sets)
|
||||
- Brand pages (filtered by brand)
|
||||
|
||||
**Benefits of reusable approach:**
|
||||
- Single source of truth for product browsing UI
|
||||
- Consistent filtering, sorting, and pagination behavior across entire site
|
||||
- Easier maintenance (fix bugs once, applies everywhere)
|
||||
- Better user experience (familiar interface on every product browsing page)
|
||||
- Significantly less code duplication
|
||||
|
||||
**What to make configurable:**
|
||||
- Initial filter parameters (category ID, search query, promotion ID, brand, etc.)
|
||||
- Page title and breadcrumbs
|
||||
- Whether to show filters sidebar (some pages may hide certain filters)
|
||||
- Default sort order (category: featured, search: relevance, sale: discount %)
|
||||
- Number of products per page
|
||||
- Filter options available (hide category filter on category pages, etc.)
|
||||
|
||||
**Common mistake:**
|
||||
- ❌ Creating separate components/pages for "Shop All", category pages, and search results with duplicated filtering/sorting/pagination logic
|
||||
- ✅ Build one reusable ProductListing component that accepts filter parameters and reuse it across all product browsing pages
|
||||
|
||||
### Routing Pattern
|
||||
|
||||
**CRITICAL: Always use dynamic routes for category pages, NEVER static pages.**
|
||||
|
||||
Category/listing pages must use dynamic routes that accept a parameter (handle, slug, or category ID):
|
||||
|
||||
**Correct examples:**
|
||||
- Next.js App Router: `app/categories/[handle]/page.tsx`
|
||||
- Next.js Pages Router: `pages/categories/[handle].tsx`
|
||||
- SvelteKit: `routes/categories/[handle]/+page.svelte`
|
||||
- TanStack Start: `routes/categories/$handle.tsx`
|
||||
- Remix: `routes/categories.$handle.tsx`
|
||||
|
||||
**Wrong examples:**
|
||||
- ❌ `pages/categories/women.tsx` (static file per category)
|
||||
- ❌ `pages/categories/men.tsx` (doesn't scale)
|
||||
|
||||
Fetch category products in the dynamic route based on the handle/ID parameter from the URL.
|
||||
|
||||
## Decision: Pagination vs Infinite Scroll vs Load More
|
||||
|
||||
This is a critical ecommerce decision that affects user experience, SEO, and technical implementation.
|
||||
|
||||
### Use Pagination When:
|
||||
|
||||
**User needs:**
|
||||
- Return to specific result pages
|
||||
- Precise control over browsing
|
||||
- Professional/research shopping (compare systematically)
|
||||
- B2B shoppers (procurement, large orders)
|
||||
|
||||
**Product characteristics:**
|
||||
- Position matters (rankings, bestsellers)
|
||||
- Large catalog with stable ordering
|
||||
- Products require careful comparison
|
||||
|
||||
**Technical benefits:**
|
||||
- SEO-friendly (unique URL per page)
|
||||
- Better for indexing and crawling
|
||||
- Easier back button support
|
||||
- Lower memory usage
|
||||
|
||||
**Implementation:**
|
||||
```typescript
|
||||
// URL structure: /products?page=2&category=shirts
|
||||
// Each page has unique URL for SEO
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Desktop-heavy audience
|
||||
- B2B ecommerce
|
||||
- Product comparison shopping
|
||||
- Catalog with 100+ products
|
||||
|
||||
### Use Infinite Scroll When:
|
||||
|
||||
**User needs:**
|
||||
- Exploratory browsing behavior
|
||||
- Mobile-first experience
|
||||
- Seamless discovery flow
|
||||
- Fashion/visual shopping
|
||||
|
||||
**Product characteristics:**
|
||||
- Visual-heavy products (fashion, art, photography)
|
||||
- Impulse purchases
|
||||
- Discovery-focused (Pinterest-style)
|
||||
|
||||
**Technical considerations:**
|
||||
- More complex to implement
|
||||
- Requires careful SEO handling (pagination URLs still needed)
|
||||
- Higher memory usage (all loaded products stay in DOM)
|
||||
- Need to handle browser back button carefully
|
||||
|
||||
**Implementation:**
|
||||
```typescript
|
||||
// Load more when user scrolls to bottom
|
||||
// Keep pagination in URL for SEO: /products?page=2
|
||||
// Use Intersection Observer API for detection
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- Mobile-first stores (>60% mobile traffic)
|
||||
- Fashion, home decor, visual products
|
||||
- Younger demographic (18-34)
|
||||
- Discovery-focused shopping
|
||||
|
||||
### Use "Load More" Button When:
|
||||
|
||||
**Benefits of compromise:**
|
||||
- User controls when to load (not automatic)
|
||||
- Footer remains accessible (important for policies, contact)
|
||||
- Better for slower connections (international users)
|
||||
- Accessibility friendly (no automatic loading)
|
||||
- Lower memory usage than infinite scroll
|
||||
|
||||
**Implementation:**
|
||||
```typescript
|
||||
// Button triggers next page load
|
||||
// Append products to existing grid
|
||||
// Show count: "Load 24 More Products"
|
||||
```
|
||||
|
||||
**Best for:**
|
||||
- International audience (varying connection speeds)
|
||||
- Footer content is important (legal, policies, contact)
|
||||
- Accessibility concerns with infinite scroll
|
||||
- Compromise between pagination and infinite scroll
|
||||
|
||||
### Hybrid Approach (Recommended):
|
||||
|
||||
Combine patterns based on context:
|
||||
- Pagination for SEO (canonical URLs)
|
||||
- Infinite scroll for UX (on user interaction)
|
||||
- Load more for control (user-triggered)
|
||||
|
||||
**Example:**
|
||||
```typescript
|
||||
// Desktop: Pagination at bottom + infinite scroll option
|
||||
// Mobile: Infinite scroll with pagination URLs for SEO
|
||||
// All: Preserve scroll position on back button
|
||||
```
|
||||
|
||||
## Decision: Filter Pattern Selection
|
||||
|
||||
### Sidebar Filters (Desktop)
|
||||
|
||||
**Use when:**
|
||||
- Many filter options (5+ categories)
|
||||
- Complex product attributes
|
||||
- Power users (B2B, professional shoppers)
|
||||
- Desktop-heavy traffic
|
||||
|
||||
**Layout:**
|
||||
- Left sidebar (250-320px wide)
|
||||
- Sticky position (scrolls with page)
|
||||
- Collapsible sections (accordion)
|
||||
- Apply immediately (no "Apply" button)
|
||||
|
||||
### Top Filters (Desktop)
|
||||
|
||||
**Use when:**
|
||||
- Few filter options (2-4 key filters)
|
||||
- Maximize grid space (full-width layout)
|
||||
- Simple product categories
|
||||
- Visual-first products (fashion)
|
||||
|
||||
**Layout:**
|
||||
- Horizontal filter bar above grid
|
||||
- Dropdowns or button toggles
|
||||
- Limited options (price, category, brand)
|
||||
- Compact design
|
||||
|
||||
### Drawer Filters (Mobile - Always)
|
||||
|
||||
**Pattern:**
|
||||
- "Filters" button at top (shows active count badge)
|
||||
- Slide-out drawer (full-screen or 80% width)
|
||||
- Accordion sections
|
||||
- "Apply" button at bottom (batch filtering)
|
||||
- "Clear All" option
|
||||
|
||||
**Why batch filtering on mobile:**
|
||||
- Prevents multiple re-renders on slow connections
|
||||
- User can adjust multiple filters before applying
|
||||
- Better mobile UX (less disruptive)
|
||||
|
||||
## Product Grid Layout
|
||||
|
||||
**Responsive columns:**
|
||||
- Large desktop (>1440px): 4 columns
|
||||
- Desktop (1024-1440px): 3-4 columns
|
||||
- Tablet (768-1024px): 3 columns
|
||||
- Mobile (< 768px): 2 columns
|
||||
|
||||
**Adjust based on product type:**
|
||||
- Fashion/lifestyle: 3-4 columns (more visible at once)
|
||||
- Electronics/detailed: 2-3 columns (larger cards, more detail)
|
||||
- Furniture/large items: 2-3 columns (showcase details)
|
||||
|
||||
**Product card essentials:**
|
||||
- Product image (primary)
|
||||
- Title (truncated to 2 lines)
|
||||
- Price (Medusa: display as-is, don't divide by 100)
|
||||
- Optional: Rating, badges, wishlist
|
||||
- See product-card.md for detailed guidelines
|
||||
|
||||
**Grid spacing:**
|
||||
- 16-24px gap (desktop)
|
||||
- 12-16px gap (mobile)
|
||||
- Equal height rows (optional, improves visual consistency)
|
||||
|
||||
## Filtering Strategy
|
||||
|
||||
### Filter Types by Purpose
|
||||
|
||||
**Category filters:**
|
||||
- Multi-select checkboxes
|
||||
- Hierarchical (parent-child categories)
|
||||
- Show product count per category
|
||||
- Example: "Shirts (24)" "T-Shirts (12)"
|
||||
|
||||
**Price range filter:**
|
||||
- Range slider (drag min/max)
|
||||
- Or: Predefined ranges ("$0-$50", "$50-$100")
|
||||
- Update dynamically as products filtered
|
||||
- Show min/max from current results
|
||||
|
||||
**Attribute filters (Size, Color, Brand):**
|
||||
- Multi-select checkboxes
|
||||
- Visual swatches for colors
|
||||
- Show available options based on current filters
|
||||
- Gray out unavailable combinations
|
||||
|
||||
**Availability filters:**
|
||||
- "In Stock" checkbox
|
||||
- "On Sale" checkbox
|
||||
- "New Arrivals" checkbox
|
||||
- Single purpose, clear value
|
||||
|
||||
### Filter Behavior
|
||||
|
||||
**Filter persistence:**
|
||||
- Save in URL parameters (shareable, bookmarkable)
|
||||
- Example: `/products?category=shirts&price=0-50&color=blue`
|
||||
- Restore filters on page reload
|
||||
- Clear all filters should reset URL
|
||||
|
||||
### Active Filters Display
|
||||
|
||||
**Show active filters:**
|
||||
- Above product grid
|
||||
- Pill/tag format: "Blue ✕" "Under $50 ✕"
|
||||
- Click X to remove individual filter
|
||||
- "Clear All" link to remove all filters
|
||||
- Count: "3 filters active"
|
||||
|
||||
## Sorting Strategy
|
||||
|
||||
### Common Sort Options
|
||||
|
||||
**Essential options:**
|
||||
- **Featured** (default): Store's recommended order (bestsellers, promoted)
|
||||
- **Price: Low to High**: Budget-conscious shoppers
|
||||
- **Price: High to Low**: Premium product seekers
|
||||
- **Newest**: Fashion, tech, time-sensitive products
|
||||
- **Best Selling**: Social proof, popular choices
|
||||
- **Top Rated**: Quality-focused shoppers
|
||||
|
||||
**Advanced options:**
|
||||
- Name: A-Z (alphabetical)
|
||||
- Discount: Highest % off (sale hunters)
|
||||
- Reviews: Most reviewed (validation seekers)
|
||||
|
||||
### Sort Implementation
|
||||
|
||||
**Display:**
|
||||
- Dropdown above product grid (right-aligned)
|
||||
- Label: "Sort by:" or just dropdown
|
||||
- Update products immediately on selection
|
||||
- Show current sort in URL: `/products?order=-created_at`
|
||||
|
||||
**Backend integration:**
|
||||
- Pass sort parameter to API (check backend docs for parameter name)
|
||||
- Common parameters: `order`, `sort`, `sort_by`
|
||||
- Common values: `-created_at` (desc), `+price` (asc), `-price` (desc)
|
||||
|
||||
**Preserve filters:**
|
||||
- Sorting doesn't clear filters
|
||||
- Maintains all active filters
|
||||
- Updates URL with sort parameter
|
||||
|
||||
## Backend Integration
|
||||
|
||||
### Fetching Products
|
||||
|
||||
**Query parameters to include:**
|
||||
- Category/collection filter (if applicable)
|
||||
- Pagination (limit, offset or cursor)
|
||||
- Sort order
|
||||
- Filter values (price, attributes, etc.)
|
||||
- For Medusa: `region_id` (required for correct pricing)
|
||||
|
||||
Check backend API documentation for exact parameter names and formats.
|
||||
|
||||
### Available Filters
|
||||
|
||||
**Dynamic filter updates:**
|
||||
- Show only relevant filters for current category
|
||||
- Display product count per filter option
|
||||
- Gray out options with 0 products
|
||||
- Update available options when filters change
|
||||
|
||||
### URL State Management
|
||||
|
||||
**Filter URL structure pattern:**
|
||||
`/products?category_id=123&order=-created_at&page=2&price=0-50`
|
||||
|
||||
**Benefits:**
|
||||
- Shareable links
|
||||
- Bookmarkable searches
|
||||
- Browser back/forward works correctly
|
||||
- SEO-friendly (crawlable filter combinations)
|
||||
|
||||
**Implementation approach:**
|
||||
- Read filters from URL query parameters on page load
|
||||
- Update URL when filters change using URLSearchParams and history.pushState
|
||||
- Parse URL parameters to reconstruct filter state
|
||||
|
||||
## Empty and No Results States
|
||||
|
||||
### No Products in Category
|
||||
|
||||
**When category is empty:**
|
||||
- Message: "No products available yet"
|
||||
- Subtext: "Check back soon for new arrivals"
|
||||
- CTA: "Browse all products" or "Go to home"
|
||||
- Alternative: Show related categories
|
||||
- Optional: Newsletter signup for notifications
|
||||
|
||||
### No Results from Filters
|
||||
|
||||
**When filters too restrictive:**
|
||||
- Message: "No products match your filters"
|
||||
- Subtext: "Try removing some filters or adjusting your criteria"
|
||||
- **Prominent "Clear All Filters" button**
|
||||
- Show which filters might be too restrictive
|
||||
- Suggestions: "Try expanding price range" or "Remove brand filter"
|
||||
|
||||
**Example:**
|
||||
```
|
||||
No products found
|
||||
|
||||
You filtered by:
|
||||
- Color: Blue
|
||||
- Size: XXL
|
||||
- Price: $0-$20
|
||||
|
||||
Try:
|
||||
• Removing size filter (only 2 XXL products)
|
||||
• Expanding price range
|
||||
• [Clear All Filters]
|
||||
```
|
||||
|
||||
### No Results from Search
|
||||
|
||||
**When search query returns nothing:**
|
||||
- Message: "No results for '[query]'"
|
||||
- Suggestions: Check spelling, try different keywords
|
||||
- CTA: Browse popular categories
|
||||
- Show search suggestions (similar queries)
|
||||
- Display popular or trending products
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Lazy Loading Images
|
||||
|
||||
**Implementation:**
|
||||
- Load images as they come into viewport
|
||||
- Use Intersection Observer API
|
||||
- Show placeholder or blur-up effect
|
||||
- Improves initial page load significantly
|
||||
|
||||
**Critical for ecommerce:**
|
||||
- Product listings have 24-100+ images per page
|
||||
- Lazy loading reduces initial load by 60-80%
|
||||
- Faster perceived performance
|
||||
|
||||
### Virtual Scrolling (Advanced)
|
||||
|
||||
**When to use:**
|
||||
- Very large catalogs (500+ products visible)
|
||||
- Infinite scroll with memory concerns
|
||||
- Performance issues with many DOM elements
|
||||
|
||||
**How it works:**
|
||||
- Only render visible products + buffer
|
||||
- Reuse DOM elements as user scrolls
|
||||
- Maintains scroll position
|
||||
- Libraries: react-window, react-virtuoso
|
||||
|
||||
**Tradeoff:**
|
||||
- Complex implementation
|
||||
- Better performance for large lists
|
||||
- Required for catalogs with 1000+ products loaded
|
||||
|
||||
### Filter Performance
|
||||
|
||||
**Optimistic UI:**
|
||||
- Update grid immediately (predicted results)
|
||||
- Show loading overlay briefly
|
||||
- Replace with real results
|
||||
- Better perceived performance
|
||||
|
||||
## Mobile Optimization
|
||||
|
||||
**Critical mobile patterns:**
|
||||
|
||||
**2-column grid:**
|
||||
- Maximum 2 products per row
|
||||
- Larger touch targets
|
||||
- Simplified cards (essential info only)
|
||||
- Remove hover effects
|
||||
|
||||
**Filter drawer:**
|
||||
- Full-screen or 80% width drawer
|
||||
- "Filters" button with badge count
|
||||
- Batch apply (don't re-fetch on each change)
|
||||
- Clear all at top
|
||||
|
||||
**Sticky filter/sort bar:**
|
||||
- Fixed at top while scrolling
|
||||
- Quick access to filters and sorting
|
||||
- Shows active filter count
|
||||
- Higher engagement rates
|
||||
|
||||
**Infinite scroll default:**
|
||||
- Better mobile UX than pagination
|
||||
- Natural scrolling behavior
|
||||
- Keep pagination URLs for SEO
|
||||
- Handle back button correctly
|
||||
|
||||
**Performance:**
|
||||
- Lazy load images (critical on mobile)
|
||||
- Limit initial products (12-24)
|
||||
- Optimize image sizes for mobile
|
||||
- Fast filter updates (<1s)
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential product listing features:**
|
||||
|
||||
- [ ] **RECOMMENDED: Product listing built as reusable component**
|
||||
- [ ] Reusable component works for: shop all, category pages, search results, sale pages
|
||||
- [ ] Component accepts filter parameters (categoryId, searchQuery, promotionId, etc.)
|
||||
- [ ] Responsive grid (3-4 columns desktop, 2 mobile)
|
||||
- [ ] Decision made: Pagination vs infinite scroll vs load more
|
||||
- [ ] Filter pattern selected: Sidebar (desktop) vs drawer (mobile)
|
||||
- [ ] Filters fetched from backend dynamically
|
||||
- [ ] Filter options show product count
|
||||
- [ ] Active filters displayed above grid (removable pills)
|
||||
- [ ] "Clear all filters" button prominent
|
||||
- [ ] Sorting options (featured, price, newest, bestselling)
|
||||
- [ ] Sort updates products without clearing filters
|
||||
- [ ] Filters and sort persist in URL (shareable)
|
||||
- [ ] Results count displayed ("Showing 1-24 of 156 products")
|
||||
- [ ] Empty state: "No products match filters" with suggestions
|
||||
- [ ] "Clear all filters" prominent when no results
|
||||
- [ ] Product prices displayed correctly (Medusa: as-is, not divided)
|
||||
- [ ] Lazy loading for images (Intersection Observer)
|
||||
- [ ] Loading state for filter changes (< 1s)
|
||||
- [ ] Mobile: Filter drawer with batch apply
|
||||
- [ ] Mobile: 2-column grid maximum
|
||||
- [ ] Mobile: Sticky filter/sort button
|
||||
- [ ] Pagination URLs for SEO (even with infinite scroll)
|
||||
- [ ] Back button support (restore filters, scroll position)
|
||||
- [ ] Keyboard accessible (tab through filters, enter to apply)
|
||||
- [ ] ARIA labels on filters (role="group", aria-label)
|
||||
@@ -0,0 +1,356 @@
|
||||
# Static Pages
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [FAQ Page](#faq-page)
|
||||
- [About Page](#about-page)
|
||||
- [Contact Page](#contact-page)
|
||||
- [Shipping and Returns](#shipping-and-returns)
|
||||
- [Privacy Policy and Terms](#privacy-policy-and-terms)
|
||||
- [Size Guide](#size-guide)
|
||||
- [Mobile and SEO](#mobile-and-seo)
|
||||
- [Checklist](#checklist)
|
||||
|
||||
## Overview
|
||||
|
||||
Static pages provide essential information about the store, policies, and customer support. Purpose: Build trust, reduce support inquiries, meet legal requirements, improve SEO.
|
||||
|
||||
### Essential Static Pages
|
||||
|
||||
**Required:**
|
||||
- Privacy Policy (legally required in most regions)
|
||||
- Terms and Conditions
|
||||
- Shipping and Returns
|
||||
- Contact
|
||||
|
||||
**Strongly recommended:**
|
||||
- FAQ (Frequently Asked Questions)
|
||||
- About Us
|
||||
|
||||
**Optional:**
|
||||
- Size Guide (for apparel stores)
|
||||
- Store Locator (if physical stores)
|
||||
|
||||
## FAQ Page
|
||||
|
||||
### Purpose and Structure
|
||||
|
||||
**Purpose**: Answer common customer questions, reduce support inquiries, improve purchase confidence.
|
||||
|
||||
**Common FAQ categories:**
|
||||
- Ordering and Payment
|
||||
- Shipping and Delivery
|
||||
- Returns and Exchanges
|
||||
- Product Information
|
||||
- Account Management
|
||||
|
||||
### Layout Pattern: Accordion (Recommended)
|
||||
|
||||
Question as clickable header, answer hidden by default, click to expand. Compact, scannable format.
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Frequently Asked Questions
|
||||
|
||||
Ordering and Payment
|
||||
|
||||
▸ How do I place an order?
|
||||
▸ What payment methods do you accept?
|
||||
▸ Is it safe to use my credit card?
|
||||
|
||||
Shipping and Delivery
|
||||
|
||||
▸ How long does shipping take?
|
||||
▸ Do you ship internationally?
|
||||
```
|
||||
|
||||
**Alternative: All Expanded**
|
||||
All questions and answers visible. Better for few questions (<10), good for SEO (all content visible), easy to Ctrl+F search.
|
||||
|
||||
### Search Functionality
|
||||
|
||||
**FAQ search** (for extensive FAQs):
|
||||
Search box at top, real-time filtering as user types, highlights matching questions, "No results" state with contact link.
|
||||
|
||||
### Content Guidelines
|
||||
|
||||
**Question format:**
|
||||
Clear, concise, use customer language, start with question words (How, What, When).
|
||||
|
||||
**Answer format:**
|
||||
Direct answer first sentence, additional details if needed, bullet points for lists, link to related pages, 2-4 sentences ideal.
|
||||
|
||||
## About Page
|
||||
|
||||
### Purpose and Content
|
||||
|
||||
**Purpose**: Tell brand story, build trust and connection, showcase values and mission, differentiate from competitors.
|
||||
|
||||
**Key sections:**
|
||||
- Brand story/history (how the company started)
|
||||
- Mission and values (3-5 core values)
|
||||
- Why choose us (what makes you different)
|
||||
- Sustainability/social responsibility (if applicable)
|
||||
|
||||
### Layout Structure
|
||||
|
||||
**Hero section:**
|
||||
Large image (team, products, brand imagery), headline (brand tagline or mission), brief intro paragraph (2-3 sentences).
|
||||
|
||||
**Story section:**
|
||||
3-5 paragraphs, conversational tone, focus on customer benefits.
|
||||
|
||||
**Values section:**
|
||||
3-5 core values with icon or image for each, brief description (1-2 sentences).
|
||||
|
||||
**Call-to-action:**
|
||||
Shop products, join newsletter, follow on social media.
|
||||
|
||||
## Contact Page
|
||||
|
||||
### Contact Methods
|
||||
|
||||
**Essential:**
|
||||
- Contact form (primary)
|
||||
- Email address
|
||||
- Phone number (optional)
|
||||
- Business hours
|
||||
- Response time expectation ("We respond within 24 hours")
|
||||
|
||||
**Optional:**
|
||||
- Live chat button
|
||||
- FAQ link ("Find answers faster")
|
||||
- Social media links
|
||||
- Physical address (if applicable)
|
||||
|
||||
### Contact Form
|
||||
|
||||
**Form fields:**
|
||||
- Name (required)
|
||||
- Email (required)
|
||||
- Subject or Topic (dropdown, optional)
|
||||
- Message (textarea, required)
|
||||
- Order number (optional, for order inquiries)
|
||||
- Submit button
|
||||
|
||||
**Form features:**
|
||||
Clear field labels, placeholder examples, required field indicators, email validation, success confirmation.
|
||||
|
||||
## Shipping and Returns
|
||||
|
||||
### Shipping Information
|
||||
|
||||
**Key sections:**
|
||||
- Shipping methods and costs (table format)
|
||||
- Delivery timeframes
|
||||
- International shipping (if applicable)
|
||||
- Order processing time ("Orders placed by 2pm EST ship same day")
|
||||
- Tracking information
|
||||
- Shipping restrictions
|
||||
|
||||
**Shipping Methods Table Format:**
|
||||
```
|
||||
Method | Cost | Delivery Time
|
||||
──────────────────────────────────────────
|
||||
Standard | $5.99 | 5-7 business days
|
||||
Express | $12.99 | 2-3 business days
|
||||
Overnight | $24.99 | Next business day
|
||||
Free Shipping | Free | Orders over $50
|
||||
```
|
||||
|
||||
### Returns and Exchanges
|
||||
|
||||
**Key information:**
|
||||
- Return window (e.g., 30 days)
|
||||
- Return conditions (unused, tags attached, etc.)
|
||||
- Refund method (original payment, store credit)
|
||||
- Return shipping cost
|
||||
- Exchange process
|
||||
- Non-returnable items
|
||||
|
||||
**Return process steps:**
|
||||
```
|
||||
How to Return an Item
|
||||
|
||||
1. Initiate Return
|
||||
Log into your account and select the order
|
||||
|
||||
2. Print Return Label
|
||||
We'll email you a prepaid shipping label
|
||||
|
||||
3. Pack and Ship
|
||||
Include all original packaging and tags
|
||||
|
||||
4. Receive Refund
|
||||
Refunds processed within 5-7 business days
|
||||
```
|
||||
|
||||
## Privacy Policy and Terms
|
||||
|
||||
### Privacy Policy
|
||||
|
||||
**Purpose**: Legal requirement in most regions (GDPR, CCPA compliance), explain data collection and use, build customer trust.
|
||||
|
||||
**Key sections:**
|
||||
- Information collected
|
||||
- How information is used
|
||||
- Data sharing and disclosure
|
||||
- Cookies and tracking
|
||||
- User rights (access, deletion, etc.)
|
||||
- Data security measures
|
||||
- Contact for privacy inquiries
|
||||
- Last updated date
|
||||
|
||||
**Layout:**
|
||||
Table of contents (for long policies), clear section headings, numbered or bulleted lists, plain language, last updated date at top.
|
||||
|
||||
**Important**: Consult legal counsel for content, include required disclosures, update regularly.
|
||||
|
||||
### Terms and Conditions
|
||||
|
||||
**Purpose**: Legal agreement between store and customer, define rules and limitations, protect business legally.
|
||||
|
||||
**Key sections:**
|
||||
- Acceptance of terms
|
||||
- Product descriptions and pricing
|
||||
- Order acceptance and cancellation
|
||||
- Payment and billing
|
||||
- Shipping and delivery
|
||||
- Returns and refunds
|
||||
- Intellectual property
|
||||
- Limitation of liability
|
||||
- Dispute resolution
|
||||
- Changes to terms
|
||||
|
||||
**Layout:**
|
||||
Numbered sections (1, 1.1, 1.2), table of contents for long documents, clear section titles, anchor links to sections.
|
||||
|
||||
## Size Guide
|
||||
|
||||
**Purpose (for apparel/footwear stores)**:
|
||||
Help customers choose correct size, reduce returns due to sizing issues, increase purchase confidence.
|
||||
|
||||
**Content:**
|
||||
- Size charts (numeric measurements) - use proper table markup
|
||||
- How to measure instructions with illustrations
|
||||
- Fit descriptions (slim fit, relaxed, etc.)
|
||||
- Model measurements (for reference)
|
||||
- Size conversion chart (US, EU, UK)
|
||||
|
||||
**Size Chart Format:**
|
||||
```
|
||||
Women's Tops Size Guide
|
||||
|
||||
Size | Bust | Waist | Hips
|
||||
─────────────────────────────────────
|
||||
XS | 32-33" | 24-25" | 35-36"
|
||||
S | 34-35" | 26-27" | 37-38"
|
||||
M | 36-37" | 28-29" | 39-40"
|
||||
L | 38-40" | 30-32" | 41-43"
|
||||
XL | 41-43" | 33-35" | 44-46"
|
||||
```
|
||||
|
||||
**Accessibility:**
|
||||
Use proper table markup (not images), clear column headers, screen reader friendly, mobile-responsive tables.
|
||||
|
||||
## Mobile and SEO
|
||||
|
||||
### Mobile Optimizations
|
||||
|
||||
**Layout:**
|
||||
Single column, full-width content, larger touch targets for accordions, generous padding (16-20px).
|
||||
|
||||
**Typography:**
|
||||
16px minimum body text, 24-32px headings, line height 1.5-1.6, short paragraphs (3-4 sentences max).
|
||||
|
||||
**Tables:**
|
||||
Horizontal scroll for wide tables or card layout (stacked rows), responsive design.
|
||||
|
||||
**Forms:**
|
||||
Full-width inputs, 44-48px height, large submit buttons, appropriate keyboard types.
|
||||
|
||||
**Quick actions:**
|
||||
- Tap-to-call: Phone numbers as clickable links (`tel:`)
|
||||
- Tap-to-email: Email addresses as clickable links (`mailto:`)
|
||||
- Map integration: "Get Directions" links to native map app
|
||||
|
||||
### SEO for Static Pages
|
||||
|
||||
**On-Page SEO:**
|
||||
- Unique title per page (50-60 characters max, format: "Page Title | Store Name")
|
||||
- Meta descriptions (150-160 characters, include call-to-action)
|
||||
- Proper heading hierarchy (one H1 per page, H2 for sections, H3 for subsections)
|
||||
- Original, unique content
|
||||
- Internal links to products/categories
|
||||
- Regular updates (especially FAQ)
|
||||
|
||||
**Schema Markup:**
|
||||
- FAQ schema for FAQ pages (rich snippets)
|
||||
- Organization schema for About page
|
||||
- LocalBusiness schema for Store Locator
|
||||
- ContactPoint schema for Contact page
|
||||
|
||||
**Benefits:**
|
||||
Rich snippets in search results, improved visibility, better click-through rates.
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential pages:**
|
||||
|
||||
- [ ] FAQ page with accordion layout
|
||||
- [ ] FAQ search functionality (for extensive FAQs)
|
||||
- [ ] FAQ categories organized logically
|
||||
- [ ] Contact page with form
|
||||
- [ ] Contact form validation
|
||||
- [ ] Email address and business hours visible
|
||||
- [ ] Shipping and Returns page
|
||||
- [ ] Shipping methods and costs table
|
||||
- [ ] Delivery timeframes clear
|
||||
- [ ] Return policy with conditions
|
||||
- [ ] Return process step-by-step
|
||||
- [ ] Privacy Policy page
|
||||
- [ ] Last updated date on Privacy Policy
|
||||
- [ ] Privacy policy in plain language
|
||||
- [ ] Terms and Conditions page
|
||||
- [ ] Last updated date on Terms
|
||||
|
||||
**Optional but valuable:**
|
||||
|
||||
- [ ] About Us page with brand story
|
||||
- [ ] Mission and values section
|
||||
- [ ] Size Guide (if apparel)
|
||||
- [ ] Size charts with measurements
|
||||
- [ ] How to measure instructions
|
||||
- [ ] Store Locator (if physical stores)
|
||||
|
||||
**SEO and technical:**
|
||||
|
||||
- [ ] Unique title tags per page
|
||||
- [ ] Meta descriptions per page
|
||||
- [ ] Proper heading hierarchy (H1, H2, H3)
|
||||
- [ ] Internal links to products/categories
|
||||
- [ ] Schema markup (FAQ, Organization, etc.)
|
||||
- [ ] Mobile-responsive layout
|
||||
- [ ] Fast loading times
|
||||
|
||||
**Accessibility:**
|
||||
|
||||
- [ ] Semantic HTML (main, article, section)
|
||||
- [ ] ARIA labels on accordions
|
||||
- [ ] Keyboard navigation supported
|
||||
- [ ] Focus indicators visible
|
||||
- [ ] High contrast text (4.5:1)
|
||||
- [ ] Forms properly labeled
|
||||
- [ ] Tables with proper headers
|
||||
- [ ] Alt text on images
|
||||
|
||||
**Content quality:**
|
||||
|
||||
- [ ] Clear, concise writing
|
||||
- [ ] Short paragraphs (3-4 sentences)
|
||||
- [ ] Bullet points for lists
|
||||
- [ ] Regular content updates
|
||||
- [ ] No outdated information
|
||||
- [ ] Contact info current
|
||||
- [ ] Policies reflect current practices
|
||||
Reference in New Issue
Block a user