storefront-best-practices

What this skill does

# Ecommerce Storefront Best Practices

Comprehensive guidance for building modern, high-converting ecommerce storefronts covering UI/UX patterns, component design, layout structures, SEO optimization, and mobile responsiveness.

## When to Apply

**ALWAYS load this skill when working on ANY storefront task:**

- **Adding checkout page/flow** - Payment, shipping, order placement
- **Implementing cart** - Cart page, cart popup, add to cart functionality
- **Building product pages** - Product details, product listings, product grids
- **Creating navigation** - Navbar, megamenu, footer, mobile menu
- **Integrating Medusa backend** - SDK setup, cart, products, payment
- **Any storefront component** - Homepage, search, filters, account pages
- Building new ecommerce storefronts from scratch
- Improving existing shopping experiences and conversion rates
- Optimizing for usability, accessibility, and SEO
- Designing mobile-responsive ecommerce experiences

**Example prompts that should trigger this skill:**
- "Add a checkout page"
- "Implement shopping cart"
- "Create product listing page"
- "Connect to Medusa backend"
- "Add navigation menu"
- "Build homepage for store"

## CRITICAL: Load Reference Files When Needed

**⚠️ ALWAYS load `reference/design.md` BEFORE creating ANY UI component**
- Discovers existing design tokens (colors, fonts, spacing, patterns)
- Prevents introducing inconsistent styles
- Provides guardrails for maintaining brand consistency
- **Required for every component, not just new storefronts**

**Load these references based on what you're implementing:**

- **Starting a new storefront?** → MUST load `reference/design.md` first to discover user preferences
- **Connecting to backend API?** → MUST load `reference/connecting-to-backend.md` first
- **Connecting to Medusa backend?** → MUST load `reference/medusa.md` for SDK setup, pricing, regions, and Medusa patterns
- **Implementing homepage?** → MUST load `reference/components/navbar.md`, `reference/components/hero.md`, `reference/components/footer.md`, and `reference/layouts/home-page.md`
- **Implementing navigation?** → MUST load `reference/components/navbar.md` and optionally `reference/components/megamenu.md`
- **Building product listing?** → MUST load `reference/layouts/product-listing.md` first
- **Building product details?** → MUST load `reference/layouts/product-details.md` first
- **Implementing checkout?** → MUST load `reference/layouts/checkout.md` first
- **Optimizing for SEO?** → MUST load `reference/seo.md` first
- **Optimizing for mobile?** → MUST load `reference/mobile-responsiveness.md` first

**Minimum requirement:** Load at least 1-2 reference files relevant to your specific task before implementing.

## Planning and Implementation Workflow

**IMPORTANT: If you create a plan for implementing storefront features, include the following in your plan:**

When implementing each component, page, layout, or feature in the plan:
1. **Refer back to this skill** before starting implementation
2. **Load relevant reference files** listed above for the specific component/page you're building
3. **Follow the patterns and guidance** in the reference files
4. **Check common mistakes** sections to avoid known pitfalls

**Example plan structure:**

```
Task 1: Implement Navigation
- Load reference/components/navbar.md
- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)
- Refer to skill for common mistakes (e.g., hardcoding categories)

Task 2: Implement Product Listing Page
- Load reference/layouts/product-listing.md
- Follow pagination/filtering patterns from product-listing.md
- Use reference/components/product-card.md for product grid items
- Check skill for backend integration guidance

Task 3: Implement Checkout Flow
- Load reference/layouts/checkout.md
- Load reference/medusa.md for Medusa payment integration
- Follow component architecture recommendations (separate step components)
- Refer to skill for payment method fetching requirements
```

**Why this matters:**
- Plans provide high-level strategy
- Reference files provide detailed implementation patterns
- Skill file contains critical mistakes to avoid
- Following this workflow ensures consistency and best practices

## Critical Ecommerce-Specific Patterns

### Accessibility
- **CRITICAL: Cart count updates require `aria-live="polite"`** - Screen readers won't announce without it
- Ensure keyboard navigation for all cart/checkout interactions

### Mobile
- **Sticky bottom elements MUST use `env(safe-area-inset-bottom)`** - iOS home indicator will cut off purchase buttons otherwise
- 44px minimum touch targets for cart actions, variant selectors, quantity buttons

### Performance
- **ALWAYS add `loading="lazy"` to product images below fold** - Don't rely on browser defaults
- Optimize product images for mobile (<500KB) - Most ecommerce traffic is mobile

### Conversion Optimization
- Clear CTAs throughout shopping flow
- Minimal friction in checkout (guest checkout if supported)
- Trust signals (reviews, security badges, return policy) near purchase buttons
- Clear pricing and shipping information upfront

### SEO
- **Product schema (JSON-LD) required** - Critical for Google Shopping and rich snippets
- Use [PageSpeed Insights](https://pagespeed.web.dev/) to measure Core Web Vitals

### Visual Design
- **NEVER use emojis** in storefront UI - Use icons or images instead (unprofessional, accessibility issues)

### Backend Integration
- **Backend detection**: If in monorepo, check for backend directory. If unsure, ask user which backend is used.
- **NEVER hardcode dynamic content**: Always fetch categories, regions, products, shipping options, etc. from backend - they change frequently
- Never assume API structure - verify endpoints and data formats

### ⚠️ CRITICAL: Backend SDK Method Verification Workflow

**YOU MUST FOLLOW THIS EXACT WORKFLOW BEFORE WRITING CODE THAT CONNECTS TO BACKEND:**

**Step 1: PAUSE - Do NOT write code yet**
- You are about to write code that calls a backend API or SDK method (e.g., Medusa SDK, REST API, GraphQL)
- **STOP** - Do not proceed to code without verification

**Step 2: QUERY the documentation or MCP server**
- **If MCP server available**: Query it for the exact method (for example, medusa MCP)
- **If no MCP server**: Search official documentation
- **Find**: Exact method name, parameters, return type

**Step 3: VERIFY what you found**
- State out loud to the user: "I need to verify the correct method for [operation]. Let me check [MCP server/documentation]."
- Show the user what you found: "According to [source], the method is `sdk.store.cart.methodName(params)`"
- Confirm the method signature and parameters

**Step 4: ONLY THEN write the code**
- Now you can write code using the verified method
- Use the exact signature you found

**Step 5: CHECK for TypeScript errors**
- After writing the code, check for any TypeScript/type errors related to the SDK
- If you see type errors on SDK methods, it means you used an incorrect method name or wrong parameters
- **Type errors are a sign you didn't verify correctly** - Go back to Step 2

**THIS IS NOT OPTIONAL - THIS IS MANDATORY ERROR PREVENTION**

**It is a CRITICAL ERROR to:**
- ❌ Write code that calls backend APIs/SDKs without explicitly querying docs/MCP first
- ❌ Guess method names or parameters
- ❌ Ignore TypeScript errors on SDK methods (errors indicate incorrect method usage)
- ❌ Copy examples from this skill without verification (examples may be outdated)
- ❌ Assume SDK methods match REST API endpoints

**For Medusa specifically:**
- **Medusa pricing**: Display prices as-is - DO NOT divide by 100 (unlike Stripe, Medusa stores prices in display format)
- **Medusa MCP server**: https://docs.medusajs.com/mcp - Recommend setup if not installed
- Load `reference/medusa.md` for Medusa-specific patterns (regions, pricing, etc.)

### Routing Patterns
- **ALWAYS use dynamic routes** for products and categories - NEV