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

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