/storefront-best-practices

name: storefront-best-practices
description: ALWAYS use this skill when working on ecommerce storefronts, online stores, shopping sites. Use for ANY storefront component including checkout pages, cart, payment flows, product pages, product listings, navigation, homepage, or ANY page/component in a storefront. CRITICAL for adding checkout, implementing cart, integrating Medusa backend, making a store agent-friendly for AI shopping agents, or building any ecommerce functionality. Framework-agnostic (Next.js, SvelteKit, TanStack Start, React, Vue). Provides patterns, decision frameworks, backend integration guidance.

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