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, or building any ecommerce functionality. Framework-agnostic (Next.js, SvelteKit, TanStack Start, React, Vue). Provides patterns, decision frameworks, backend integration guidance.
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
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
❌ 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")
