@thorprovider/create-storefront 0.1.1

package/skills/storefront-best-practices/reference/components/product-card.md

@@ -0,0 +1,125 @@
+# Product Card Component
+
+## Contents
+
+- [Overview](#overview)
+- [Price Display (Ecommerce-Specific)](#price-display-ecommerce-specific)
+- [Action Buttons and Variant Handling](#action-buttons-and-variant-handling)
+- [Badges and Labels](#badges-and-labels)
+- [Mobile Considerations](#mobile-considerations)
+- [Ecommerce Checklist](#ecommerce-checklist)
+
+## Overview
+
+Product cards display products in grids (product listings, search results, related products). Key ecommerce considerations: clear pricing, quick add-to-cart, and stock indicators.
+
+**Assumed knowledge**: AI agents know how to build cards with images, titles, and buttons. This guide focuses on ecommerce-specific patterns.
+
+### Key Ecommerce Requirements
+
+- Clear, prominent pricing (including sale prices)
+- Variant handling for add-to-cart
+- Stock status indicators
+- Sale/New/Out of Stock badges
+- Responsive grid (1 col mobile, 2-3 tablet, 3-4 desktop)
+- Fast image loading (lazy load, optimized)
+
+## Price Display (Ecommerce-Specific)
+
+### Regular vs Sale Pricing
+
+**Sale price display:**
+- Sale price: Larger, bold, red or accent color
+- Original price: Smaller, struck through (~~$79.99~~), gray
+- Position sale price before original price
+- Optional: Show discount percentage badge (-20%)
+
+**Format consistently:**
+- Always include currency symbol ($49.99)
+- Consistent decimals ($49.99 not $49.9 or $50)
+- For Medusa: Display prices as-is (no divide by 100)
+
+### Price Range (Multiple Variants)
+
+**When variants have different prices:**
+- Show "From $49" or "$49 - $79"
+- Makes it clear price varies by selection
+- Don't show range if all variants same price
+
+## Action Buttons and Variant Handling
+
+### Add to Cart with Variants (CRITICAL)
+
+**Key challenge**: Products with variants require variant selection before adding to cart.
+
+**Handling strategies:**
+
+1. **Add first variant by default** - Click adds `product.variants[0]`. Fast for simple products (1-2 variants).
+2. **Redirect to product page** - Navigate to detail page for variant selection. Best for complex products (size + color + material).
+3. **Quick View modal** - Variant selector in modal. Good middle ground (desktop only).
+
+**Decision:**
+- Simple products (1-2 variants): Add first variant
+- Fashion/apparel with sizes: Require size selection (redirect or Quick View)
+- Complex products (3+ variant types): Redirect to product page
+
+**Button behavior:**
+- Loading state ("Adding..."), disable during loading
+- Optimistic UI update (cart count immediately)
+- Success feedback (toast, cart popup, or checkmark)
+- **Don't navigate away** (stay on listing page)
+- Handle errors (out of stock, API failure)
+
+**Wishlist button (optional)**: Heart icon, top-right over image. Empty when not saved, filled (red) when saved. Refer to wishlist.md for more details.
+
+## Badges and Labels
+
+**Badge priority** (show max 1-2 per card):
+
+1. **Out of Stock** (highest) - Gray/black overlay on image, disables add-to-cart
+2. **Sale/Discount** - "Sale" or "-20%", red/accent, top-left corner
+3. **New** - "New" for recent products, blue/green, top-left corner
+4. **Low Stock** (optional) - "Only 3 left", orange, creates urgency
+
+**Display**: Top-left corner (except Out of Stock overlay), small but readable, high contrast.
+
+## Mobile Considerations
+
+### Grid Layout
+
+**Mobile-specific adjustments:**
+- 2 columns maximum on mobile (never 3+)
+- Larger touch targets (44px minimum for buttons)
+- Always show "Add to Cart" button (no hover-only)
+- Simplified content (hide optional elements like brand)
+- Smaller images for performance (<400px wide)
+
+### Touch Interactions
+
+**No hover states on mobile:**
+- Don't hide actions behind hover
+- Always show primary button
+- Use tap states (active state) instead of hover
+
+## Ecommerce Checklist
+
+**Essential features:**
+
+- [ ] Clear product image (optimized, lazy loaded)
+- [ ] Product title (truncated to 2 lines max)
+- [ ] Price prominently displayed
+- [ ] Sale price shown correctly (struck-through original price)
+- [ ] Currency symbol included
+- [ ] For Medusa: Price displayed as-is (not divided by 100)
+- [ ] Add to Cart button with loading state
+- [ ] Variant handling strategy (first variant, redirect, or Quick View)
+- [ ] Optimistic UI update (cart count immediately)
+- [ ] Success feedback (toast or cart popup)
+- [ ] Don't navigate away after adding to cart
+- [ ] Out of Stock badge (disables add-to-cart)
+- [ ] Sale badge when price reduced
+- [ ] Responsive grid (1 col mobile, 2-3 tablet, 3-4 desktop)
+- [ ] Touch-friendly on mobile (44px buttons)
+- [ ] Keyboard accessible (focus states, Enter to activate)
+- [ ] Descriptive alt text on images
+- [ ] Semantic HTML (`<article>` wrapper)

package/skills/storefront-best-practices/reference/components/product-reviews.md

@@ -0,0 +1,217 @@
+# Product Reviews Component
+
+## Contents
+
+- [Overview](#overview)
+- [Review Display Patterns](#review-display-patterns)
+- [Rating Summary and Distribution](#rating-summary-and-distribution)
+- [Sorting and Filtering](#sorting-and-filtering)
+- [Review Submission](#review-submission)
+- [Trust Signals](#trust-signals)
+- [SEO Integration](#seo-integration)
+
+## Overview
+
+Product reviews build trust and influence purchase decisions. Reviews with ratings convert 270% better than products without.
+
+**Assumed knowledge**: Claude knows how to build forms and display lists. This guide focuses on ecommerce review patterns and trust signals.
+
+### Key Requirements
+
+- Star rating summary (1-5 stars) with distribution
+- Individual reviews with ratings, text, author, date
+- Sorting (Most Recent, Most Helpful, Highest/Lowest Rating)
+- Filtering by rating (5 stars only, 4+ stars)
+- Verified purchase badges
+- Helpful votes (upvote system)
+- Review submission form
+- Mobile-optimized
+
+## Review Display Patterns
+
+### Placement
+
+**On product page:**
+- Below product details (after add-to-cart)
+- Before related products
+- Anchor link in product info: "★★★★★ (127 reviews)"
+
+**Separate reviews page:**
+- Only for very large catalogs (500+ reviews)
+- Link: "View All Reviews"
+- Most stores show reviews inline on product page
+
+## Rating Summary and Distribution
+
+### Average Rating Display
+
+**Show prominently:**
+- Average rating: "★★★★★ 4.5 out of 5"
+- Total review count: "Based on 127 reviews"
+- Large stars (24-32px)
+
+### Rating Distribution (CRITICAL)
+
+**Visual breakdown with clickable bars:**
+```
+5 ★ [████████████████████] 82 (65%)
+4 ★ [██████░░░░░░░░░░░░░░] 25 (20%)
+3 ★ [██░░░░░░░░░░░░░░░░░░] 10 (8%)
+2 ★ [█░░░░░░░░░░░░░░░░░░░] 5 (4%)
+1 ★ [█░░░░░░░░░░░░░░░░░░░] 5 (3%)
+```
+
+**Make bars clickable:**
+- Click to filter reviews by rating
+- Shows only selected star ratings
+- "Show all" to reset filter
+
+**Why distribution matters:**
+- Perfect 5.0 rating seems fake (customers trust 4.2-4.5 average)
+- Showing negative reviews builds trust
+- Distribution helps customers understand product quality
+
+### No Reviews State
+
+**When no reviews:**
+- "No reviews yet"
+- "Be the first to review this product"
+- "Write a Review" button prominent
+- Don't show 0 stars or empty rating
+
+## Sorting and Filtering
+
+### Sort Options (CRITICAL)
+
+**Essential sorting:**
+- **Most Recent** (default) - shows latest feedback
+- **Most Helpful** (by upvotes) - surfaces best reviews
+- **Highest Rating** (5 stars first) - see positive feedback
+- **Lowest Rating** (1 star first) - see concerns
+
+**Dropdown selector:**
+```
+Sort by: [Most Recent ▾]
+```
+
+### Filter Options
+
+**Filter by rating:**
+- All ratings (default)
+- 5 stars only
+- 4+ stars
+- 3 stars or less (see negative feedback)
+
+**Filter by criteria:**
+- Verified purchases only (highest trust)
+- With photos only (visual proof)
+- Recent (last 30 days, 6 months)
+
+**Show filtered count:**
+- "Showing 24 of 127 reviews"
+
+## Review Submission
+
+### Review Form Fields
+
+**Required:**
+- Star rating (1-5 stars selector)
+- Review text (textarea, 50-500 characters)
+- Reviewer name (if not logged in)
+
+**Optional:**
+- Review title/headline
+- Upload images (2-5 max)
+- Would you recommend? (Yes/No)
+
+**Form placement:**
+- "Write a Review" button opens modal or inline form
+- Position near rating summary
+
+### Form Validation
+
+**Requirements:**
+- Rating must be selected
+- Minimum review length (50 characters)
+- Show character counter: "50 / 500 characters"
+- Validate before submit
+
+**Success:**
+- "Thank you for your review!"
+- "Your review is pending approval" (if moderation enabled)
+
+## Trust Signals
+
+### Verified Purchase Badge (CRITICAL)
+
+**Display:**
+- Badge or checkmark: "✓ Verified Purchase"
+- Position near reviewer name
+- Green color or checkmark icon
+- Only for confirmed customers
+
+**Why it matters:**
+- Builds trust (real customer, not fake)
+- Reduces suspicion of paid reviews
+- Higher credibility
+
+### Helpful Votes
+
+**Upvote/downvote system:**
+- "Was this review helpful?"
+- [👍 Yes (24)] [👎 No (2)]
+- Click to vote (one vote per user)
+- Powers "Most Helpful" sorting
+
+**Benefits:**
+- Surfaces most useful reviews
+- Community validation
+- Reduces impact of unhelpful reviews
+
+### Review Images (Optional)
+
+Customer-uploaded photos (3-4 max per review, 60-80px thumbnails, click to enlarge). Visual proof increases trust and engagement.
+
+### Store Responses (Recommended)
+
+Seller replies below original review (indented, light gray background). Respond to negative reviews professionally - shows you care, addresses concerns without being defensive.
+
+## SEO Integration
+
+**AggregateRating Schema (CRITICAL):** Add structured data to show star ratings in search results. Include `ratingValue` (avg rating), `reviewCount`, `bestRating` (5), `worstRating` (1).
+
+**SEO benefits:** Star ratings in search results, higher CTR, rich snippets. See seo.md for implementation details.
+
+**Important:** Only include if reviews are real. Fake reviews violate Google guidelines.
+
+## Display Patterns
+
+**Individual review card:**
+Star rating (16-20px) + text + reviewer name (first name + initial) + date + verified badge + helpful votes. Truncate long reviews (200-300 chars) with "Read more".
+
+**Mobile:**
+Single column, touch-friendly votes (44px), full-screen sort select, filter bottom sheet, "Load more" pagination.
+
+## Checklist
+
+**Essential features:**
+
+- [ ] Star rating summary (average + count)
+- [ ] Rating distribution bar chart (5 to 1 stars)
+- [ ] Clickable bars to filter by rating
+- [ ] Sort dropdown (Most Recent, Most Helpful, Highest/Lowest)
+- [ ] Filter options (verified, with photos, by rating)
+- [ ] Individual reviews with: stars, text, name, date
+- [ ] Verified purchase badge
+- [ ] Helpful votes (upvote/downvote)
+- [ ] Review submission form (rating, text)
+- [ ] Form validation (minimum length, required rating)
+- [ ] "Read more" for long reviews
+- [ ] Store responses to reviews (recommended)
+- [ ] Review images (customer uploads, optional)
+- [ ] Mobile: Touch targets 44px minimum
+- [ ] Pagination or "Load more" button
+- [ ] No reviews state ("Be the first to review")
+- [ ] AggregateRating structured data (SEO)
+- [ ] ARIA labels for star ratings
+- [ ] Keyboard accessible (all interactions)

package/skills/storefront-best-practices/reference/components/product-slider.md

@@ -0,0 +1,174 @@
+# Product Slider Component
+
+## Contents
+
+- [Overview](#overview)
+- [When to Use Product Sliders](#when-to-use-product-sliders)
+- [Slider Patterns](#slider-patterns)
+- [Product Display](#product-display)
+- [Navigation Controls](#navigation-controls)
+- [Mobile Sliders](#mobile-sliders)
+- [Performance](#performance)
+- [Checklist](#checklist)
+
+## Overview
+
+Product slider (carousel) displays multiple products horizontally with navigation to scroll through them. Used for related products, recently viewed, bestsellers, and featured products.
+
+**Assumed knowledge**: AI agents know how to build carousels with navigation. This focuses on ecommerce product slider patterns.
+
+**Key requirements:**
+- Horizontal scrolling of product cards
+- Arrow navigation (prev/next)
+- Optional dot indicators
+- Mobile: Swipe gesture support
+- Responsive product count (4-6 visible desktop, 2-3 mobile)
+- Lazy loading for off-screen products
+
+## When to Use Product Sliders
+
+**Use for:**
+- Related products (product page)
+- Recently viewed (product page, homepage)
+- "You May Also Like" (product page)
+- Bestsellers / Featured products (homepage)
+- "Frequently Bought Together" (product page)
+- New arrivals (homepage)
+- Category showcases (homepage)
+
+**Don't use for:**
+- Main product images (use gallery instead)
+- Critical content (not all users scroll/swipe)
+- Checkout flow (keep linear)
+- Primary navigation (use grid for discoverability)
+
+## Slider Patterns
+
+**Continuous scroll:**
+- Shows 4-6 products at once (desktop)
+- Scroll left/right by 1-2 products at a time
+- Smooth animated transition (300-400ms)
+- Most common pattern
+
+**Infinite loop (optional):**
+- Wraps to beginning after end
+- Good for small product sets (<10 items)
+- Creates continuous browsing feel
+- Not necessary for large sets
+
+**Snap to alignment:**
+- Products snap to grid after scroll
+- Prevents partial product visibility
+- Better visual alignment
+- Improves browsing experience
+
+**Auto-play (NOT recommended for products):**
+- Automatic scrolling without user action
+- Poor UX for product sliders (users lose control)
+- Only use for promotional banners/hero images
+- If using: Pause on hover, slow speed (5-7s)
+
+## Product Display
+
+**Product cards in sliders:**
+- Same cards as product grids (see product-card.md)
+- Simplified on mobile (less detail, smaller images)
+- Image, title, price minimum
+- Optional: Rating, "Add to Cart" (desktop only)
+- Adequate spacing between cards (16-24px)
+
+**Responsive display:**
+- Large desktop (>1440px): 5-6 products visible
+- Desktop (1024-1440px): 4-5 products
+- Tablet (768-1024px): 3-4 products
+- Mobile (<768px): 2 products (sometimes 1.5 for scroll hint)
+
+**Scroll hint on mobile:**
+- Show 1.5 products (partial visibility of next)
+- Indicates more content to swipe
+- Improves discoverability
+- Better than showing exact 2 products
+
+## Navigation Controls
+
+**Arrow buttons:**
+- Left/right arrows outside slider
+- Desktop: Always visible or show on hover
+- Mobile: Hidden (swipe gesture preferred)
+- Position: Vertically centered
+- Size: 40-48px touch targets
+- Disable left arrow at start, right arrow at end (no infinite loop)
+
+**Dot indicators (optional):**
+- Show progress through slider
+- Each dot = one "page" of products
+- Position: Below slider, centered
+- Small (8-12px dots)
+- Only if many products (>12)
+- Less common for product sliders (more for hero carousels)
+
+**Keyboard navigation:**
+- Tab through visible product cards
+- Arrow keys scroll slider (optional)
+- Focus management on scroll
+
+## Mobile Sliders
+
+**Touch gestures:**
+- Horizontal swipe to scroll
+- Native scroll momentum
+- Snap to product alignment
+- No arrow buttons (swipe is intuitive)
+
+**Mobile-specific adjustments:**
+- 2 products visible (or 1.5 for hint)
+- Larger touch targets on products
+- Remove hover-only features (Quick View)
+- Faster scroll animations (200-300ms)
+
+**Performance on mobile:**
+- Lazy load off-screen products
+- Smaller image sizes
+- Limit initial products loaded (8-10)
+- Load more on scroll
+
+## Performance
+
+**Lazy loading (critical):**
+- Only load visible products initially
+- Load adjacent products (left/right) on demand
+- Significantly improves page load time
+- Use Intersection Observer API
+
+**Image optimization:**
+- Responsive images (smaller for mobile)
+- WebP format with fallback
+- Lazy load off-screen images
+- Optimized thumbnails (<300KB)
+
+**Limit slider length:**
+- Max 20-30 products per slider
+- "View All" link to full category page
+- Improves performance
+- Prevents endless scrolling
+
+## Checklist
+
+**Essential features:**
+- [ ] 4-6 products visible (desktop), 2 (mobile)
+- [ ] Arrow navigation (desktop)
+- [ ] Swipe gesture (mobile)
+- [ ] Product cards with image, title, price
+- [ ] Responsive product count
+- [ ] Smooth scroll transitions (300-400ms)
+- [ ] Snap to product alignment
+- [ ] Lazy load off-screen products
+- [ ] "View All" link if many products (>20)
+- [ ] Disable arrows at start/end
+- [ ] Keyboard accessible (Tab through products)
+- [ ] Mobile: No arrows, swipe only
+- [ ] Optimized images (<300KB)
+- [ ] Spacing between products (16-24px)
+- [ ] ARIA labels on navigation (`aria-label="Previous products"`)
+- [ ] `role="region"` on slider container
+- [ ] NO auto-play for product sliders

package/skills/storefront-best-practices/reference/components/search.md

@@ -0,0 +1,101 @@
+# Search Component
+
+## Contents
+
+- [Overview](#overview)
+- [Search Placement](#search-placement)
+- [Autocomplete and Product Suggestions](#autocomplete-and-product-suggestions)
+- [Search Results Page](#search-results-page)
+- [Empty States](#empty-states)
+- [Recent and Popular Searches](#recent-and-popular-searches)
+- [Mobile Search](#mobile-search)
+
+## Overview
+
+Search is critical for ecommerce - users with search intent convert at higher rates. Provide fast, relevant product discovery with autocomplete.
+
+**Assumed knowledge**: AI agents know how to build search inputs with icons and clear buttons. This guide focuses on ecommerce search patterns.
+
+### Key Requirements
+
+- Prominent search input (always accessible)
+- Instant autocomplete after 2-3 characters
+- Product suggestions with images
+- Fast, relevant search results
+- Filters to refine results
+- Empty state guidance
+- Mobile full-screen search modal
+
+## Search Placement
+
+**Desktop**: Navbar center (between logo and cart) or right side. Always visible, 300-500px width. Part of sticky navbar. Never hide in hamburger menu.
+
+**Mobile**: Magnifying glass icon in top-right (44x44px minimum). Opens full-screen modal - eliminates distractions, maximizes suggestion space, better typing experience.
+
+## Autocomplete and Product Suggestions
+
+**Show suggestions** after 2-3 characters (not 1). Debounce 300ms to prevent excessive API calls.
+
+**Display 5-10 product suggestions:**
+- Small image (40-60px), title, price
+- Clickable to product page
+- Optional: Category/brand suggestions, popular terms
+- Divide sections with headers
+- "View all results for [query]" footer link
+
+**Backend integration**: Fetch from search API. Check with ecommerce platform's documentation for API reference.
+
+## Search Results Page
+
+**Header**: "Search Results for '[query]'" + result count ("24 products found"). Search bar visible and pre-filled for refining.
+
+**Grid layout**: Same as product listings (see product-listing.md). 1-4 columns based on device.
+
+**Sorting**: Relevance (default, unique to search), Price Low/High, Newest.
+
+**Filters**: Sidebar (desktop) or drawer (mobile). Category, Price, Brand, Availability with result counts.
+
+## Empty States
+
+**No results**: "No results for '[query]'" with helpful suggestions (check spelling, try broader keywords, browse categories). "Browse All Products" button + links to popular categories.
+
+**Loading state**: Product card skeletons (6-8 cards), minimum 300ms display to avoid flashing.
+
+## Recent and Popular Searches
+
+**Recent searches** (user-specific, localStorage): Show 3-5 recent searches when input focused (before typing). Helps re-search without retyping.
+
+**Popular searches** (site-wide, from backend): Show 5-10 trending terms when focused. Pill/tag styling.
+
+Display both on: Empty input focus (desktop dropdown), mobile modal open.
+
+## Mobile Search
+
+**Full-screen modal pattern:**
+- Header: Back button (44x44px) + search input (48px height, auto-focus, `type="search"`)
+- Content: Recent/popular searches (empty), autocomplete (typing), scrollable
+- Close: Back button, device back gesture, Escape key
+
+## Ecommerce Search Checklist
+
+**Essential features:**
+
+- [ ] Prominent search input in navbar (desktop)
+- [ ] Search icon clearly visible (mobile)
+- [ ] Full-screen modal on mobile tap
+- [ ] Autocomplete after 2-3 characters
+- [ ] Debounced API calls (300ms)
+- [ ] Product suggestions with images, prices
+- [ ] "View all results" link in dropdown
+- [ ] Search results page shows query
+- [ ] Result count displayed
+- [ ] Sort by Relevance (default for search)
+- [ ] Filters for refining results (category, price, brand)
+- [ ] Empty state with helpful guidance
+- [ ] Loading state indicator (skeleton)
+- [ ] Recent searches (localStorage)
+- [ ] Popular searches (from backend)
+- [ ] Mobile: Auto-focus, large input (48px)
+- [ ] Keyboard navigation (arrow keys, Enter, Escape)
+- [ ] ARIA labels (`role="search"`, `aria-label`)
+- [ ] Accessible to screen readers