@thorprovider/create-storefront 0.1.1

package/skills/storefront-best-practices/reference/layouts/home-page.md

@@ -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

package/skills/storefront-best-practices/reference/layouts/order-confirmation.md

@@ -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)