version: "1.0.0" name: storefront-best-practices description: "Always use this skill when working on ecommerce storefronts, online stores, or shopping sites. Use it for any storefront component: checkout pages, cart, payment flows, product pages, product listings, navigation, homepage. Load it when you add checkout, implement a cart, integrate the Medusa backend, or build any ecommerce function. Framework-agnostic (Next.js, SvelteKit, TanStack Start, React, Vue). Provides patterns, decision frameworks, and backend integration guidance."

Ecommerce Storefront Best Practices

Guidance for building ecommerce storefronts covering UI/UX patterns, component design, layout structures, SEO, and mobile responsiveness.

When to Apply

Load this skill for every 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 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 you create 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
• Adding forms, CTAs, filters, cart/checkout steps, or engagement UX? → MUST load reference/analytics.md and instrument Matomo in the same change (consent-gated; no PII)
• 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
• Planning or changing critical checkout/payment behavior? → MUST also load references/checkout-e2e-delivery.md; establish the disposable real-stack Playwright test and failing acceptance path before production code
• Choosing a payment provider or adding PayPal/Klarna/multi-provider? → load references/payment-provider-architecture.md; Hyperswitch (@juspay-tech/medusa-custom-payments + medusa-custom-payments-react) is the recommended unified solution for 3+ providers
• 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 keeps implementation consistent

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 the fold - Do not 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 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

Analytics (Matomo)

• Always instrument new funnel/engagement UX (forms, filters, checkout steps, CTAs) — see reference/analytics.md and repo AGENTS.md (Matomo analytics)
• Consent-gated only; no PII in event payloads; major-unit prices; purchases only on order confirmation

⚠️ CRITICAL: Backend SDK Method Verification Workflow

You must follow this exact workflow before you write code that connects to a 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. It 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
• ❌ Declaring an endpoint broken from a 404/400 without checking the exact path the

