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:

• Refer back to this skill before starting implementation

• Load relevant reference files listed above for the specific component/page you're building

• Follow the patterns and guidance in the reference files

• 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 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 - 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 implementing 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:

• User preferences - Read design.md to discover design style preferences

• Brand identity - Colors, typography, tone that match the brand

• Target audience - B2C vs B2B, demographics, device usage

• Product type - Fashion vs electronics vs groceries affect layout choices

• Business requirements - Multi-currency, multi-language, region-specific

• Backend system - API structure affects component implementation

Integration with Medusa

Medusa is a modern, flexible 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

• ❌ ERROR: 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

• ❌ ERROR: Ignoring TypeScript errors on SDK methods - Type errors mean you used wrong method names or parameters. Go back and verify with docs/MCP

• ❌ ERROR: Guessing API method names, SDK methods, or parameters - Always verify exact method signatures before use

• ❌ ERROR: Not using Medusa MCP server when available - If using Medusa backend, always query MCP server for methods

• ❌ ERROR: Copying code examples without verifying they're 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