storefront-best-practices_skill

Overview

This skill provides concise, framework-agnostic best practices for building and maintaining ecommerce storefronts and shopping flows. It is required whenever you work on any storefront component — product pages, cart, checkout, navigation, homepage, or integrations with Medusa. Follow it to ensure accessibility, performance, SEO, and reliable backend integration.

How this skill works

The skill defines mandatory reference-loading steps, decision frameworks, and critical implementation checks before writing code that touches UI or backend APIs. It lists specific reference files to load based on the component being implemented and enforces a verification workflow for backend/SDK calls (query docs/MCP, confirm method signature, then code). It also captures accessibility, mobile, performance, routing, and conversion patterns critical for ecommerce.

When to use it

• Any task that changes or adds storefront UI: product pages, listings, cart, checkout, navigation, homepage
• Integrating with a backend or Medusa SDK, or creating API-backed features
• Designing or adjusting mobile responsiveness, accessibility, or SEO for shopping flows
• Selecting implementation patterns (checkout strategy, product listing strategy, cart pattern)
• Creating plans for implementing components or full storefronts

Best practices

• Always load relevant reference files before implementing a component (design, medusa, checkout, etc.)
• Follow the backend SDK verification workflow: pause, query docs/MCP, confirm method signature, then write code
• Never hardcode dynamic content—fetch categories, products, regions, and shipping options from the backend
• Enforce accessibility: cart counts use aria-live="polite" and keyboard focus management for checkout
• Optimize mobile touch targets (≥44px) and use safe-area insets for sticky bottom elements
• Add loading="lazy" for below-the-fold product images and keep mobile images <500KB

Example use cases

• Add a checkout flow: load reference/layouts/checkout.md and reference/medusa.md, verify SDK methods, then implement step components
• Implement a cart popup: load reference/components/cart-popup.md and reference/components/navbar.md, ensure aria-live updates
• Build product listing page: load reference/layouts/product-listing.md and product-card.md, pick pagination vs infinite scroll via decision framework
• Connect storefront to Medusa: load reference/medusa.md, detect monorepo backend, verify exact SDK methods via MCP/docs before coding
• Create responsive navigation: load reference/components/navbar.md (and megamenu.md if needed), use dynamic routes for categories