Storefront Best Practices

• Building or extending an ecommerce storefront — any framework (Next.js, SvelteKit, TanStack Start, React, Vue): product pages, product listings, cart, checkout, navigation, homepage, search, account pages, or order confirmation.
• Integrating a backend (including Medusa) — SDK setup, fetching products/categories/regions, pricing display, payment method selection, and cart management.
• Optimizing an existing store — improving conversion rates, fixing mobile experience issues, adding SEO structured data, or improving accessibility in the shopping flow.
• Planning a storefront implementation — generating a step-by-step build plan that references the correct reference files and avoids known pitfalls before writing any code.

• Non-ecommerce projects — admin dashboards, SaaS apps, blogs, or any site without a shopping/purchasing flow have no use for this skill's patterns.
• Pure backend or API work — if you are only working on the server-side commerce logic with no frontend storefront component involved, this skill adds little value.

Before writing any code that calls a backend API or SDK, the skill enforces a 5-step workflow: pause, query docs or MCP server, verify the method with the user, write code, then check for TypeScript errors. This prevents guessed method names, outdated examples, and silent runtime failures.

The skill maps every storefront task — checkout, product listing, navigation, SEO, mobile, Medusa integration, and more — to a specific reference file (e.g., reference/layouts/checkout.md, reference/medusa.md). It specifies exactly which files to load before implementing each feature, ensuring patterns are applied consistently.

Covers high-impact rules unique to storefronts: aria-live="polite" on cart counts for screen readers, env(safe-area-inset-bottom) for iOS sticky buttons, 44px minimum touch targets, mandatory loading="lazy" on product images below the fold, and prohibition of emojis in storefront UI.

Provides correct dynamic route patterns for Next.js (App and Pages Router), SvelteKit, TanStack Start, and Remix for product and category pages. Explicitly warns against static per-item routes that don't scale.

Covers Medusa SDK initialization (publishable API key required), correct pricing display (do not divide by 100), region_id requirement when fetching products, CORS port conventions (8000), Vite SSR config, using @medusajs/types instead of custom types, and cart state clearing after order placement.

A categorized list of over 30 named anti-patterns across cart/navigation, product browsing, checkout, mobile, SEO, performance, design consistency, and backend integration — each phrased as a concrete ❌ rule to check before and during implementation.

The skill provides a 10-step sequential workflow from discovery (loading design.md) through foundation, core components, shopping flow, and optimization. Each step references the exact file to load before implementing, ensuring nothing is missed and styles stay consistent.

Guides checkout architecture decisions (single-page vs. multi-step), enforces fetching payment methods from the backend rather than hardcoding them, flags the guest checkout requirement, and provides the Medusa-specific payment integration steps via reference/layouts/checkout.md and reference/medusa.md.

Covers SDK setup, region and pricing patterns, product fetching with region_id, country lists scoped to the cart's region, Vite SSR configuration, and use of the Medusa MCP server for method verification — preventing the most common Medusa storefront integration errors.

Directs developers to reference/mobile-responsiveness.md for touch target sizes, safe-area insets, and image optimization, and to reference/seo.md for Product JSON-LD schema, meta tags, Open Graph, and Core Web Vitals measurement via PageSpeed Insights.