@thorprovider/create-storefront 0.1.1

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

@@ -0,0 +1,241 @@
+# Hero Section Component
+
+## Contents
+
+- [Overview](#overview)
+- [Hero Types and When to Use](#hero-types-and-when-to-use)
+- [Content Guidelines](#content-guidelines)
+- [Multiple Heroes (Carousel)](#multiple-heroes-carousel)
+- [Mobile Hero](#mobile-hero)
+- [Performance](#performance)
+- [Checklist](#checklist)
+
+## Overview
+
+Hero section is the prominent banner at top of homepage, immediately below navigation. First content users see - sets tone for shopping experience.
+
+**Assumed knowledge**: AI agents know how to build full-width banners with images and text overlays. This focuses on ecommerce hero patterns.
+
+**Key requirements:**
+- Above the fold (immediately visible)
+- Clear value proposition or promotional message
+- High-quality imagery
+- Strong call-to-action
+- Fast loading (critical for first impression)
+
+## Hero Types and When to Use
+
+### 1. Full-Width Banner (Most Common)
+
+**Characteristics:**
+- Spans entire viewport width
+- Large background image or video
+- Text overlay with headline + CTA
+- Single focused message
+
+**Best for:**
+- Seasonal campaigns ("Summer Sale")
+- New product arrivals
+- Brand storytelling
+- Single promotional focus
+- Simple, bold message
+
+**Example:** Background image of products, headline "40% Off Summer Sale", CTA "Shop Now"
+
+### 2. Split Hero (Image + Content)
+
+**Characteristics:**
+- 50/50 or 60/40 split layout
+- Image on one side, text content on other
+- No text overlay on image
+- Cleaner, easier to read
+
+**Best for:**
+- Product launches (show product clearly)
+- Detailed messaging (more text space)
+- Accessibility (no text-on-image contrast issues)
+- Professional/B2B stores
+
+**Example:** Product image (left 50%), headline + benefits + CTA (right 50%)
+
+### 3. Minimal Hero
+
+**Characteristics:**
+- Large image, minimal text
+- Image does storytelling
+- Subtle headline, small CTA
+- Emphasis on visual brand
+
+**Best for:**
+- Luxury brands (sophisticated aesthetic)
+- Lifestyle brands (aspirational imagery)
+- Photography-focused products
+- Brand over promotion
+
+### 4. Video Hero
+
+**Characteristics:**
+- Background video (muted, looping)
+- Text overlay on video
+- Fallback image for slow connections
+
+**Best for:**
+- Fashion brands (show products in motion)
+- Lifestyle products (demonstrate usage)
+- High-budget campaigns
+- Brand storytelling with motion
+
+**Important:** Auto-play muted, provide play/pause controls, optimize file size (<5MB), use poster image fallback.
+
+### 5. Product Showcase Hero
+
+**Characteristics:**
+- Multiple featured products in hero
+- Grid of 2-4 products
+- Quick links to product pages
+- Less promotional, more discovery
+
+**Best for:**
+- Multi-category stores
+- Product-focused (not campaign-focused)
+- Quick product discovery
+- Minimal marketing, maximum browsing
+
+## Content Guidelines
+
+**Headline best practices:**
+- Short and impactful (5-10 words)
+- Clear value proposition ("Free Shipping on All Orders")
+- Urgency if time-sensitive ("48-Hour Flash Sale")
+- Benefit-focused ("Upgrade Your Style")
+- Avoid generic ("Welcome to Our Store")
+
+**Subtext (optional):**
+- 10-20 words maximum
+- Expand on headline benefit
+- Add context or details
+- Not always necessary (clean design)
+
+**Call-to-action:**
+- Single primary CTA button
+- Action-oriented text ("Shop Now", "Explore Category", "Get Started")
+- High contrast (stands out on image)
+- Large enough (48px height minimum)
+- Link to relevant landing page (sale, category, product listing)
+
+**Image selection:**
+- High quality, professional photography
+- Shows products or lifestyle context
+- Represents brand aesthetic
+- Optimized for web (<500KB)
+- Responsive (different crops for mobile)
+- Ensure text overlay is readable (adequate contrast)
+
+## Multiple Heroes (Carousel)
+
+**Carousel pattern:**
+- 2-4 slides rotating automatically
+- Each slide = independent hero (own message, image, CTA)
+- Auto-rotate every 5-7 seconds (slow enough to read)
+- Manual controls (prev/next arrows, dot indicators)
+- Pause on hover (accessibility)
+
+**When to use carousel:**
+- Multiple concurrent campaigns (Winter Sale + New Arrivals)
+- Different audience segments (Men/Women/Kids)
+- Seasonal variety showcase
+- Limited above-fold space
+
+**When NOT to use carousel:**
+- Single focused campaign (just use one hero)
+- Users rarely see slides beyond first (carousel blindness)
+- Slower page load (multiple images)
+- Accessibility concerns (auto-rotating content)
+
+**Carousel best practices:**
+- Max 3-4 slides (more = ignored)
+- First slide most important (most viewed)
+- Consistent layout across slides
+- Clear indicators showing progress
+- Don't rely on later slides for critical info
+- Pause on interaction (hover, focus)
+
+## Mobile Hero
+
+**Mobile adjustments (CRITICAL):**
+
+**Layout:**
+- Full-width, portrait aspect (2:3 or 3:4)
+- Vertical composition (text overlays center/bottom)
+- Larger text for readability
+- Simplified message (shorter headline)
+
+**Split hero on mobile:**
+- Stack vertically (image top, text bottom)
+- Don't use side-by-side (too cramped)
+
+**Performance:**
+- Smaller images (<300KB)
+- Different image crop for mobile portrait
+- Use `srcset` or `<picture>` for responsive images
+- Consider static image instead of video (mobile data)
+
+**Touch interactions:**
+- Large CTA button (48px height minimum)
+- Easy carousel controls (if used)
+- Swipe gesture for carousel slides
+
+## Performance
+
+**Critical for first impression:**
+
+**Image optimization:**
+- WebP format with JPEG fallback
+- Lazy load below-fold content (not hero - it's above fold)
+- Responsive images (mobile gets smaller size)
+- Target: <500KB desktop, <300KB mobile
+- Use CDN for faster delivery
+
+**Video optimization:**
+- <5MB file size maximum
+- Muted, autoplay, loop
+- Poster image (shows before video loads)
+- Fallback to image on slow connections
+- Consider not using on mobile (data/performance)
+
+**LCP optimization:**
+- Hero image is often Largest Contentful Paint
+- Preload hero image: `<link rel="preload" as="image" href="hero.jpg">`
+- Inline critical CSS for hero
+- Avoid layout shift (set image dimensions)
+
+**Target metrics:**
+- LCP < 2.5 seconds
+- No layout shift (CLS < 0.1)
+- Fast interaction (hero CTA clickable immediately)
+
+## Checklist
+
+**Essential features:**
+
+- [ ] Above the fold (immediately visible)
+- [ ] Clear headline (5-10 words, value proposition)
+- [ ] High-quality image (professional, on-brand)
+- [ ] Primary CTA button (action-oriented, high contrast)
+- [ ] Fast loading (<500KB image desktop, <300KB mobile)
+- [ ] Responsive images (different sizes/crops for devices)
+- [ ] Mobile: Portrait aspect ratio (2:3 or 3:4)
+- [ ] Mobile: Vertical text placement (center/bottom)
+- [ ] Mobile: Large CTA (48px height minimum)
+- [ ] Text overlay readable (adequate contrast, background overlay)
+- [ ] If carousel: Max 3-4 slides
+- [ ] If carousel: Auto-rotate 5-7 seconds
+- [ ] If carousel: Pause on hover/focus
+- [ ] If carousel: Manual controls (arrows, dots)
+- [ ] If video: Muted, autoplay, loop
+- [ ] If video: Poster image fallback
+- [ ] If video: <5MB file size
+- [ ] Preload hero image (LCP optimization)
+- [ ] No layout shift (set image dimensions)
+- [ ] ARIA labels on carousel controls
+- [ ] Keyboard accessible (Tab to CTA, arrow keys for carousel)

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

@@ -0,0 +1,239 @@
+# Megamenu Component
+
+## Contents
+
+- [Overview](#overview)
+- [When to Use Megamenu](#when-to-use-megamenu)
+- [Content Organization](#content-organization)
+- [Layout Patterns](#layout-patterns)
+- [Trigger Behavior](#trigger-behavior)
+- [Mobile Alternative](#mobile-alternative)
+- [Checklist](#checklist)
+
+## Overview
+
+Megamenu is a large, full-width dropdown navigation showing multiple columns of categories, links, and promotional content. Opens from navbar trigger items (e.g., "Shop", "Men", "Women").
+
+**Assumed knowledge**: AI agents know how to build dropdown menus with hover/click triggers. This focuses on ecommerce megamenu patterns.
+
+**Key requirements:**
+- Full-width display (spans viewport)
+- Multiple columns for categories
+- Positioned directly below navbar
+- Optional promotional images
+- Mobile alternative (hamburger menu, not megamenu)
+
+## When to Use Megamenu
+
+**Use megamenu when:**
+- Large product catalog (10+ top-level categories)
+- Deep hierarchy (parent → child → grandchild levels)
+- Want to showcase featured products/campaigns
+- Multiple segments (Men, Women, Kids, etc.)
+- Visual storytelling needed
+
+**Use simple dropdown when:**
+- Small catalog (<10 categories)
+- Flat category structure (1-2 levels)
+- Text-only navigation sufficient
+- Minimalist design preference
+
+**Common megamenu triggers:**
+- "Shop" (all categories)
+- "Men", "Women", "Kids" (segmented)
+- "New Arrivals" (curated)
+- "Sale" (promotional)
+
+## Content Organization
+
+**Backend Integration (CRITICAL):**
+
+Fetch categories dynamically from ecommerce backend - never hardcode categories. Categories change frequently (new products, seasonal updates, inventory changes). Fetch from API on component mount or during SSR.
+
+**Column structure (3-5 columns recommended):**
+
+**Column 1-3: Category columns**
+- Parent category header (bold, non-clickable or clickable to "View All")
+- Child categories below (clickable links)
+- 5-10 links per column maximum
+- Group related subcategories
+
+**Example:**
+
+```plaintext
+Electronics (header)
+  Laptops
+  Desktops
+  Monitors
+  Accessories
+  View All Electronics
+```
+
+**Column 4-5: Promotional/Featured**
+- Product image card (1-2 featured products)
+- Campaign banner ("Summer Sale", "New Arrivals")
+- "Shop the Look" curated sets
+- Seasonal promotions
+
+**Content limits:**
+
+- Max 5 columns (avoid overcrowding)
+- Max 10 links per column
+- 1-2 promotional images maximum
+- Keep height reasonable (<600px)
+
+## Layout Patterns
+
+### ⚠️ CRITICAL: Megamenu Positioning (Common Mistake)
+
+**Common positioning errors that MUST be avoided:**
+
+❌ **Mistake 1: Navbar doesn't have `position: relative`**
+- Without positioning context on navbar, megamenu won't position correctly
+- Megamenu will position relative to document body instead of navbar
+
+❌ **Mistake 2: Megamenu positioned relative to trigger button**
+- Causes megamenu to appear offset, not aligned to left edge
+- Megamenu won't span full width of navbar
+- Different trigger positions cause inconsistent megamenu placement
+
+❌ **Mistake 3: Megamenu doesn't span full width**
+- Using `width: auto` or no width constraint
+- Missing `left: 0` and `right: 0` properties
+- Results in narrow dropdown instead of full-width panel
+
+---
+
+**REQUIRED positioning pattern:**
+
+**Visual structure:**
+```
+┌─────────────────────────────────────────────────┐
+│ NAVBAR (position: relative)                     │
+│  [Logo]  [Shop ▼]  [Men]  [Women]  [Cart]      │
+└─────────────────────────────────────────────────┘
+  ┌───────────────────────────────────────────────┐
+  │ MEGAMENU (absolute, left: 0, full width)      │
+  │ ┌─────────────────────────────────────────┐   │
+  │ │ Container (centered content)            │   │
+  │ │ [Col1]  [Col2]  [Col3]  [Promo]        │   │
+  │ └─────────────────────────────────────────┘   │
+  └───────────────────────────────────────────────┘
+```
+
+**Required structure:**
+
+1. **Navbar container**
+   - MUST have `position: relative`
+   - Creates positioning context for megamenu
+   - Contains both trigger button and megamenu dropdown
+
+2. **Megamenu dropdown**
+   - MUST have `position: absolute`
+   - MUST have `left: 0` (aligns to left edge of navbar)
+   - MUST have `right: 0` OR `width: 100%` (spans full navbar width)
+   - MUST have `top: 100%` (positioned directly below navbar)
+   - Should have appropriate `z-index` (above content, below modals)
+
+3. **Content wrapper (inside megamenu)**
+   - Use constrained width container (e.g., `max-width`, `container`)
+   - Center content with `margin: 0 auto`
+   - Contains grid/columns for megamenu content
+
+**Why this pattern is mandatory:**
+- Navbar `position: relative` creates positioning context
+- Megamenu `absolute` + `left: 0` + full width ensures consistent, full-width layout
+- Positioning relative to navbar (not trigger) prevents offset issues
+- Inner container centers content while maintaining full-width background
+
+---
+
+### Other Layout Considerations
+
+- Positioned below navbar (no gap)
+- White/light background, boxed padding
+- Shadow or border for depth
+- High z-index (above page content, below modals)
+
+**Column layout:**
+- Equal-width columns or flexible grid
+- Adequate spacing (24-32px between columns)
+- Left-aligned text in category columns
+- Right column(s) for promotional content
+- Responsive: Stack columns on tablet if needed
+
+**Promotional images:**
+- Right-aligned (1-2 columns)
+- Aspect ratio: 2:3 or square
+- Product images or lifestyle photography
+- Clickable to product/category page
+- Include caption or CTA ("Shop Now")
+
+## Trigger Behavior
+
+**Desktop hover (recommended):**
+- Megamenu opens on trigger hover
+- **CRITICAL: Megamenu MUST stay open while hovering over the dropdown content**
+- Stays open while hovering trigger OR dropdown area
+- Closes only when mouse leaves both trigger and dropdown areas
+- Debounce close (200-300ms delay) to prevent accidental closure
+- Smooth fade-in/out transition (200-300ms)
+
+**Why this is critical:**
+- If dropdown closes when moving from trigger to content, users can't access links
+- Frustrating UX - users can't interact with megamenu items
+- Common mistake: Only listening for hover on trigger, not on dropdown
+
+**Desktop click (alternative):**
+- Click trigger to toggle open/close
+- Click outside to close
+- Better for touch-enabled laptops
+- Less accidental openings
+
+**Hover flickering prevention:**
+- No gap between navbar and dropdown
+- Dropdown should slightly overlap navbar
+- Debounce close delay prevents flickering
+
+## Mobile Alternative
+
+**Do NOT use megamenu on mobile:**
+- Too large for mobile screens
+- Hard to navigate multi-column layout
+- Poor touch experience
+
+**Mobile alternative (hamburger menu):**
+- Hamburger icon opens slide-in drawer
+- Vertical accordion for categories
+- Parent category expands to show children
+- Simple, scrollable list
+- See navbar.md for mobile navigation patterns
+
+**Breakpoint:**
+- Megamenu: Desktop only (>1024px)
+- Hamburger: Tablet and mobile (<1024px)
+
+## Checklist
+
+**Essential features:**
+- [ ] Triggered from navbar items ("Shop", segments)
+- [ ] **CRITICAL: Navbar container has `position: relative` (creates positioning context)**
+- [ ] **CRITICAL: Megamenu has `position: absolute` with `left: 0` (NOT positioned relative to trigger button)**
+- [ ] **CRITICAL: Megamenu spans full width (`right: 0` or `w-full`, NOT just `w-auto`)**
+- [ ] **CRITICAL: Megamenu positioned at `top: 100%` or `top-full` (directly below navbar)**
+- [ ] Full-width dropdown below navbar, spans entire navbar width
+- [ ] 3-5 columns for organization
+- [ ] Category hierarchy (parent → children links)
+- [ ] Optional promotional images (1-2)
+- [ ] **CRITICAL: Megamenu stays open when hovering over dropdown content (not just trigger)**
+- [ ] Hover trigger with debounced close (200-300ms)
+- [ ] Smooth fade-in/out transition
+- [ ] No flickering (no gap between navbar and dropdown)
+- [ ] Mobile: Use hamburger menu, NOT megamenu
+- [ ] Keyboard accessible (Tab through links, Escape closes)
+- [ ] `role="navigation"` on dropdown panel
+- [ ] ARIA labels on trigger buttons
+- [ ] Screen reader friendly (announce expand/collapse)
+- [ ] Max 10 links per column
+- [ ] Max 5 columns total
+- [ ] Fetched dynamically from backend (don't hardcode categories)