@thorprovider/create-storefront 0.1.1

package/skills/storefront-best-practices/reference/layouts/static-pages.md

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

package/skills/storefront-best-practices/reference/medusa.md

@@ -0,0 +1,307 @@
+# Medusa Backend Integration
+
+## Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [SDK Setup](#sdk-setup)
+- [Vite Configuration](#vite-configuration-tanstack-start-vite-projects)
+- [TypeScript Types](#typescript-types)
+- [Price Display](#price-display)
+- [SDK Organization](#sdk-organization)
+- [Critical Medusa Patterns](#critical-medusa-patterns)
+- [Region State Management](#region-state-management)
+
+## Overview
+
+Guide for connecting your storefront to Medusa backend using the [Medusa JS SDK](https://docs.medusajs.com/resources/js-sdk).
+
+**When to use this guide:**
+- Building a storefront with Medusa backend
+- Need to integrate Medusa SDK properly
+- Working with multi-region stores
+- Handling Medusa-specific pricing and regions
+
+**For general backend patterns**, see `reference/connecting-to-backend.md`.
+
+## ⚠️ CRITICAL: Follow the 5-Step Verification Workflow
+
+**BEFORE writing code that calls Medusa SDK methods**, follow the mandatory workflow from SKILL.md:
+
+1. **PAUSE** - Don't write code yet
+2. **QUERY** MCP server or docs (https://docs.medusajs.com/resources/js-sdk) for exact method
+3. **VERIFY** with user what you found
+4. **WRITE** code using verified method
+5. **CHECK** for TypeScript errors - Type errors mean wrong method name or parameters
+
+**If you see TypeScript errors on SDK methods, you used incorrect methods. Go back to Step 2 and verify again.**
+
+**This file shows PATTERNS (what to do), not exact methods (how to do it). Always verify method names with MCP/docs before use.**
+
+## 💡 RECOMMENDED: Set Up Medusa MCP Server
+
+**If the Medusa MCP server is not installed, strongly recommend setting it up.**
+
+**Setup instructions**: add HTTP MCP server with URL https://docs.medusajs.com/mcp
+
+The MCP server provides real-time method verification without leaving your IDE.
+
+## Installation
+
+```bash
+npm install @medusajs/js-sdk@latest @medusajs/types@latest
+```
+
+Both required: SDK provides functionality, types provide TypeScript support.
+
+## SDK Setup
+
+```typescript
+import Medusa from "@medusajs/js-sdk"
+
+export const sdk = new Medusa({
+  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL || "http://localhost:9000",
+  debug: process.env.NODE_ENV === "development",
+  publishableKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+})
+```
+
+**CRITICAL: Always set publishableKey.**
+
+- Required for multi-region stores to get correct pricing
+- Required for accessing products with regional prices
+- Without it, product queries may fail or return incorrect prices
+- Get publishable key from Medusa admin dashboard under Settings → Publishable API Keys
+
+**IMPORTANT: Storefront Port Configuration**
+
+- **Run storefront at port 8000** to avoid CORS errors
+- Medusa backend's default CORS configuration expects storefront at `http://localhost:8000`
+- If using different port, configure CORS in Medusa backend's `medusa-config.ts`:
+  ```typescript
+  store_cors: process.env.STORE_CORS || "http://localhost:YOUR_PORT"
+  ```
+- Common framework defaults:
+  - Next.js: Port 3000 (needs CORS config update)
+  - TanStack Start: Port 3000 (needs CORS config update)
+  - Vite: Port 5173 (needs CORS config update)
+  - **Recommended**: Use port 8000 to avoid configuration changes
+
+## Vite Configuration (TanStack Start, Vite Projects)
+
+**IMPORTANT: For Vite-based projects, configure SSR externals.**
+
+Add this to your `vite.config.ts`:
+
+```typescript
+export default defineConfig({
+  // ... other config
+  ssr: {
+    noExternal: ['@medusajs/js-sdk'],
+  },
+})
+```
+
+**Why this is needed:**
+- Medusa JS SDK must be processed by Vite during SSR
+- Without this config, SDK calls will fail during server-side rendering
+- Applies to TanStack Start, vanilla Vite, and other Vite-based frameworks
+
+## TypeScript Types
+
+**IMPORTANT: Always use `@medusajs/types` - never define custom types.**
+
+```typescript
+import type {
+  StoreProduct,
+  StoreCart,
+  StoreCartLineItem,
+  StoreRegion,
+  StoreProductCategory,
+  StoreCustomer,
+  StoreOrder
+} from "@medusajs/types"
+```
+
+**Why use official types:**
+- Complete and accurate type definitions
+- Updated with each Medusa release
+- Includes all entity relationships and fields
+- Prevents type mismatches with API responses
+
+## Price Display
+
+**CRITICAL: Medusa prices are stored as-is - DO NOT divide by 100.**
+
+Unlike Stripe (where amounts are in cents), Medusa stores prices in their display value.
+
+```typescript
+// ❌ WRONG - Dividing by 100
+<div>${product.variants[0].prices[0].amount / 100}</div>
+
+// ✅ CORRECT - Display as-is
+<div>${product.variants[0].prices[0].amount}</div>
+```
+
+**Correct price formatting:**
+```typescript
+const formatPrice = (amount: number, currencyCode: string) => {
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: currencyCode,
+  }).format(amount)
+}
+```
+
+**Price fields to use:**
+- `variant.calculated_price.calculated_amount` - Final price including promotions
+- `variant.calculated_price.original_amount` - Original price before discounts
+- Both are already in display format - no conversion needed
+
+## SDK Organization
+
+The Medusa SDK is organized by resources:
+- `sdk.store.product.*` - Product operations
+- `sdk.store.cart.*` - Cart operations
+- `sdk.store.category.*` - Category operations
+- `sdk.store.customer.*` - Customer operations (authenticated)
+- `sdk.store.order.*` - Order operations (authenticated)
+- `sdk.store.payment.*` - Payment operations
+- `sdk.store.fulfillment.*` - Shipping/fulfillment operations
+- `sdk.store.region.*` - Region operations
+
+**To find specific methods**: Consult documentation (https://docs.medusajs.com/resources/js-sdk) or use MCP server.
+
+## Critical Medusa Patterns
+
+**IMPORTANT**: The patterns below show WHAT to do, not exact HOW. Always verify method names and signatures with MCP server or documentation before using.
+
+### 1. Always Pass `region_id` for Products
+
+**Pattern**: Product queries require `region_id` parameter for correct pricing.
+
+**Why:** Without `region_id`, `calculated_price` will be missing or incorrect.
+
+**To implement**: Query MCP/docs for product listing and retrieval methods. Pass `region_id: selectedRegion.id` as parameter.
+
+### 2. Cart Updates Pattern
+
+**Pattern**: Line items have dedicated methods (create, update, delete). Other cart properties use a generic update method.
+
+**Line item operations** (verify exact method names with MCP/docs):
+- Add item to cart
+- Update item quantity
+- Remove item from cart
+
+**Other cart updates** (email, addresses, region, promo codes):
+- Use cart's generic update method
+
+**To implement**: Query MCP server or documentation for exact cart method signatures:
+https://docs.medusajs.com/resources/references/js-sdk/store/cart
+
+### 3. Payment Flow Pattern
+
+**High-level workflow:**
+1. Query available payment providers for the cart's region
+2. User selects payment method
+3. Initialize payment session for selected provider
+4. Render provider-specific UI (Stripe Elements, etc.)
+5. Complete payment through provider
+
+**To implement**: Query MCP/docs for:
+- Payment provider listing method
+- Payment session initialization method
+- Payment completion method
+
+**Resources**:
+- MCP server (if installed)
+- Medusa payment docs: https://docs.medusajs.com/resources/references/js-sdk/store/payment
+- `reference/layouts/checkout.md` for checkout flow
+
+### 4. Checkout Flow Pattern
+
+**High-level workflow:**
+1. Collect shipping address
+2. Query available shipping options for cart
+3. User selects shipping method
+4. Collect payment information
+5. Initialize payment session
+6. Complete/place order
+
+**To implement**: Query MCP/docs for each step's methods. Don't guess method names.
+
+### 5. Category Fetching
+
+**Pattern**: Fetch categories from `sdk.store.category.*` resource.
+
+**To implement**: Query MCP/docs for category listing method. See `reference/components/navbar.md` for usage patterns.
+
+## Region State Management
+
+**Critical for Medusa**: Region determines currency, pricing, taxes, and available products.
+
+### Why Region Context Matters
+
+Medusa requires region for:
+- Creating carts (must pass `region_id`)
+- Retrieving products with correct prices
+- Determining currency and tax calculations
+- Filtering available payment and shipping methods
+
+### Implementation Approach
+
+**High-level workflow:**
+1. Fetch available regions on app load (query MCP/docs for region listing method)
+2. Detect user's country (IP, browser locale, or user selection)
+3. Find region containing that country
+4. Store selected region globally (React Context, Zustand, etc.)
+5. Use `selectedRegion.id` for all cart and product operations
+
+**When user changes country:**
+- Find new region containing the country
+- Update cart with new region_id (query MCP/docs for cart update method)
+- Store selection in localStorage for persistence
+
+**To implement**: Query MCP server or docs for exact region and cart methods. Don't copy example code without verification.
+
+**For detailed region implementation with code examples**, see:
+- `reference/components/country-selector.md`
+- Medusa MCP server (if installed)
+- Medusa docs: https://docs.medusajs.com/resources/storefront-development/regions/context
+
+## Error Handling
+
+SDK throws `FetchError` with:
+- `status`: HTTP status code
+- `statusText`: Error code
+- `message`: Descriptive message
+
+```typescript
+try {
+  const data = await sdk.store.customer.retrieve()
+} catch (error) {
+  const fetchError = error as FetchError
+  if (fetchError.statusText === "Unauthorized") {
+    redirect('/login')
+  }
+}
+```
+
+## Custom Endpoints
+
+For custom API routes:
+
+```typescript
+const data = await sdk.client.fetch(`/custom/endpoint`, {
+  method: "POST",
+  body: { /* ... */ },
+})
+```
+
+## Resources
+
+- **Medusa JS SDK docs**: https://docs.medusajs.com/resources/js-sdk
+- **Storefront development**: https://docs.medusajs.com/resources/storefront-development
+- **Checkout flow**: https://docs.medusajs.com/resources/storefront-development/checkout
+- **Region context**: https://docs.medusajs.com/resources/storefront-development/regions/context
+- **Use Medusa MCP server** if available for real-time method lookup