@thorprovider/storefront 0.3.1

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

@@ -0,0 +1,123 @@
+# Breadcrumbs Component
+
+## Contents
+
+- [Overview](#overview)
+- [When to Use Breadcrumbs](#when-to-use-breadcrumbs)
+- [Ecommerce Breadcrumb Patterns](#ecommerce-breadcrumb-patterns)
+- [Mobile Breadcrumbs](#mobile-breadcrumbs)
+- [SEO Structured Data](#seo-structured-data)
+- [Checklist](#checklist)
+
+## Overview
+
+Breadcrumbs show the user's location within the site hierarchy (Home → Category → Subcategory → Product). Critical for ecommerce navigation and SEO.
+
+**Assumed knowledge**: AI agents know how to build breadcrumbs with separators and links. This guide focuses on ecommerce-specific patterns.
+
+### Key Requirements
+
+- Show full path from homepage to current page
+- Each level clickable (except current page)
+- Position below navbar, above page title
+- Include structured data for SEO (JSON-LD)
+- Mobile-optimized (back link pattern)
+
+## When to Use Breadcrumbs
+
+**Use for:**
+- Product pages (Home → Category → Subcategory → Product)
+- Category pages (Home → Category → Subcategory)
+- Deep site hierarchies (3+ levels)
+- Large catalogs with many categories
+
+**Don't use for:**
+- Homepage (no parent pages)
+- Flat site structures (1-2 levels)
+- Checkout flow (linear, not hierarchical)
+- Search results (not hierarchical)
+
+## Ecommerce Breadcrumb Patterns
+
+### Product Page Breadcrumbs
+
+**Standard pattern:**
+- Home / Category / Subcategory / Product Name
+- Example: Home / Electronics / Laptops / Gaming Laptop Pro
+
+**Key considerations:**
+- All levels except product name are clickable
+- Product name is current page (non-clickable, darker text)
+- Shows product's location in catalog
+
+**Multiple category membership:**
+- If product in multiple categories, choose primary/canonical
+- Match category in URL or navigation path
+- Be consistent across site
+
+### Category Page Breadcrumbs
+
+**Standard pattern:**
+- Home / Parent Category / Current Category
+- Example: Home / Electronics / Laptops
+
+**Current category:**
+- Non-clickable (plain text)
+- Visually distinct from links (darker or bold)
+
+### Path Construction
+
+**Hierarchy:**
+- Start with "Home" (or home icon)
+- Follow category hierarchy
+- End with current page
+- Maximum 5-6 levels (keep shallow)
+
+**URL alignment:**
+- Breadcrumb path should match URL hierarchy
+- Consistent naming between URLs and breadcrumbs
+- Example: `/categories/electronics/laptops` → "Home / Electronics / Laptops"
+
+## Mobile Breadcrumbs
+
+### Mobile Pattern: Collapse to Back Link
+
+**Recommended approach:**
+- Show only previous level as back link
+- Back arrow icon (←) + parent page name
+- Example: "← Gaming Laptops"
+
+**Why:**
+- Saves vertical space on mobile
+- Clear affordance (back navigation)
+- Simpler than full breadcrumb trail
+- Mobile users have device back button
+
+**Alternative: Truncated path**
+- Show "Home ... Current Page"
+- Hide middle levels
+- Balances space and context
+
+## SEO Structured Data
+
+**BreadcrumbList schema (CRITICAL)**: Add JSON-LD structured data. Breadcrumbs appear in search results, improves CTR, helps search engines understand site structure.
+
+**Implementation**: schema.org BreadcrumbList with items array. Each item has position (1, 2, 3...), name, and URL. See seo.md for schema details.
+
+## Checklist
+
+**Essential features:**
+
+- [ ] Positioned below navbar, above page title
+- [ ] Full path shown (Home → Category → Product)
+- [ ] All levels clickable except current page
+- [ ] Current page visually distinct (non-clickable, darker)
+- [ ] Clear separators (›, /, > or chevron)
+- [ ] Mobile: Back link pattern ("← Category")
+- [ ] Structured data (JSON-LD BreadcrumbList)
+- [ ] Semantic HTML (`<nav aria-label="Breadcrumb">`)
+- [ ] `aria-current="page"` on current item
+- [ ] Keyboard accessible (tab through links)
+- [ ] Truncate long labels (20-30 characters max)
+- [ ] Consistent with navigation labels
+- [ ] Maximum 5-6 levels deep

package/skills/storefront-best-practices/reference/components/cart-popup.md

@@ -0,0 +1,189 @@
+# Cart Popup Component
+
+## Contents
+
+- [Overview](#overview)
+- [When to Show Cart Popup](#when-to-show-cart-popup)
+- [Layout Patterns](#layout-patterns)
+- [Cart Display](#cart-display)
+- [Actions and CTAs](#actions-and-ctas)
+- [Empty State](#empty-state)
+- [Mobile Considerations](#mobile-considerations)
+- [Checklist](#checklist)
+
+## Overview
+
+Cart popup (mini cart/cart drawer) shows quick cart overview without navigating away. Opens from cart icon click or after adding items.
+
+**⚠️ CRITICAL: Always display variant details (size, color, material, etc.) in cart popup, not just product titles.**
+
+**Assumed knowledge**: AI agents know how to build modals, dialogs, and overlays. This focuses on ecommerce-specific patterns.
+
+**Cart popup vs full cart page:**
+- Popup: Quick overview, fast checkout path, continue shopping easily
+- Full page: Detailed review, promo codes, complex operations
+- **Recommended**: Both - popup for speed, full cart page for details
+
+## When to Show Cart Popup
+
+**Trigger options:**
+
+1. **On cart icon click** (always) - Click cart icon in navbar opens popup
+2. **After adding to cart** (recommended) - Auto-open popup when item added, confirms action, allows checkout or continue shopping
+3. **Hover cart icon** (desktop only, optional) - Quick peek on hover. Can be accidental, not recommended.
+
+**Add-to-cart feedback alternatives:**
+- Show popup (most common) - Immediate confirmation, clear path to checkout
+- Toast only (less intrusive) - Small notification, user clicks cart icon to see details
+- Navigate to cart page (traditional) - Goes directly to full cart page, less common now
+
+## Layout Patterns
+
+**Two common patterns:**
+
+**1. Dropdown (recommended for simplicity):**
+- Drops down from cart icon, positioned below navbar
+- Width: 280-320px, max height with scroll
+- No backdrop overlay (click outside to close)
+- Better for few items, simpler implementation
+
+**2. Slide-in drawer (more prominent):**
+- Slides from right, full height, width 320-400px (desktop) or 80-90% (mobile)
+- Semi-transparent backdrop overlay (click to close)
+- Better for multiple items or complex carts
+
+**Both patterns have:**
+- Header: Title + item count + close button (optional for dropdown)
+- Scrollable content: List of cart items
+- Sticky footer: Subtotal + action buttons (Checkout, View Cart)
+
+## Cart Display
+
+**Fetch cart data from backend:**
+- Cart ID from localStorage
+- Line items (products, variants, quantities, prices)
+- Cart totals (subtotal, tax, shipping)
+- See connecting-to-backend.md for backend integration
+
+**When to fetch:**
+- On app initialization (update cart icon badge)
+- On popup open (show loading state)
+- After cart updates (add/remove/change quantity)
+
+**State management:**
+- Store cart data globally (React Context or TanStack Query)
+- Persist cart ID in localStorage
+- Optimistic UI updates (update immediately, revert on error)
+- **CRITICAL: Clear cart state after order is placed** - See connecting-to-backend.md for cart cleanup pattern
+- Common issue: Cart popup shows old items after checkout because cart state wasn't cleared
+- See connecting-to-backend.md for cart state patterns
+
+**Cart item display:**
+
+**CRITICAL: Always show variant details (size, color, material, etc.) for each cart item.**
+
+Without variant details, users can't confirm they added the correct variant. This is especially critical when products have multiple options.
+
+- Product image (60-80px thumbnail)
+- Product title (truncated to 2 lines)
+- **Variant details (REQUIRED)**: Size, color, material, or other variant options
+  - Format: "Size: Large, Color: Black" or "Large / Black"
+  - Show ALL selected variant options, not just product title
+  - Display below title, smaller text (gray)
+- Quantity controls (+/- buttons, debounce 300-500ms)
+- Unit price and total price (line item total = price × quantity)
+- Remove button (X icon, no confirmation needed)
+
+**Why variant details are critical:**
+- User confirmation: "Did I add the right size?"
+- Prevents cart abandonment from uncertainty
+- Allows corrections before checkout
+- Essential for products with multiple variants (clothing, shoes, configurable products)
+
+## Actions and CTAs
+
+**Cart summary display:**
+- Subtotal (sum of all items)
+- Shipping and tax: "Calculated at checkout" or actual amount
+- Total: Bold and prominent
+
+**Free shipping indicator (optional):**
+- "Add $25 more for free shipping" with progress bar
+- Encourages larger orders, updates as cart changes
+
+**Promo codes:**
+- Usually NOT in cart popup (too cramped)
+- Reserve for full cart page
+- Exception: Simple code input if space permits
+
+**Action buttons:**
+1. **Checkout** (primary) - Most prominent, high contrast (brand color), navigates to checkout
+2. **View Cart** (secondary) - Outline or subtle, navigates to full cart page
+
+Both buttons full-width, 44-48px height on mobile.
+
+## Empty State
+
+Show icon/illustration + "Your cart is empty" + "Continue Shopping" button. Centered, friendly, minimal design.
+
+## Loading and Error States
+
+**On popup open**: Show skeleton/placeholder while fetching (avoid blank screen)
+
+**During updates**:
+- Quantity changes: Inline spinner, disable controls, debounce 300-500ms
+- Item removal: Fade out animation, disable remove button during request
+- Add to cart: Loading indicator on button ("Adding...")
+
+**Error handling**:
+- Network errors: Show retry option, don't close popup
+- Invalid cart ID: Create new cart automatically
+- Out of stock: Disable quantity increase, show message
+- Revert optimistic updates on failure
+
+**Animations**: Smooth transitions (250-350ms), slide-in drawer, backdrop fade-in/out. Highlight newly added items.
+
+## Mobile Considerations
+
+**Dropdown on mobile:**
+- Full-width (100% minus margins)
+- Max height 60-70% viewport, scrollable
+- Tap outside to close
+
+**Drawer on mobile:**
+- 85-95% screen width or full screen
+- Slides from right or bottom
+- Swipe to close gesture supported
+- Backdrop overlay
+
+**Mobile adjustments:**
+- Large touch targets (44-48px minimum)
+- Full-width action buttons (48-52px height)
+- Smaller images (60px), truncate titles
+- Sticky footer with actions
+- Large close button (44x44px)
+
+## Checklist
+
+**Essential features:**
+- [ ] Opens on cart icon click
+- [ ] Dropdown (280-320px) or drawer (320-400px) layout
+- [ ] Close button or click outside to close
+- [ ] Backdrop overlay if drawer
+- [ ] **CRITICAL: Cart items show variant details (size, color, etc.) - not just product title**
+- [ ] Cart items with image, title, variant options, quantity, prices
+- [ ] Quantity controls (+/- buttons, debounced)
+- [ ] Remove item button
+- [ ] Subtotal displayed
+- [ ] Checkout button (primary)
+- [ ] View Cart button (secondary)
+- [ ] Empty state with "Continue Shopping" CTA
+- [ ] Loading states (skeleton/spinner)
+- [ ] Smooth animations (250-350ms)
+- [ ] Mobile: Full-width dropdown or 85-95% drawer
+- [ ] Touch targets 44-48px minimum
+- [ ] `role="dialog"` and `aria-modal="true"`
+- [ ] ARIA labels on cart button ("Shopping cart with 3 items")
+- [ ] Keyboard accessible (focus trap, Escape closes, return focus)
+- [ ] Screen reader announcements (item added/removed)
+- [ ] Real-time cart count badge updates

package/skills/storefront-best-practices/reference/components/country-selector.md

@@ -0,0 +1,298 @@
+# Country Selector Component
+
+## Contents
+
+- [Overview](#overview)
+- [When to Implement](#when-to-implement)
+- [UI Patterns](#ui-patterns)
+- [State Management](#state-management)
+- [Backend Integration](#backend-integration)
+- [Detection and Defaults](#detection-and-defaults)
+- [Mobile Considerations](#mobile-considerations)
+- [Checklist](#checklist)
+
+## Overview
+
+Country selector allows customers to choose their country/region, which determines currency, pricing, available products, shipping options, payment methods, and localized content.
+
+### Key Ecommerce Functions
+
+- Display prices in correct currency
+- Show country-specific product availability
+- Apply region-specific promotions and discounts
+- Calculate accurate shipping costs and delivery times
+- Enable appropriate payment methods
+- Display localized content and language
+
+### Purpose
+
+**Why country/region selection matters:**
+- Prices vary by region (currency, taxes, import fees)
+- Product availability differs by market
+- Shipping methods and costs are region-specific
+- Legal requirements vary (privacy, consumer protection)
+- Payment methods differ by country
+- Improves user experience with relevant content
+
+## When to Implement
+
+**Implement country selector when:**
+- Backend supports multiple countries or regions
+- Selling to multiple countries or regions
+- Prices vary by location (currency, taxes)
+- International shipping with different rates
+- Region-specific product catalogs
+- Multi-currency support needed
+- Legal or regulatory requirements vary by region
+
+**Skip if:**
+- Backend doesn't support multiple countries or regions
+- All prices in one currency
+- No regional differences in catalog or pricing
+
+## UI Patterns
+
+### Placement Options
+
+**Footer placement (modern and minimal):**
+- Bottom of page in footer
+- Less prominent but always accessible
+- Icon (flag or globe) + country code/name
+
+**Header placement (most common):**
+- Top-right of navigation bar
+- Icon (flag or globe) + country code/name
+- Click opens dropdown or modal selector
+
+**Modal/popup on first visit:**
+- Detect location and suggest country
+- Allow user to confirm or change
+- Store preference for future visits
+
+### Selector Design Patterns
+
+**Pattern 1: Dropdown (Recommended)**
+
+Small, compact selector in header. Shows current country flag/name, click to open dropdown with country list.
+
+**Pros:** Doesn't interrupt browsing, always accessible, familiar pattern.
+
+**Pattern 2: Modal on First Visit**
+
+Full-screen or centered modal on first visit. "Select your country to see accurate prices and shipping."
+
+**Pros:** Forces initial selection, ensures accurate pricing from start.
+**Cons:** Can be intrusive, delays browsing.
+
+**Tradeoff:** Modal ensures selection but adds friction. Dropdown is less intrusive but users may miss it.
+
+**Pattern 3: Inline Banner**
+
+Sticky banner at top: "Shipping to United States? Change" with link to selector.
+
+**Pros:** Non-intrusive reminder, doesn't block content.
+**Cons:** Takes vertical space, easy to ignore.
+
+### Country List Display
+
+**Search + list:**
+- Search input at top
+- Alphabetical country list below
+- Popular countries at top (US, UK, Canada, etc.)
+- Flag icons for visual recognition
+
+**Grouped by region:**
+- North America, Europe, Asia, etc.
+- Collapsible sections
+- Helpful for large lists (100+ countries)
+
+**Format:**
+```
+🇺🇸 United States (USD)
+🇬🇧 United Kingdom (GBP)
+🇨🇦 Canada (CAD)
+───────────────────
+🇩🇪 Germany (EUR)
+🇫🇷 France (EUR)
+```
+
+Show flag, country name, and currency code for clarity.
+
+## State Management
+
+### Storing Country Selection
+
+**Client-side storage (recommended):**
+- localStorage or cookies
+- Persists across sessions
+- Key: `region_id` or `country_code`
+
+**Why local storage:**
+- Fast access without API call
+- Available immediately on page load
+- No server round-trip needed
+
+### Context Provider Pattern
+
+**Recommended: Create context for region/country data.**
+
+Provides quick access throughout the app to:
+- Selected country
+- Selected region (if applicable)
+- Currency
+- Available payment methods
+- Shipping options
+
+**Benefits:**
+- Centralized country/region logic
+- Easy access from any component
+- Single source of truth
+- Simplified cart and product queries
+
+**Example structure:**
+```typescript
+interface RegionContext {
+  country: string
+  region?: string
+  currency: string
+  changeCountry: (country: string) => void
+}
+```
+
+### When to Apply Selection
+
+**Apply country/region to:**
+- Product price display (convert currency, apply regional pricing)
+- Cart creation (set region for accurate totals)
+- Product queries (retrieve accurate pricing)
+- Checkout flow (shipping methods, payment options)
+- Content display (language, measurements)
+
+## Backend Integration
+
+### General Backend Requirements
+
+**What backend needs to provide:**
+- List of available countries/regions
+- Mapping of countries to regions (if using regional structure)
+- Pricing per region or country
+- Product availability by region
+- Shipping methods by region
+- Supported payment methods by region
+
+**API considerations:**
+- Fetch country/region list on app load
+- Pass selected country/region to product queries
+- Include region in cart creation
+- Validate country selection on backend
+
+### Medusa Backend Integration
+
+**For Medusa users, regions are critical for accurate pricing.**
+
+Medusa uses regions (not individual countries) for pricing. A region can contain multiple countries.
+
+**Key concepts:**
+- **Region**: Group of countries with shared pricing (e.g., "Europe" region)
+- **Country**: Individual country within a region
+- **Currency**: Each region has one currency
+
+**Mapping country to region:**
+1. Customer selects country (e.g., "Germany")
+2. Find which region contains that country (e.g., "Europe" region)
+3. Store region ID for cart and product operations
+4. Use region for all pricing queries
+
+**Required for:**
+- Creating carts: Must pass region ID
+- Retrieving products: Pass region to get accurate prices
+- Product availability: Products may be region-specific
+
+**Implementation pattern:**
+Create a context that stores both country and region. When country changes, look up corresponding region and update both.
+
+**For detailed Medusa region implementation, see:**
+- Medusa storefront regions documentation: https://docs.medusajs.com/resources/storefront-development/regions/context
+- Medusa JS SDK regions endpoints
+- Consult Medusa MCP server for real-time API details
+
+**Other backends:**
+Check the ecommerce backend's documentation for country/region handling patterns.
+
+## Detection and Defaults
+
+### Auto-Detection
+
+**IP-based geolocation (recommended):**
+Detect user's country from IP address. Use as default but allow user to change.
+
+**Implementation:**
+- Use geolocation API or service (MaxMind, ipapi.co, CloudFlare)
+- Server-side detection (more accurate)
+- Set as default, show confirmation: "Shipping to United States?"
+
+**Benefits:** Reduces friction, most users keep detected country.
+
+**Tradeoff:** Not 100% accurate (VPNs, proxies). Always allow manual override.
+
+### Fallback Strategy
+
+**If detection fails or unavailable:**
+1. Check localStorage for previous selection
+2. Use browser language as hint (`navigator.language`)
+3. Default to primary market (e.g., US for US-based store)
+4. Prompt user to select on first interaction (cart, checkout)
+
+**Never block browsing if country unknown.**
+Allow browsing with default pricing, prompt selection before checkout.
+
+## Mobile Considerations
+
+**Selector placement:**
+Mobile hamburger menu or bottom of page. Top-right in mobile header if space allows.
+
+**Modal selector:**
+Full-screen modal on mobile for country selection. Large touch targets (48px), search input at top, easy scrolling.
+
+**Sticky reminder:**
+Small banner: "Shipping to US? Change" with tap to open selector.
+
+**Detection prompt:**
+Bottom sheet: "We detected you're in Germany. Is this correct?" with Confirm/Change buttons.
+
+## Checklist
+
+**Essential features:**
+
+- [ ] Country selector visible (header, footer, or first-visit modal)
+- [ ] Current country clearly displayed (flag, name, currency)
+- [ ] Dropdown or modal with country list
+- [ ] Search functionality for long country lists
+- [ ] Popular countries at top of list
+- [ ] Flag icons for visual recognition
+- [ ] Show currency code per country
+- [ ] localStorage persistence (save selection)
+- [ ] Context provider for region/country data
+- [ ] Auto-detection based on IP (optional)
+- [ ] Manual override always available
+- [ ] Apply to product prices (currency, regional pricing)
+- [ ] Apply to cart creation (set region)
+- [ ] Apply to checkout (shipping, payment methods)
+- [ ] Fallback if detection fails
+- [ ] Mobile: Full-screen modal or bottom sheet
+- [ ] Mobile: Large touch targets (48px)
+- [ ] Backend integration (fetch regions, map countries)
+- [ ] For Medusa: Region context with country-to-region mapping
+- [ ] For Medusa: Pass region to cart and product queries
+- [ ] ARIA label on selector button
+- [ ] Keyboard accessible (Tab, Enter, arrows)
+- [ ] Screen reader announces country changes
+
+**Optional enhancements:**
+
+- [ ] Currency conversion display (show original + converted)
+- [ ] Language selector tied to country
+- [ ] Shipping estimate based on country
+- [ ] Tax estimation display
+- [ ] Regional content (images, messaging)
+- [ ] "Not shipping to your country?" alternative