installed SDK version calls. SDK paths change across major versions — e.g. Medusa 2.x moved store customer auth from /store/auth/... (v1) to /auth/{actor}/{provider}; a 404 on the old path is expected, not a backend bug (false finding, 2026-08-11: "customer auth broken" was actually a v1-path probe; /auth/customer/emailpass returned 401 = alive). Diagnosis mode: before filing a backend bug, grep the installed SDK for the real path — grep -rn "fetch(\/auth/" node_modules/@medusajs/js-sdk/dist/esm` (or the equivalent resource client) — then probe THAT path. For auth, a 401 with bad creds proves route + provider are registered; only a 404 on the v2 path means unmounted.

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 - never create static pages for individual items
• Product pages: Use dynamic routes like /products/[handle] or /products/$handle, NOT /products/shirt.tsx
• Category pages: Use dynamic routes like /categories/[handle] or /categories/$handle, NOT /categories/women.tsx
• Framework-specific patterns:
• Next.js App Router: app/products/[handle]/page.tsx or app/products/[id]/page.tsx
• Next.js Pages Router: pages/products/[handle].tsx
• SvelteKit: routes/products/[handle]/+page.svelte
• TanStack Start: routes/products/$handle.tsx
• Remix: routes/products.$handle.tsx
• Why: Dynamic routes scale to any number of products/categories without creating individual files
• Static routes are unmaintainable and don't scale (imagine creating 1000 product files)

Pattern Selection Guides

When you need to choose between implementation patterns, load the relevant reference file:

• Checkout strategy (single-page vs multi-step) → Load reference/layouts/checkout.md
• Navigation strategy (dropdown vs megamenu) → Load reference/components/navbar.md and reference/components/megamenu.md
• Product listing strategy (pagination vs infinite scroll vs load more) → Load reference/layouts/product-listing.md
• Search strategy (autocomplete vs filters vs natural language) → Load reference/components/search.md
• Mobile vs desktop priorities → Load reference/mobile-responsiveness.md
• Variant selection (text vs swatches vs configurator) → Load reference/layouts/product-details.md
• Cart pattern (popup vs drawer vs page navigation) → Load reference/components/cart-popup.md and reference/layouts/cart.md
• Trust signals strategy → Load reference/layouts/product-details.md and reference/layouts/checkout.md

Each reference file contains decision frameworks with specific criteria to help you choose the right pattern for your context.

Quick Reference

General

reference/connecting-to-backend.md    - Framework detection, API setup, backend integration patterns
reference/medusa.md                    - Medusa SDK integration, pricing, regions, TypeScript types
reference/design.md                    - User preferences, brand identity, design systems
reference/seo.md                       - Meta tags, structured data, Core Web Vitals
reference/mobile-responsiveness.md     - Mobile-first design, responsive breakpoints, touch interactions

Components

reference/components/navbar.md         - Desktop/mobile navigation, logo, menu, cart icon, load for ALL pages
reference/components/megamenu.md       - Category organization, featured products, mobile alternatives
reference/components/cart-popup.md     - Add-to-cart feedback, mini cart display
reference/components/country-selector.md - Country/region selection, currency, pricing, Medusa regions
reference/components/breadcrumbs.md    - Category hierarchy, structured data markup
reference/components/search.md         - Search input, autocomplete, results, filters
reference/components/product-reviews.md - Review display, rating aggregation, submission
reference/components/hero.md           - Hero layouts, CTA placement, image optimization
reference/components/popups.md         - Newsletter signup, discount popups, exit-intent
reference/components/footer.md         - Content organization, navigation, social media, load for ALL pages
reference/components/product-card.md   - Product images, pricing, add to cart, badges
reference/components/product-slider.md - Carousel implementation, mobile swipe, accessibility

Layouts

reference/layouts/home-page.md         - Hero, featured categories, product listings
reference/layouts/product-listing.md   - Grid/list views, filters, sorting, pagination
reference/layouts/product-details.md   - Image gallery, variant selection, related products
reference/layouts/cart.md              - Cart items, quantity updates, promo codes
reference/layouts/checkout.md          - Multi-step/single-page, address forms, payment
reference/layouts/order-confirmation.md - Order number, summary, delivery info
reference/layouts/account.md           - Dashboard, order history, address book
reference/layouts/static-pages.md      - FAQ, about, contact, shipping/returns policies

Features

reference/features/wishlist.md         - Add to wishlist, wishlist page, move to cart
reference/features/promotions.md       - Promotional banners, discount codes, sale badges

Common Implementation Patterns

Starting a New Storefront

IMPORTANT: For each step below, load the referenced files before you implement that step.

1. Discovery Phase → Read design.md for user preferences
2. Foundation Setup → Read connecting-to-backend.md (or medusa.md for Medusa), mobile-responsiveness.md, seo.md
3. Core Components → Implement navbar.md, footer.md
4. Home Page → Read home-page.md
5. Product Browsing → Read product-listing.md, product-card.md, search.md
6. Product Details → Read product-details.md, product-reviews.md
7. Cart & Checkout → Read cart-popup.md, cart.md, checkout.md, order-confirmation.md
8. User Account → Read account.md
9. Additional Features → Read wishlist.md, promotions.md
10. Optimization → SEO audit (seo.md), mobile testing (mobile-responsiveness.md)

Even if you create an implementation plan, refer back to the skill and load relevant reference files when implementing each step.

Shopping Flow Pattern

Browse → View → Cart → Checkout
 
Browse:   home-page.md → product-listing.md
View:     product-details.md + product-reviews.md
Cart:     cart-popup.md → cart.md
Checkout: checkout.md → order-confirmation.md

Component Selection Guide

For product grids and filtering → product-listing.md and product-card.md For product cards → product-card.md For navigation → navbar.md and megamenu.md For search functionality → search.md For checkout flow → checkout.md For promotions and sales → promotions.md

Design Considerations

Before implementing, consider:

1. User preferences - Read design.md to discover design style preferences
2. Brand identity - Colors, typography, tone that match the brand
3. Target audience - B2C vs B2B, demographics, device usage
4. Product type - Fashion vs electronics vs groceries affect layout choices
5. Business requirements - Multi-currency, multi-language, region-specific
6. Backend system - API structure affects component implementation

Integration with Medusa

Medusa is an ecommerce backend. Consider Medusa when:

• Building a new ecommerce storefront
• Need a headless commerce solution
• Want built-in support for multi-region, multi-currency
• Need powerful promotion and discount engine
• Require flexible product modeling

For detailed Medusa integration guidance, see reference/medusa.md. For general backend patterns, see reference/connecting-to-backend.md.

Framework Agnostic

All guidance is framework-agnostic. Examples use React/TypeScript where code demonstrations are helpful, but patterns apply to:

• Next.js
• SvelteKit
• Tanstack Start
• Any modern frontend framework

Minimum Viable Features

Mandatory for launch (core shopping flow):

• Navbar with cart, categories, search
• Product listing with filtering and pagination
• Product details with variant selection
• Add to cart functionality
• Cart page with item management
• Checkout flow (shipping, payment, review)
• Order confirmation page

Nice-to-have (add if time permits):

• Related products recommendations
• Product reviews and ratings
• Wishlist functionality
• Image zoom on product pages
• Bottom navigation on mobile
• Mega-menu for navigation
• Newsletter signup
• Product comparison
• Quick view modals

User-dependent (ask before implementing):

• Guest checkout vs login-required
• Account dashboard features
• Multi-language support
• Multi-currency support
• Live chat support

Top Ecommerce Mistakes to Avoid

Before implementing, watch out for these common ecommerce-specific pitfalls:

1. Cart and Navigation Mistakes

• ❌ Hiding cart indicator in mobile hamburger menu (keep always visible)
• ❌ Not showing real-time cart count updates
• ❌ CRITICAL: Missing `aria-live="polite"` on cart count - Screen readers won't announce cart updates without it
• ❌ Not displaying variant details (size, color, etc.) in cart popup - only showing product title
• ❌ Megamenu closes when hovering over dropdown content (must stay open when hovering trigger OR dropdown)
• ❌ CRITICAL: Megamenu positioning errors - Three common mistakes:
• ❌ Navbar doesn't have position: relative (megamenu won't position correctly)
• ❌ Megamenu positioned relative to trigger button instead of navbar (use absolute left-0 on megamenu)
• ❌ Megamenu doesn't span full width (must use right-0 or w-full, not just w-auto)
• ❌ Hardcoding categories, featured products, or any dynamic content instead of fetching from backend
• ❌ No clear indication of current page in category navigation

2. Product Browsing Mistakes

• ❌ Creating static routes for products/categories (use dynamic routes like /products/[handle] instead of /products/shirt.tsx)
• ❌ Missing "no products found" empty state with helpful suggestions
• ❌ No loading indicators while fetching products
• ❌ Pagination without SEO-friendly URLs (for search engines)
• ❌ Filter selections that don't persist on page reload

3. Product Details Mistakes

• ❌ Enabling "Add to Cart" before variant selection (size, color, etc.)
• ❌ Missing product images optimization (large uncompressed images)
• ❌ Navigating away from product page after adding to cart (stay on page)
• ❌ Using emojis in UI instead of icons or images (unprofessional, accessibility issues)

4. Design and Consistency Mistakes

• ❌ CRITICAL: Not loading `reference/design.md` before creating any UI component - Leads to inconsistent colors, fonts, and styles
• ❌ Introducing new colors without checking existing theme first
• ❌ Adding new fonts without verifying what's already used
• ❌ Using arbitrary Tailwind values when theme tokens exist
• ❌ Not detecting Tailwind version (v3 vs v4) - Causes syntax errors

5. Checkout and Conversion Mistakes

• ❌ Requiring account creation to checkout (offer guest checkout if backend supports it)
• ❌ Not fetching payment methods from backend - assuming available payment options or skipping payment method selection
• ❌ Overly complex multi-step checkout (4+ steps kills conversion) - Optimal is 3 steps: Shipping Info, Delivery Method + Payment, Review
• ❌ Missing trust signals (secure checkout badge, return policy link)
• ❌ Not handling out-of-stock errors gracefully during checkout

6. Mobile Experience Mistakes

• ❌ Touch targets smaller than 44x44px (buttons, links, form fields)
• ❌ Desktop-style hover menus on mobile (use tap/click instead)
• ❌ Not optimizing images for mobile (loading huge desktop images)
• ❌ Missing mobile-specific patterns (bottom nav, drawer filters)

7. Performance and SEO Mistakes

• ❌ Missing structured data (Product schema) for SEO
• ❌ No explicit image lazy loading (don't assume browser defaults) - Always add loading="lazy" to images below the fold
• ❌ Missing meta tags and Open Graph for social sharing
• ❌ Not optimizing Core Web Vitals (LCP, FID, CLS) - Use PageSpeed Insights or Lighthouse to measure

8. Backend Integration Mistakes

• ❌ Writing code that calls backend APIs/SDKs without following the 5-step verification workflow - You must: 1) pause, 2) query docs/MCP, 3) verify with user, 4) write code, 5) check for type errors
• ❌ Ignoring TypeScript errors on SDK methods - Type errors mean you used wrong method names or parameters. Go back and verify with docs/MCP
• ❌ Guessing API method names, SDK methods, or parameters - Always verify exact method signatures before use
• ❌ Not using Medusa MCP server when available - If using Medusa backend, always query MCP server for methods
• ❌ Copying code examples without verifying they are current - Examples may be outdated, always verify first
• ❌ Not detecting which backend is being used (check monorepo, ask user if unsure)
• ❌ Assuming API structure without checking backend documentation or MCP server
• ❌ Hardcoding dynamic content (categories, regions, products, etc.) instead of fetching from backend
• ❌ Defining custom types for Medusa entities instead of using @medusajs/types package
• ❌ Initializing Medusa SDK without publishable API key (required for multi-region stores and product pricing)
• ❌ Fetching Medusa products without passing region_id query parameter (causes missing or incorrect pricing)
• ❌ Showing all countries in Medusa checkout - should only show countries from cart's region
• ❌ Dividing Medusa prices by 100 (Medusa stores prices as-is, not in cents like Stripe)
• ❌ Missing Vite SSR config for Medusa SDK (add ssr.noExternal: ['@medusajs/js-sdk'] to vite.config.ts)
• ❌ Running Medusa storefront on port other than 8000 (causes CORS errors - Medusa backend expects port 8000 by default)
• ❌ Not handling loading, error, and empty states for API calls
• ❌ Making API calls on client-side that should be server-side (SEO, security)
• ❌ Not implementing proper error messages ("Error occurred" vs "Product out of stock")
• ❌ Missing cache invalidation (stale product data, prices, inventory)
• ❌ Not clearing cart state after order is placed - Cart popup shows old items because cart wasn't reset from Context/localStorage/cache