medusajs/medusa-agent-skills/storefront-best-practices

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
• Making a storefront agent-friendly (AI shopping agents, AI search, agentic commerce)

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"
• "Make my store agent-ready / AI-friendly"

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
• Making the store agent-friendly, or building product pages, add-to-cart, search, footer, robots.txt, sitemap or structured data? → MUST load reference/agent-friendly.md
• 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 to measure Core Web Vitals

Agent-Friendliness

AI agents (ChatGPT, Claude, Perplexity, browser agents) shop on behalf of users. Most don't run JavaScript. Load reference/agent-friendly.md for full guidance. Top rules:

• Product name, visible price with currency and stock status MUST be in the server HTML - verify with curl
• Add-to-cart MUST be a named `<button type="submit">` inside a `<form method="post" action="...">`; variant selectors MUST be native radios/<select> inside that form
• Search MUST work at a GET URL (/search?q=) with server-rendered results
• Don't block AI agents (robots.txt, middleware, CAPTCHA on home/PDP/cart, gates replacing content)
• Unknown product handles MUST return 404, not 200 or a homepage redirect

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)
• Docs 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/agent-friendly.md            - AI agent access, machine-readable product data, operable forms, llms.txt, UCP
reference/mobile-responsiveness.md     - Mobile-first design, responsive breakpoints, touch interactions

Components