[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill-medusa-storefront-best-practices":3,"mdc--r31z1n-key":40,"related-org-medusa-storefront-best-practices":2492,"related-repo-medusa-storefront-best-practices":2653},{"slug":4,"name":4,"fn":5,"description":6,"org":7,"tags":12,"stars":24,"repoUrl":25,"updatedAt":26,"license":27,"forks":28,"topics":29,"repo":35,"sourceUrl":38,"mdContent":39},"storefront-best-practices","apply e-commerce storefront best practices","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\u002Fcomponent 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.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},"medusa","Medusa","https:\u002F\u002Fpexgzepcugksgbtrxkhf.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Forg-logos\u002Fmedusa.jpg","medusajs",[13,15,18,21],{"name":9,"slug":8,"type":14},"tag",{"name":16,"slug":17,"type":14},"E-commerce","e-commerce",{"name":19,"slug":20,"type":14},"Frontend","frontend",{"name":22,"slug":23,"type":14},"Design","design",197,"https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills","2026-04-06T18:29:59.740623",null,24,[30,31,32,33,34,8],"agentic-commerce","claude","claude-code","commerce","ecommerce",{"repoUrl":25,"stars":24,"forks":28,"topics":36,"description":37},[30,31,32,33,34,8],"Agent skills and commands for Medusa best practices and conventions.","https:\u002F\u002Fgithub.com\u002Fmedusajs\u002Fmedusa-agent-skills\u002Ftree\u002FHEAD\u002Fplugins\u002Fecommerce-storefront\u002Fskills\u002Fstorefront-best-practices","---\nname: storefront-best-practices\ndescription: 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\u002Fcomponent 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.\n---\n\n# Ecommerce Storefront Best Practices\n\nComprehensive guidance for building modern, high-converting ecommerce storefronts covering UI\u002FUX patterns, component design, layout structures, SEO optimization, and mobile responsiveness.\n\n## When to Apply\n\n**ALWAYS load this skill when working on ANY storefront task:**\n\n- **Adding checkout page\u002Fflow** - Payment, shipping, order placement\n- **Implementing cart** - Cart page, cart popup, add to cart functionality\n- **Building product pages** - Product details, product listings, product grids\n- **Creating navigation** - Navbar, megamenu, footer, mobile menu\n- **Integrating Medusa backend** - SDK setup, cart, products, payment\n- **Any storefront component** - Homepage, search, filters, account pages\n- Building new ecommerce storefronts from scratch\n- Improving existing shopping experiences and conversion rates\n- Optimizing for usability, accessibility, and SEO\n- Designing mobile-responsive ecommerce experiences\n\n**Example prompts that should trigger this skill:**\n- \"Add a checkout page\"\n- \"Implement shopping cart\"\n- \"Create product listing page\"\n- \"Connect to Medusa backend\"\n- \"Add navigation menu\"\n- \"Build homepage for store\"\n\n## CRITICAL: Load Reference Files When Needed\n\n**⚠️ ALWAYS load `reference\u002Fdesign.md` BEFORE creating ANY UI component**\n- Discovers existing design tokens (colors, fonts, spacing, patterns)\n- Prevents introducing inconsistent styles\n- Provides guardrails for maintaining brand consistency\n- **Required for every component, not just new storefronts**\n\n**Load these references based on what you're implementing:**\n\n- **Starting a new storefront?** → MUST load `reference\u002Fdesign.md` first to discover user preferences\n- **Connecting to backend API?** → MUST load `reference\u002Fconnecting-to-backend.md` first\n- **Connecting to Medusa backend?** → MUST load `reference\u002Fmedusa.md` for SDK setup, pricing, regions, and Medusa patterns\n- **Implementing homepage?** → MUST load `reference\u002Fcomponents\u002Fnavbar.md`, `reference\u002Fcomponents\u002Fhero.md`, `reference\u002Fcomponents\u002Ffooter.md`, and `reference\u002Flayouts\u002Fhome-page.md`\n- **Implementing navigation?** → MUST load `reference\u002Fcomponents\u002Fnavbar.md` and optionally `reference\u002Fcomponents\u002Fmegamenu.md`\n- **Building product listing?** → MUST load `reference\u002Flayouts\u002Fproduct-listing.md` first\n- **Building product details?** → MUST load `reference\u002Flayouts\u002Fproduct-details.md` first\n- **Implementing checkout?** → MUST load `reference\u002Flayouts\u002Fcheckout.md` first\n- **Optimizing for SEO?** → MUST load `reference\u002Fseo.md` first\n- **Optimizing for mobile?** → MUST load `reference\u002Fmobile-responsiveness.md` first\n\n**Minimum requirement:** Load at least 1-2 reference files relevant to your specific task before implementing.\n\n## Planning and Implementation Workflow\n\n**IMPORTANT: If you create a plan for implementing storefront features, include the following in your plan:**\n\nWhen implementing each component, page, layout, or feature in the plan:\n1. **Refer back to this skill** before starting implementation\n2. **Load relevant reference files** listed above for the specific component\u002Fpage you're building\n3. **Follow the patterns and guidance** in the reference files\n4. **Check common mistakes** sections to avoid known pitfalls\n\n**Example plan structure:**\n\n```\nTask 1: Implement Navigation\n- Load reference\u002Fcomponents\u002Fnavbar.md\n- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)\n- Refer to skill for common mistakes (e.g., hardcoding categories)\n\nTask 2: Implement Product Listing Page\n- Load reference\u002Flayouts\u002Fproduct-listing.md\n- Follow pagination\u002Ffiltering patterns from product-listing.md\n- Use reference\u002Fcomponents\u002Fproduct-card.md for product grid items\n- Check skill for backend integration guidance\n\nTask 3: Implement Checkout Flow\n- Load reference\u002Flayouts\u002Fcheckout.md\n- Load reference\u002Fmedusa.md for Medusa payment integration\n- Follow component architecture recommendations (separate step components)\n- Refer to skill for payment method fetching requirements\n```\n\n**Why this matters:**\n- Plans provide high-level strategy\n- Reference files provide detailed implementation patterns\n- Skill file contains critical mistakes to avoid\n- Following this workflow ensures consistency and best practices\n\n## Critical Ecommerce-Specific Patterns\n\n### Accessibility\n- **CRITICAL: Cart count updates require `aria-live=\"polite\"`** - Screen readers won't announce without it\n- Ensure keyboard navigation for all cart\u002Fcheckout interactions\n\n### Mobile\n- **Sticky bottom elements MUST use `env(safe-area-inset-bottom)`** - iOS home indicator will cut off purchase buttons otherwise\n- 44px minimum touch targets for cart actions, variant selectors, quantity buttons\n\n### Performance\n- **ALWAYS add `loading=\"lazy\"` to product images below fold** - Don't rely on browser defaults\n- Optimize product images for mobile (\u003C500KB) - Most ecommerce traffic is mobile\n\n### Conversion Optimization\n- Clear CTAs throughout shopping flow\n- Minimal friction in checkout (guest checkout if supported)\n- Trust signals (reviews, security badges, return policy) near purchase buttons\n- Clear pricing and shipping information upfront\n\n### SEO\n- **Product schema (JSON-LD) required** - Critical for Google Shopping and rich snippets\n- Use [PageSpeed Insights](https:\u002F\u002Fpagespeed.web.dev\u002F) to measure Core Web Vitals\n\n### Visual Design\n- **NEVER use emojis** in storefront UI - Use icons or images instead (unprofessional, accessibility issues)\n\n### Backend Integration\n- **Backend detection**: If in monorepo, check for backend directory. If unsure, ask user which backend is used.\n- **NEVER hardcode dynamic content**: Always fetch categories, regions, products, shipping options, etc. from backend - they change frequently\n- Never assume API structure - verify endpoints and data formats\n\n### ⚠️ CRITICAL: Backend SDK Method Verification Workflow\n\n**YOU MUST FOLLOW THIS EXACT WORKFLOW BEFORE WRITING CODE THAT CONNECTS TO BACKEND:**\n\n**Step 1: PAUSE - Do NOT write code yet**\n- You are about to write code that calls a backend API or SDK method (e.g., Medusa SDK, REST API, GraphQL)\n- **STOP** - Do not proceed to code without verification\n\n**Step 2: QUERY the documentation or MCP server**\n- **If MCP server available**: Query it for the exact method (for example, medusa MCP)\n- **If no MCP server**: Search official documentation\n- **Find**: Exact method name, parameters, return type\n\n**Step 3: VERIFY what you found**\n- State out loud to the user: \"I need to verify the correct method for [operation]. Let me check [MCP server\u002Fdocumentation].\"\n- Show the user what you found: \"According to [source], the method is `sdk.store.cart.methodName(params)`\"\n- Confirm the method signature and parameters\n\n**Step 4: ONLY THEN write the code**\n- Now you can write code using the verified method\n- Use the exact signature you found\n\n**Step 5: CHECK for TypeScript errors**\n- After writing the code, check for any TypeScript\u002Ftype errors related to the SDK\n- If you see type errors on SDK methods, it means you used an incorrect method name or wrong parameters\n- **Type errors are a sign you didn't verify correctly** - Go back to Step 2\n\n**THIS IS NOT OPTIONAL - THIS IS MANDATORY ERROR PREVENTION**\n\n**It is a CRITICAL ERROR to:**\n- ❌ Write code that calls backend APIs\u002FSDKs without explicitly querying docs\u002FMCP first\n- ❌ Guess method names or parameters\n- ❌ Ignore TypeScript errors on SDK methods (errors indicate incorrect method usage)\n- ❌ Copy examples from this skill without verification (examples may be outdated)\n- ❌ Assume SDK methods match REST API endpoints\n\n**For Medusa specifically:**\n- **Medusa pricing**: Display prices as-is - DO NOT divide by 100 (unlike Stripe, Medusa stores prices in display format)\n- **Medusa MCP server**: https:\u002F\u002Fdocs.medusajs.com\u002Fmcp - Recommend setup if not installed\n- Load `reference\u002Fmedusa.md` for Medusa-specific patterns (regions, pricing, etc.)\n\n### Routing Patterns\n- **ALWAYS use dynamic routes** for products and categories - NEVER create static pages for individual items\n- Product pages: Use dynamic routes like `\u002Fproducts\u002F[handle]` or `\u002Fproducts\u002F$handle`, NOT `\u002Fproducts\u002Fshirt.tsx`\n- Category pages: Use dynamic routes like `\u002Fcategories\u002F[handle]` or `\u002Fcategories\u002F$handle`, NOT `\u002Fcategories\u002Fwomen.tsx`\n- Framework-specific patterns:\n  - **Next.js App Router**: `app\u002Fproducts\u002F[handle]\u002Fpage.tsx` or `app\u002Fproducts\u002F[id]\u002Fpage.tsx`\n  - **Next.js Pages Router**: `pages\u002Fproducts\u002F[handle].tsx`\n  - **SvelteKit**: `routes\u002Fproducts\u002F[handle]\u002F+page.svelte`\n  - **TanStack Start**: `routes\u002Fproducts\u002F$handle.tsx`\n  - **Remix**: `routes\u002Fproducts.$handle.tsx`\n- Why: Dynamic routes scale to any number of products\u002Fcategories without creating individual files\n- Static routes are unmaintainable and don't scale (imagine creating 1000 product files)\n\n## Pattern Selection Guides\n\nWhen you need to choose between implementation patterns, load the relevant reference file:\n\n- **Checkout strategy** (single-page vs multi-step) → Load `reference\u002Flayouts\u002Fcheckout.md`\n- **Navigation strategy** (dropdown vs megamenu) → Load `reference\u002Fcomponents\u002Fnavbar.md` and `reference\u002Fcomponents\u002Fmegamenu.md`\n- **Product listing strategy** (pagination vs infinite scroll vs load more) → Load `reference\u002Flayouts\u002Fproduct-listing.md`\n- **Search strategy** (autocomplete vs filters vs natural language) → Load `reference\u002Fcomponents\u002Fsearch.md`\n- **Mobile vs desktop priorities** → Load `reference\u002Fmobile-responsiveness.md`\n- **Variant selection** (text vs swatches vs configurator) → Load `reference\u002Flayouts\u002Fproduct-details.md`\n- **Cart pattern** (popup vs drawer vs page navigation) → Load `reference\u002Fcomponents\u002Fcart-popup.md` and `reference\u002Flayouts\u002Fcart.md`\n- **Trust signals strategy** → Load `reference\u002Flayouts\u002Fproduct-details.md` and `reference\u002Flayouts\u002Fcheckout.md`\n\nEach reference file contains decision frameworks with specific criteria to help you choose the right pattern for your context.\n\n## Quick Reference\n\n### General\n\n```\nreference\u002Fconnecting-to-backend.md    - Framework detection, API setup, backend integration patterns\nreference\u002Fmedusa.md                    - Medusa SDK integration, pricing, regions, TypeScript types\nreference\u002Fdesign.md                    - User preferences, brand identity, design systems\nreference\u002Fseo.md                       - Meta tags, structured data, Core Web Vitals\nreference\u002Fmobile-responsiveness.md     - Mobile-first design, responsive breakpoints, touch interactions\n```\n\n### Components\n\n```\nreference\u002Fcomponents\u002Fnavbar.md         - Desktop\u002Fmobile navigation, logo, menu, cart icon, load for ALL pages\nreference\u002Fcomponents\u002Fmegamenu.md       - Category organization, featured products, mobile alternatives\nreference\u002Fcomponents\u002Fcart-popup.md     - Add-to-cart feedback, mini cart display\nreference\u002Fcomponents\u002Fcountry-selector.md - Country\u002Fregion selection, currency, pricing, Medusa regions\nreference\u002Fcomponents\u002Fbreadcrumbs.md    - Category hierarchy, structured data markup\nreference\u002Fcomponents\u002Fsearch.md         - Search input, autocomplete, results, filters\nreference\u002Fcomponents\u002Fproduct-reviews.md - Review display, rating aggregation, submission\nreference\u002Fcomponents\u002Fhero.md           - Hero layouts, CTA placement, image optimization\nreference\u002Fcomponents\u002Fpopups.md         - Newsletter signup, discount popups, exit-intent\nreference\u002Fcomponents\u002Ffooter.md         - Content organization, navigation, social media, load for ALL pages\nreference\u002Fcomponents\u002Fproduct-card.md   - Product images, pricing, add to cart, badges\nreference\u002Fcomponents\u002Fproduct-slider.md - Carousel implementation, mobile swipe, accessibility\n```\n\n### Layouts\n\n```\nreference\u002Flayouts\u002Fhome-page.md         - Hero, featured categories, product listings\nreference\u002Flayouts\u002Fproduct-listing.md   - Grid\u002Flist views, filters, sorting, pagination\nreference\u002Flayouts\u002Fproduct-details.md   - Image gallery, variant selection, related products\nreference\u002Flayouts\u002Fcart.md              - Cart items, quantity updates, promo codes\nreference\u002Flayouts\u002Fcheckout.md          - Multi-step\u002Fsingle-page, address forms, payment\nreference\u002Flayouts\u002Forder-confirmation.md - Order number, summary, delivery info\nreference\u002Flayouts\u002Faccount.md           - Dashboard, order history, address book\nreference\u002Flayouts\u002Fstatic-pages.md      - FAQ, about, contact, shipping\u002Freturns policies\n```\n\n### Features\n\n```\nreference\u002Ffeatures\u002Fwishlist.md         - Add to wishlist, wishlist page, move to cart\nreference\u002Ffeatures\u002Fpromotions.md       - Promotional banners, discount codes, sale badges\n```\n\n## Common Implementation Patterns\n\n### Starting a New Storefront\n\n**IMPORTANT: For each step below, load the referenced files BEFORE implementing that step.**\n\n```\n1. Discovery Phase → Read design.md for user preferences\n2. Foundation Setup → Read connecting-to-backend.md (or medusa.md for Medusa), mobile-responsiveness.md, seo.md\n3. Core Components → Implement navbar.md, footer.md\n4. Home Page → Read home-page.md\n5. Product Browsing → Read product-listing.md, product-card.md, search.md\n6. Product Details → Read product-details.md, product-reviews.md\n7. Cart & Checkout → Read cart-popup.md, cart.md, checkout.md, order-confirmation.md\n8. User Account → Read account.md\n9. Additional Features → Read wishlist.md, promotions.md\n10. Optimization → SEO audit (seo.md), mobile testing (mobile-responsiveness.md)\n```\n\nEven if you create an implementation plan, refer back to the skill and load relevant reference files when implementing each step.\n\n### Shopping Flow Pattern\n\n```\nBrowse → View → Cart → Checkout\n\nBrowse:   home-page.md → product-listing.md\nView:     product-details.md + product-reviews.md\nCart:     cart-popup.md → cart.md\nCheckout: checkout.md → order-confirmation.md\n```\n\n### Component Selection Guide\n\n**For product grids and filtering** → `product-listing.md` and `product-card.md`\n**For product cards** → `product-card.md`\n**For navigation** → `navbar.md` and `megamenu.md`\n**For search functionality** → `search.md`\n**For checkout flow** → `checkout.md`\n**For promotions and sales** → `promotions.md`\n\n## Design Considerations\n\nBefore implementing, consider:\n\n1. **User preferences** - Read `design.md` to discover design style preferences\n2. **Brand identity** - Colors, typography, tone that match the brand\n3. **Target audience** - B2C vs B2B, demographics, device usage\n4. **Product type** - Fashion vs electronics vs groceries affect layout choices\n5. **Business requirements** - Multi-currency, multi-language, region-specific\n6. **Backend system** - API structure affects component implementation\n\n## Integration with Medusa\n\n[Medusa](https:\u002F\u002Fmedusajs.com) is a modern, flexible ecommerce backend. Consider Medusa when:\n\n- Building a new ecommerce storefront\n- Need a headless commerce solution\n- Want built-in support for multi-region, multi-currency\n- Need powerful promotion and discount engine\n- Require flexible product modeling\n\nFor detailed Medusa integration guidance, see `reference\u002Fmedusa.md`. For general backend patterns, see `reference\u002Fconnecting-to-backend.md`.\n\n### Framework Agnostic\n\nAll guidance is framework-agnostic. Examples use React\u002FTypeScript where code demonstrations are helpful, but patterns apply to:\n\n- Next.js\n- SvelteKit\n- Tanstack Start\n- Any modern frontend framework\n\n## Minimum Viable Features\n\n**Mandatory for launch (core shopping flow):**\n- Navbar with cart, categories, search\n- Product listing with filtering and pagination\n- Product details with variant selection\n- Add to cart functionality\n- Cart page with item management\n- Checkout flow (shipping, payment, review)\n- Order confirmation page\n\n**Nice-to-have (add if time permits):**\n- Related products recommendations\n- Product reviews and ratings\n- Wishlist functionality\n- Image zoom on product pages\n- Bottom navigation on mobile\n- Mega-menu for navigation\n- Newsletter signup\n- Product comparison\n- Quick view modals\n\n**User-dependent (ask before implementing):**\n- Guest checkout vs login-required\n- Account dashboard features\n- Multi-language support\n- Multi-currency support\n- Live chat support\n\n## Top Ecommerce Mistakes to Avoid\n\nBefore implementing, watch out for these common ecommerce-specific pitfalls:\n\n**1. Cart and Navigation Mistakes**\n- ❌ Hiding cart indicator in mobile hamburger menu (keep always visible)\n- ❌ Not showing real-time cart count updates\n- ❌ **CRITICAL: Missing `aria-live=\"polite\"` on cart count** - Screen readers won't announce cart updates without it\n- ❌ Not displaying variant details (size, color, etc.) in cart popup - only showing product title\n- ❌ Megamenu closes when hovering over dropdown content (must stay open when hovering trigger OR dropdown)\n- ❌ **CRITICAL: Megamenu positioning errors** - Three common mistakes:\n  - ❌ Navbar doesn't have `position: relative` (megamenu won't position correctly)\n  - ❌ Megamenu positioned relative to trigger button instead of navbar (use `absolute left-0` on megamenu)\n  - ❌ Megamenu doesn't span full width (must use `right-0` or `w-full`, not just `w-auto`)\n- ❌ Hardcoding categories, featured products, or any dynamic content instead of fetching from backend\n- ❌ No clear indication of current page in category navigation\n\n**2. Product Browsing Mistakes**\n- ❌ Creating static routes for products\u002Fcategories (use dynamic routes like `\u002Fproducts\u002F[handle]` instead of `\u002Fproducts\u002Fshirt.tsx`)\n- ❌ Missing \"no products found\" empty state with helpful suggestions\n- ❌ No loading indicators while fetching products\n- ❌ Pagination without SEO-friendly URLs (for search engines)\n- ❌ Filter selections that don't persist on page reload\n\n**3. Product Details Mistakes**\n- ❌ Enabling \"Add to Cart\" before variant selection (size, color, etc.)\n- ❌ Missing product images optimization (large uncompressed images)\n- ❌ Navigating away from product page after adding to cart (stay on page)\n- ❌ Using emojis in UI instead of icons or images (unprofessional, accessibility issues)\n\n**4. Design and Consistency Mistakes**\n- ❌ **CRITICAL: Not loading `reference\u002Fdesign.md` before creating ANY UI component** - Leads to inconsistent colors, fonts, and styles\n- ❌ Introducing new colors without checking existing theme first\n- ❌ Adding new fonts without verifying what's already used\n- ❌ Using arbitrary Tailwind values when theme tokens exist\n- ❌ Not detecting Tailwind version (v3 vs v4) - Causes syntax errors\n\n**5. Checkout and Conversion Mistakes**\n- ❌ Requiring account creation to checkout (offer guest checkout if backend supports it)\n- ❌ Not fetching payment methods from backend - assuming available payment options or skipping payment method selection\n- ❌ Overly complex multi-step checkout (4+ steps kills conversion) - Optimal is 3 steps: Shipping Info, Delivery Method + Payment, Review\n- ❌ Missing trust signals (secure checkout badge, return policy link)\n- ❌ Not handling out-of-stock errors gracefully during checkout\n\n**6. Mobile Experience Mistakes**\n- ❌ Touch targets smaller than 44x44px (buttons, links, form fields)\n- ❌ Desktop-style hover menus on mobile (use tap\u002Fclick instead)\n- ❌ Not optimizing images for mobile (loading huge desktop images)\n- ❌ Missing mobile-specific patterns (bottom nav, drawer filters)\n\n**7. Performance and SEO Mistakes**\n- ❌ Missing structured data (Product schema) for SEO\n- ❌ No explicit image lazy loading (don't assume browser defaults) - Always add `loading=\"lazy\"` to images below the fold\n- ❌ Missing meta tags and Open Graph for social sharing\n- ❌ Not optimizing Core Web Vitals (LCP, FID, CLS) - Use [PageSpeed Insights](https:\u002F\u002Fpagespeed.web.dev\u002F) or Lighthouse to measure\n\n**8. Backend Integration Mistakes**\n- ❌ **ERROR: Writing code that calls backend APIs\u002FSDKs without following the 5-step verification workflow** - You MUST: 1) PAUSE, 2) QUERY docs\u002FMCP, 3) VERIFY with user, 4) Write code, 5) CHECK for type errors\n- ❌ **ERROR: Ignoring TypeScript errors on SDK methods** - Type errors mean you used wrong method names or parameters. Go back and verify with docs\u002FMCP\n- ❌ **ERROR: Guessing API method names, SDK methods, or parameters** - Always verify exact method signatures before use\n- ❌ **ERROR: Not using Medusa MCP server when available** - If using Medusa backend, always query MCP server for methods\n- ❌ **ERROR: Copying code examples without verifying they're current** - Examples may be outdated, always verify first\n- ❌ Not detecting which backend is being used (check monorepo, ask user if unsure)\n- ❌ Assuming API structure without checking backend documentation or MCP server\n- ❌ Hardcoding dynamic content (categories, regions, products, etc.) instead of fetching from backend\n- ❌ Defining custom types for Medusa entities instead of using `@medusajs\u002Ftypes` package\n- ❌ Initializing Medusa SDK without publishable API key (required for multi-region stores and product pricing)\n- ❌ Fetching Medusa products without passing `region_id` query parameter (causes missing or incorrect pricing)\n- ❌ Showing all countries in Medusa checkout - should only show countries from cart's region\n- ❌ Dividing Medusa prices by 100 (Medusa stores prices as-is, not in cents like Stripe)\n- ❌ Missing Vite SSR config for Medusa SDK (add `ssr.noExternal: ['@medusajs\u002Fjs-sdk']` to vite.config.ts)\n- ❌ Running Medusa storefront on port other than 8000 (causes CORS errors - Medusa backend expects port 8000 by default)\n- ❌ Not handling loading, error, and empty states for API calls\n- ❌ Making API calls on client-side that should be server-side (SEO, security)\n- ❌ Not implementing proper error messages (\"Error occurred\" vs \"Product out of stock\")\n- ❌ Missing cache invalidation (stale product data, prices, inventory)\n- ❌ **Not clearing cart state after order is placed** - Cart popup shows old items because cart wasn't reset from Context\u002FlocalStorage\u002Fcache\n",{"data":41,"body":42},{"name":4,"description":6},{"type":43,"children":44},"root",[45,54,60,67,76,161,169,202,208,225,251,259,453,463,469,477,482,526,534,546,554,577,583,590,614,620,644,650,676,682,705,711,740,746,759,765,793,799,807,815,833,841,874,882,930,938,951,959,982,990,998,1026,1034,1077,1083,1248,1254,1259,1403,1408,1414,1420,1429,1435,1444,1450,1459,1465,1474,1480,1486,1494,1503,1508,1514,1523,1529,1618,1624,1629,1700,1706,1717,1745,1764,1770,1775,1797,1803,1811,1849,1857,1905,1913,1941,1947,1952,1960,2080,2088,2129,2137,2160,2168,2209,2217,2245,2253,2276,2284,2321,2329],{"type":46,"tag":47,"props":48,"children":50},"element","h1",{"id":49},"ecommerce-storefront-best-practices",[51],{"type":52,"value":53},"text","Ecommerce Storefront Best Practices",{"type":46,"tag":55,"props":56,"children":57},"p",{},[58],{"type":52,"value":59},"Comprehensive guidance for building modern, high-converting ecommerce storefronts covering UI\u002FUX patterns, component design, layout structures, SEO optimization, and mobile responsiveness.",{"type":46,"tag":61,"props":62,"children":64},"h2",{"id":63},"when-to-apply",[65],{"type":52,"value":66},"When to Apply",{"type":46,"tag":55,"props":68,"children":69},{},[70],{"type":46,"tag":71,"props":72,"children":73},"strong",{},[74],{"type":52,"value":75},"ALWAYS load this skill when working on ANY storefront task:",{"type":46,"tag":77,"props":78,"children":79},"ul",{},[80,91,101,111,121,131,141,146,151,156],{"type":46,"tag":81,"props":82,"children":83},"li",{},[84,89],{"type":46,"tag":71,"props":85,"children":86},{},[87],{"type":52,"value":88},"Adding checkout page\u002Fflow",{"type":52,"value":90}," - Payment, shipping, order placement",{"type":46,"tag":81,"props":92,"children":93},{},[94,99],{"type":46,"tag":71,"props":95,"children":96},{},[97],{"type":52,"value":98},"Implementing cart",{"type":52,"value":100}," - Cart page, cart popup, add to cart functionality",{"type":46,"tag":81,"props":102,"children":103},{},[104,109],{"type":46,"tag":71,"props":105,"children":106},{},[107],{"type":52,"value":108},"Building product pages",{"type":52,"value":110}," - Product details, product listings, product grids",{"type":46,"tag":81,"props":112,"children":113},{},[114,119],{"type":46,"tag":71,"props":115,"children":116},{},[117],{"type":52,"value":118},"Creating navigation",{"type":52,"value":120}," - Navbar, megamenu, footer, mobile menu",{"type":46,"tag":81,"props":122,"children":123},{},[124,129],{"type":46,"tag":71,"props":125,"children":126},{},[127],{"type":52,"value":128},"Integrating Medusa backend",{"type":52,"value":130}," - SDK setup, cart, products, payment",{"type":46,"tag":81,"props":132,"children":133},{},[134,139],{"type":46,"tag":71,"props":135,"children":136},{},[137],{"type":52,"value":138},"Any storefront component",{"type":52,"value":140}," - Homepage, search, filters, account pages",{"type":46,"tag":81,"props":142,"children":143},{},[144],{"type":52,"value":145},"Building new ecommerce storefronts from scratch",{"type":46,"tag":81,"props":147,"children":148},{},[149],{"type":52,"value":150},"Improving existing shopping experiences and conversion rates",{"type":46,"tag":81,"props":152,"children":153},{},[154],{"type":52,"value":155},"Optimizing for usability, accessibility, and SEO",{"type":46,"tag":81,"props":157,"children":158},{},[159],{"type":52,"value":160},"Designing mobile-responsive ecommerce experiences",{"type":46,"tag":55,"props":162,"children":163},{},[164],{"type":46,"tag":71,"props":165,"children":166},{},[167],{"type":52,"value":168},"Example prompts that should trigger this skill:",{"type":46,"tag":77,"props":170,"children":171},{},[172,177,182,187,192,197],{"type":46,"tag":81,"props":173,"children":174},{},[175],{"type":52,"value":176},"\"Add a checkout page\"",{"type":46,"tag":81,"props":178,"children":179},{},[180],{"type":52,"value":181},"\"Implement shopping cart\"",{"type":46,"tag":81,"props":183,"children":184},{},[185],{"type":52,"value":186},"\"Create product listing page\"",{"type":46,"tag":81,"props":188,"children":189},{},[190],{"type":52,"value":191},"\"Connect to Medusa backend\"",{"type":46,"tag":81,"props":193,"children":194},{},[195],{"type":52,"value":196},"\"Add navigation menu\"",{"type":46,"tag":81,"props":198,"children":199},{},[200],{"type":52,"value":201},"\"Build homepage for store\"",{"type":46,"tag":61,"props":203,"children":205},{"id":204},"critical-load-reference-files-when-needed",[206],{"type":52,"value":207},"CRITICAL: Load Reference Files When Needed",{"type":46,"tag":55,"props":209,"children":210},{},[211],{"type":46,"tag":71,"props":212,"children":213},{},[214,216,223],{"type":52,"value":215},"⚠️ ALWAYS load ",{"type":46,"tag":217,"props":218,"children":220},"code",{"className":219},[],[221],{"type":52,"value":222},"reference\u002Fdesign.md",{"type":52,"value":224}," BEFORE creating ANY UI component",{"type":46,"tag":77,"props":226,"children":227},{},[228,233,238,243],{"type":46,"tag":81,"props":229,"children":230},{},[231],{"type":52,"value":232},"Discovers existing design tokens (colors, fonts, spacing, patterns)",{"type":46,"tag":81,"props":234,"children":235},{},[236],{"type":52,"value":237},"Prevents introducing inconsistent styles",{"type":46,"tag":81,"props":239,"children":240},{},[241],{"type":52,"value":242},"Provides guardrails for maintaining brand consistency",{"type":46,"tag":81,"props":244,"children":245},{},[246],{"type":46,"tag":71,"props":247,"children":248},{},[249],{"type":52,"value":250},"Required for every component, not just new storefronts",{"type":46,"tag":55,"props":252,"children":253},{},[254],{"type":46,"tag":71,"props":255,"children":256},{},[257],{"type":52,"value":258},"Load these references based on what you're implementing:",{"type":46,"tag":77,"props":260,"children":261},{},[262,279,296,313,351,373,389,405,421,437],{"type":46,"tag":81,"props":263,"children":264},{},[265,270,272,277],{"type":46,"tag":71,"props":266,"children":267},{},[268],{"type":52,"value":269},"Starting a new storefront?",{"type":52,"value":271}," → MUST load ",{"type":46,"tag":217,"props":273,"children":275},{"className":274},[],[276],{"type":52,"value":222},{"type":52,"value":278}," first to discover user preferences",{"type":46,"tag":81,"props":280,"children":281},{},[282,287,288,294],{"type":46,"tag":71,"props":283,"children":284},{},[285],{"type":52,"value":286},"Connecting to backend API?",{"type":52,"value":271},{"type":46,"tag":217,"props":289,"children":291},{"className":290},[],[292],{"type":52,"value":293},"reference\u002Fconnecting-to-backend.md",{"type":52,"value":295}," first",{"type":46,"tag":81,"props":297,"children":298},{},[299,304,305,311],{"type":46,"tag":71,"props":300,"children":301},{},[302],{"type":52,"value":303},"Connecting to Medusa backend?",{"type":52,"value":271},{"type":46,"tag":217,"props":306,"children":308},{"className":307},[],[309],{"type":52,"value":310},"reference\u002Fmedusa.md",{"type":52,"value":312}," for SDK setup, pricing, regions, and Medusa patterns",{"type":46,"tag":81,"props":314,"children":315},{},[316,321,322,328,330,336,337,343,345],{"type":46,"tag":71,"props":317,"children":318},{},[319],{"type":52,"value":320},"Implementing homepage?",{"type":52,"value":271},{"type":46,"tag":217,"props":323,"children":325},{"className":324},[],[326],{"type":52,"value":327},"reference\u002Fcomponents\u002Fnavbar.md",{"type":52,"value":329},", ",{"type":46,"tag":217,"props":331,"children":333},{"className":332},[],[334],{"type":52,"value":335},"reference\u002Fcomponents\u002Fhero.md",{"type":52,"value":329},{"type":46,"tag":217,"props":338,"children":340},{"className":339},[],[341],{"type":52,"value":342},"reference\u002Fcomponents\u002Ffooter.md",{"type":52,"value":344},", and ",{"type":46,"tag":217,"props":346,"children":348},{"className":347},[],[349],{"type":52,"value":350},"reference\u002Flayouts\u002Fhome-page.md",{"type":46,"tag":81,"props":352,"children":353},{},[354,359,360,365,367],{"type":46,"tag":71,"props":355,"children":356},{},[357],{"type":52,"value":358},"Implementing navigation?",{"type":52,"value":271},{"type":46,"tag":217,"props":361,"children":363},{"className":362},[],[364],{"type":52,"value":327},{"type":52,"value":366}," and optionally ",{"type":46,"tag":217,"props":368,"children":370},{"className":369},[],[371],{"type":52,"value":372},"reference\u002Fcomponents\u002Fmegamenu.md",{"type":46,"tag":81,"props":374,"children":375},{},[376,381,382,388],{"type":46,"tag":71,"props":377,"children":378},{},[379],{"type":52,"value":380},"Building product listing?",{"type":52,"value":271},{"type":46,"tag":217,"props":383,"children":385},{"className":384},[],[386],{"type":52,"value":387},"reference\u002Flayouts\u002Fproduct-listing.md",{"type":52,"value":295},{"type":46,"tag":81,"props":390,"children":391},{},[392,397,398,404],{"type":46,"tag":71,"props":393,"children":394},{},[395],{"type":52,"value":396},"Building product details?",{"type":52,"value":271},{"type":46,"tag":217,"props":399,"children":401},{"className":400},[],[402],{"type":52,"value":403},"reference\u002Flayouts\u002Fproduct-details.md",{"type":52,"value":295},{"type":46,"tag":81,"props":406,"children":407},{},[408,413,414,420],{"type":46,"tag":71,"props":409,"children":410},{},[411],{"type":52,"value":412},"Implementing checkout?",{"type":52,"value":271},{"type":46,"tag":217,"props":415,"children":417},{"className":416},[],[418],{"type":52,"value":419},"reference\u002Flayouts\u002Fcheckout.md",{"type":52,"value":295},{"type":46,"tag":81,"props":422,"children":423},{},[424,429,430,436],{"type":46,"tag":71,"props":425,"children":426},{},[427],{"type":52,"value":428},"Optimizing for SEO?",{"type":52,"value":271},{"type":46,"tag":217,"props":431,"children":433},{"className":432},[],[434],{"type":52,"value":435},"reference\u002Fseo.md",{"type":52,"value":295},{"type":46,"tag":81,"props":438,"children":439},{},[440,445,446,452],{"type":46,"tag":71,"props":441,"children":442},{},[443],{"type":52,"value":444},"Optimizing for mobile?",{"type":52,"value":271},{"type":46,"tag":217,"props":447,"children":449},{"className":448},[],[450],{"type":52,"value":451},"reference\u002Fmobile-responsiveness.md",{"type":52,"value":295},{"type":46,"tag":55,"props":454,"children":455},{},[456,461],{"type":46,"tag":71,"props":457,"children":458},{},[459],{"type":52,"value":460},"Minimum requirement:",{"type":52,"value":462}," Load at least 1-2 reference files relevant to your specific task before implementing.",{"type":46,"tag":61,"props":464,"children":466},{"id":465},"planning-and-implementation-workflow",[467],{"type":52,"value":468},"Planning and Implementation Workflow",{"type":46,"tag":55,"props":470,"children":471},{},[472],{"type":46,"tag":71,"props":473,"children":474},{},[475],{"type":52,"value":476},"IMPORTANT: If you create a plan for implementing storefront features, include the following in your plan:",{"type":46,"tag":55,"props":478,"children":479},{},[480],{"type":52,"value":481},"When implementing each component, page, layout, or feature in the plan:",{"type":46,"tag":483,"props":484,"children":485},"ol",{},[486,496,506,516],{"type":46,"tag":81,"props":487,"children":488},{},[489,494],{"type":46,"tag":71,"props":490,"children":491},{},[492],{"type":52,"value":493},"Refer back to this skill",{"type":52,"value":495}," before starting implementation",{"type":46,"tag":81,"props":497,"children":498},{},[499,504],{"type":46,"tag":71,"props":500,"children":501},{},[502],{"type":52,"value":503},"Load relevant reference files",{"type":52,"value":505}," listed above for the specific component\u002Fpage you're building",{"type":46,"tag":81,"props":507,"children":508},{},[509,514],{"type":46,"tag":71,"props":510,"children":511},{},[512],{"type":52,"value":513},"Follow the patterns and guidance",{"type":52,"value":515}," in the reference files",{"type":46,"tag":81,"props":517,"children":518},{},[519,524],{"type":46,"tag":71,"props":520,"children":521},{},[522],{"type":52,"value":523},"Check common mistakes",{"type":52,"value":525}," sections to avoid known pitfalls",{"type":46,"tag":55,"props":527,"children":528},{},[529],{"type":46,"tag":71,"props":530,"children":531},{},[532],{"type":52,"value":533},"Example plan structure:",{"type":46,"tag":535,"props":536,"children":540},"pre",{"className":537,"code":539,"language":52},[538],"language-text","Task 1: Implement Navigation\n- Load reference\u002Fcomponents\u002Fnavbar.md\n- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)\n- Refer to skill for common mistakes (e.g., hardcoding categories)\n\nTask 2: Implement Product Listing Page\n- Load reference\u002Flayouts\u002Fproduct-listing.md\n- Follow pagination\u002Ffiltering patterns from product-listing.md\n- Use reference\u002Fcomponents\u002Fproduct-card.md for product grid items\n- Check skill for backend integration guidance\n\nTask 3: Implement Checkout Flow\n- Load reference\u002Flayouts\u002Fcheckout.md\n- Load reference\u002Fmedusa.md for Medusa payment integration\n- Follow component architecture recommendations (separate step components)\n- Refer to skill for payment method fetching requirements\n",[541],{"type":46,"tag":217,"props":542,"children":544},{"__ignoreMap":543},"",[545],{"type":52,"value":539},{"type":46,"tag":55,"props":547,"children":548},{},[549],{"type":46,"tag":71,"props":550,"children":551},{},[552],{"type":52,"value":553},"Why this matters:",{"type":46,"tag":77,"props":555,"children":556},{},[557,562,567,572],{"type":46,"tag":81,"props":558,"children":559},{},[560],{"type":52,"value":561},"Plans provide high-level strategy",{"type":46,"tag":81,"props":563,"children":564},{},[565],{"type":52,"value":566},"Reference files provide detailed implementation patterns",{"type":46,"tag":81,"props":568,"children":569},{},[570],{"type":52,"value":571},"Skill file contains critical mistakes to avoid",{"type":46,"tag":81,"props":573,"children":574},{},[575],{"type":52,"value":576},"Following this workflow ensures consistency and best practices",{"type":46,"tag":61,"props":578,"children":580},{"id":579},"critical-ecommerce-specific-patterns",[581],{"type":52,"value":582},"Critical Ecommerce-Specific Patterns",{"type":46,"tag":584,"props":585,"children":587},"h3",{"id":586},"accessibility",[588],{"type":52,"value":589},"Accessibility",{"type":46,"tag":77,"props":591,"children":592},{},[593,609],{"type":46,"tag":81,"props":594,"children":595},{},[596,607],{"type":46,"tag":71,"props":597,"children":598},{},[599,601],{"type":52,"value":600},"CRITICAL: Cart count updates require ",{"type":46,"tag":217,"props":602,"children":604},{"className":603},[],[605],{"type":52,"value":606},"aria-live=\"polite\"",{"type":52,"value":608}," - Screen readers won't announce without it",{"type":46,"tag":81,"props":610,"children":611},{},[612],{"type":52,"value":613},"Ensure keyboard navigation for all cart\u002Fcheckout interactions",{"type":46,"tag":584,"props":615,"children":617},{"id":616},"mobile",[618],{"type":52,"value":619},"Mobile",{"type":46,"tag":77,"props":621,"children":622},{},[623,639],{"type":46,"tag":81,"props":624,"children":625},{},[626,637],{"type":46,"tag":71,"props":627,"children":628},{},[629,631],{"type":52,"value":630},"Sticky bottom elements MUST use ",{"type":46,"tag":217,"props":632,"children":634},{"className":633},[],[635],{"type":52,"value":636},"env(safe-area-inset-bottom)",{"type":52,"value":638}," - iOS home indicator will cut off purchase buttons otherwise",{"type":46,"tag":81,"props":640,"children":641},{},[642],{"type":52,"value":643},"44px minimum touch targets for cart actions, variant selectors, quantity buttons",{"type":46,"tag":584,"props":645,"children":647},{"id":646},"performance",[648],{"type":52,"value":649},"Performance",{"type":46,"tag":77,"props":651,"children":652},{},[653,671],{"type":46,"tag":81,"props":654,"children":655},{},[656,669],{"type":46,"tag":71,"props":657,"children":658},{},[659,661,667],{"type":52,"value":660},"ALWAYS add ",{"type":46,"tag":217,"props":662,"children":664},{"className":663},[],[665],{"type":52,"value":666},"loading=\"lazy\"",{"type":52,"value":668}," to product images below fold",{"type":52,"value":670}," - Don't rely on browser defaults",{"type":46,"tag":81,"props":672,"children":673},{},[674],{"type":52,"value":675},"Optimize product images for mobile (\u003C500KB) - Most ecommerce traffic is mobile",{"type":46,"tag":584,"props":677,"children":679},{"id":678},"conversion-optimization",[680],{"type":52,"value":681},"Conversion Optimization",{"type":46,"tag":77,"props":683,"children":684},{},[685,690,695,700],{"type":46,"tag":81,"props":686,"children":687},{},[688],{"type":52,"value":689},"Clear CTAs throughout shopping flow",{"type":46,"tag":81,"props":691,"children":692},{},[693],{"type":52,"value":694},"Minimal friction in checkout (guest checkout if supported)",{"type":46,"tag":81,"props":696,"children":697},{},[698],{"type":52,"value":699},"Trust signals (reviews, security badges, return policy) near purchase buttons",{"type":46,"tag":81,"props":701,"children":702},{},[703],{"type":52,"value":704},"Clear pricing and shipping information upfront",{"type":46,"tag":584,"props":706,"children":708},{"id":707},"seo",[709],{"type":52,"value":710},"SEO",{"type":46,"tag":77,"props":712,"children":713},{},[714,724],{"type":46,"tag":81,"props":715,"children":716},{},[717,722],{"type":46,"tag":71,"props":718,"children":719},{},[720],{"type":52,"value":721},"Product schema (JSON-LD) required",{"type":52,"value":723}," - Critical for Google Shopping and rich snippets",{"type":46,"tag":81,"props":725,"children":726},{},[727,729,738],{"type":52,"value":728},"Use ",{"type":46,"tag":730,"props":731,"children":735},"a",{"href":732,"rel":733},"https:\u002F\u002Fpagespeed.web.dev\u002F",[734],"nofollow",[736],{"type":52,"value":737},"PageSpeed Insights",{"type":52,"value":739}," to measure Core Web Vitals",{"type":46,"tag":584,"props":741,"children":743},{"id":742},"visual-design",[744],{"type":52,"value":745},"Visual Design",{"type":46,"tag":77,"props":747,"children":748},{},[749],{"type":46,"tag":81,"props":750,"children":751},{},[752,757],{"type":46,"tag":71,"props":753,"children":754},{},[755],{"type":52,"value":756},"NEVER use emojis",{"type":52,"value":758}," in storefront UI - Use icons or images instead (unprofessional, accessibility issues)",{"type":46,"tag":584,"props":760,"children":762},{"id":761},"backend-integration",[763],{"type":52,"value":764},"Backend Integration",{"type":46,"tag":77,"props":766,"children":767},{},[768,778,788],{"type":46,"tag":81,"props":769,"children":770},{},[771,776],{"type":46,"tag":71,"props":772,"children":773},{},[774],{"type":52,"value":775},"Backend detection",{"type":52,"value":777},": If in monorepo, check for backend directory. If unsure, ask user which backend is used.",{"type":46,"tag":81,"props":779,"children":780},{},[781,786],{"type":46,"tag":71,"props":782,"children":783},{},[784],{"type":52,"value":785},"NEVER hardcode dynamic content",{"type":52,"value":787},": Always fetch categories, regions, products, shipping options, etc. from backend - they change frequently",{"type":46,"tag":81,"props":789,"children":790},{},[791],{"type":52,"value":792},"Never assume API structure - verify endpoints and data formats",{"type":46,"tag":584,"props":794,"children":796},{"id":795},"️-critical-backend-sdk-method-verification-workflow",[797],{"type":52,"value":798},"⚠️ CRITICAL: Backend SDK Method Verification Workflow",{"type":46,"tag":55,"props":800,"children":801},{},[802],{"type":46,"tag":71,"props":803,"children":804},{},[805],{"type":52,"value":806},"YOU MUST FOLLOW THIS EXACT WORKFLOW BEFORE WRITING CODE THAT CONNECTS TO BACKEND:",{"type":46,"tag":55,"props":808,"children":809},{},[810],{"type":46,"tag":71,"props":811,"children":812},{},[813],{"type":52,"value":814},"Step 1: PAUSE - Do NOT write code yet",{"type":46,"tag":77,"props":816,"children":817},{},[818,823],{"type":46,"tag":81,"props":819,"children":820},{},[821],{"type":52,"value":822},"You are about to write code that calls a backend API or SDK method (e.g., Medusa SDK, REST API, GraphQL)",{"type":46,"tag":81,"props":824,"children":825},{},[826,831],{"type":46,"tag":71,"props":827,"children":828},{},[829],{"type":52,"value":830},"STOP",{"type":52,"value":832}," - Do not proceed to code without verification",{"type":46,"tag":55,"props":834,"children":835},{},[836],{"type":46,"tag":71,"props":837,"children":838},{},[839],{"type":52,"value":840},"Step 2: QUERY the documentation or MCP server",{"type":46,"tag":77,"props":842,"children":843},{},[844,854,864],{"type":46,"tag":81,"props":845,"children":846},{},[847,852],{"type":46,"tag":71,"props":848,"children":849},{},[850],{"type":52,"value":851},"If MCP server available",{"type":52,"value":853},": Query it for the exact method (for example, medusa MCP)",{"type":46,"tag":81,"props":855,"children":856},{},[857,862],{"type":46,"tag":71,"props":858,"children":859},{},[860],{"type":52,"value":861},"If no MCP server",{"type":52,"value":863},": Search official documentation",{"type":46,"tag":81,"props":865,"children":866},{},[867,872],{"type":46,"tag":71,"props":868,"children":869},{},[870],{"type":52,"value":871},"Find",{"type":52,"value":873},": Exact method name, parameters, return type",{"type":46,"tag":55,"props":875,"children":876},{},[877],{"type":46,"tag":71,"props":878,"children":879},{},[880],{"type":52,"value":881},"Step 3: VERIFY what you found",{"type":46,"tag":77,"props":883,"children":884},{},[885,905,925],{"type":46,"tag":81,"props":886,"children":887},{},[888,890,896,898,903],{"type":52,"value":889},"State out loud to the user: \"I need to verify the correct method for ",{"type":46,"tag":891,"props":892,"children":893},"span",{},[894],{"type":52,"value":895},"operation",{"type":52,"value":897},". Let me check ",{"type":46,"tag":891,"props":899,"children":900},{},[901],{"type":52,"value":902},"MCP server\u002Fdocumentation",{"type":52,"value":904},".\"",{"type":46,"tag":81,"props":906,"children":907},{},[908,910,915,917,923],{"type":52,"value":909},"Show the user what you found: \"According to ",{"type":46,"tag":891,"props":911,"children":912},{},[913],{"type":52,"value":914},"source",{"type":52,"value":916},", the method is ",{"type":46,"tag":217,"props":918,"children":920},{"className":919},[],[921],{"type":52,"value":922},"sdk.store.cart.methodName(params)",{"type":52,"value":924},"\"",{"type":46,"tag":81,"props":926,"children":927},{},[928],{"type":52,"value":929},"Confirm the method signature and parameters",{"type":46,"tag":55,"props":931,"children":932},{},[933],{"type":46,"tag":71,"props":934,"children":935},{},[936],{"type":52,"value":937},"Step 4: ONLY THEN write the code",{"type":46,"tag":77,"props":939,"children":940},{},[941,946],{"type":46,"tag":81,"props":942,"children":943},{},[944],{"type":52,"value":945},"Now you can write code using the verified method",{"type":46,"tag":81,"props":947,"children":948},{},[949],{"type":52,"value":950},"Use the exact signature you found",{"type":46,"tag":55,"props":952,"children":953},{},[954],{"type":46,"tag":71,"props":955,"children":956},{},[957],{"type":52,"value":958},"Step 5: CHECK for TypeScript errors",{"type":46,"tag":77,"props":960,"children":961},{},[962,967,972],{"type":46,"tag":81,"props":963,"children":964},{},[965],{"type":52,"value":966},"After writing the code, check for any TypeScript\u002Ftype errors related to the SDK",{"type":46,"tag":81,"props":968,"children":969},{},[970],{"type":52,"value":971},"If you see type errors on SDK methods, it means you used an incorrect method name or wrong parameters",{"type":46,"tag":81,"props":973,"children":974},{},[975,980],{"type":46,"tag":71,"props":976,"children":977},{},[978],{"type":52,"value":979},"Type errors are a sign you didn't verify correctly",{"type":52,"value":981}," - Go back to Step 2",{"type":46,"tag":55,"props":983,"children":984},{},[985],{"type":46,"tag":71,"props":986,"children":987},{},[988],{"type":52,"value":989},"THIS IS NOT OPTIONAL - THIS IS MANDATORY ERROR PREVENTION",{"type":46,"tag":55,"props":991,"children":992},{},[993],{"type":46,"tag":71,"props":994,"children":995},{},[996],{"type":52,"value":997},"It is a CRITICAL ERROR to:",{"type":46,"tag":77,"props":999,"children":1000},{},[1001,1006,1011,1016,1021],{"type":46,"tag":81,"props":1002,"children":1003},{},[1004],{"type":52,"value":1005},"❌ Write code that calls backend APIs\u002FSDKs without explicitly querying docs\u002FMCP first",{"type":46,"tag":81,"props":1007,"children":1008},{},[1009],{"type":52,"value":1010},"❌ Guess method names or parameters",{"type":46,"tag":81,"props":1012,"children":1013},{},[1014],{"type":52,"value":1015},"❌ Ignore TypeScript errors on SDK methods (errors indicate incorrect method usage)",{"type":46,"tag":81,"props":1017,"children":1018},{},[1019],{"type":52,"value":1020},"❌ Copy examples from this skill without verification (examples may be outdated)",{"type":46,"tag":81,"props":1022,"children":1023},{},[1024],{"type":52,"value":1025},"❌ Assume SDK methods match REST API endpoints",{"type":46,"tag":55,"props":1027,"children":1028},{},[1029],{"type":46,"tag":71,"props":1030,"children":1031},{},[1032],{"type":52,"value":1033},"For Medusa specifically:",{"type":46,"tag":77,"props":1035,"children":1036},{},[1037,1047,1065],{"type":46,"tag":81,"props":1038,"children":1039},{},[1040,1045],{"type":46,"tag":71,"props":1041,"children":1042},{},[1043],{"type":52,"value":1044},"Medusa pricing",{"type":52,"value":1046},": Display prices as-is - DO NOT divide by 100 (unlike Stripe, Medusa stores prices in display format)",{"type":46,"tag":81,"props":1048,"children":1049},{},[1050,1055,1057,1063],{"type":46,"tag":71,"props":1051,"children":1052},{},[1053],{"type":52,"value":1054},"Medusa MCP server",{"type":52,"value":1056},": ",{"type":46,"tag":730,"props":1058,"children":1061},{"href":1059,"rel":1060},"https:\u002F\u002Fdocs.medusajs.com\u002Fmcp",[734],[1062],{"type":52,"value":1059},{"type":52,"value":1064}," - Recommend setup if not installed",{"type":46,"tag":81,"props":1066,"children":1067},{},[1068,1070,1075],{"type":52,"value":1069},"Load ",{"type":46,"tag":217,"props":1071,"children":1073},{"className":1072},[],[1074],{"type":52,"value":310},{"type":52,"value":1076}," for Medusa-specific patterns (regions, pricing, etc.)",{"type":46,"tag":584,"props":1078,"children":1080},{"id":1079},"routing-patterns",[1081],{"type":52,"value":1082},"Routing Patterns",{"type":46,"tag":77,"props":1084,"children":1085},{},[1086,1096,1123,1148,1238,1243],{"type":46,"tag":81,"props":1087,"children":1088},{},[1089,1094],{"type":46,"tag":71,"props":1090,"children":1091},{},[1092],{"type":52,"value":1093},"ALWAYS use dynamic routes",{"type":52,"value":1095}," for products and categories - NEVER create static pages for individual items",{"type":46,"tag":81,"props":1097,"children":1098},{},[1099,1101,1107,1109,1115,1117],{"type":52,"value":1100},"Product pages: Use dynamic routes like ",{"type":46,"tag":217,"props":1102,"children":1104},{"className":1103},[],[1105],{"type":52,"value":1106},"\u002Fproducts\u002F[handle]",{"type":52,"value":1108}," or ",{"type":46,"tag":217,"props":1110,"children":1112},{"className":1111},[],[1113],{"type":52,"value":1114},"\u002Fproducts\u002F$handle",{"type":52,"value":1116},", NOT ",{"type":46,"tag":217,"props":1118,"children":1120},{"className":1119},[],[1121],{"type":52,"value":1122},"\u002Fproducts\u002Fshirt.tsx",{"type":46,"tag":81,"props":1124,"children":1125},{},[1126,1128,1134,1135,1141,1142],{"type":52,"value":1127},"Category pages: Use dynamic routes like ",{"type":46,"tag":217,"props":1129,"children":1131},{"className":1130},[],[1132],{"type":52,"value":1133},"\u002Fcategories\u002F[handle]",{"type":52,"value":1108},{"type":46,"tag":217,"props":1136,"children":1138},{"className":1137},[],[1139],{"type":52,"value":1140},"\u002Fcategories\u002F$handle",{"type":52,"value":1116},{"type":46,"tag":217,"props":1143,"children":1145},{"className":1144},[],[1146],{"type":52,"value":1147},"\u002Fcategories\u002Fwomen.tsx",{"type":46,"tag":81,"props":1149,"children":1150},{},[1151,1153],{"type":52,"value":1152},"Framework-specific patterns:\n",{"type":46,"tag":77,"props":1154,"children":1155},{},[1156,1178,1193,1208,1223],{"type":46,"tag":81,"props":1157,"children":1158},{},[1159,1164,1165,1171,1172],{"type":46,"tag":71,"props":1160,"children":1161},{},[1162],{"type":52,"value":1163},"Next.js App Router",{"type":52,"value":1056},{"type":46,"tag":217,"props":1166,"children":1168},{"className":1167},[],[1169],{"type":52,"value":1170},"app\u002Fproducts\u002F[handle]\u002Fpage.tsx",{"type":52,"value":1108},{"type":46,"tag":217,"props":1173,"children":1175},{"className":1174},[],[1176],{"type":52,"value":1177},"app\u002Fproducts\u002F[id]\u002Fpage.tsx",{"type":46,"tag":81,"props":1179,"children":1180},{},[1181,1186,1187],{"type":46,"tag":71,"props":1182,"children":1183},{},[1184],{"type":52,"value":1185},"Next.js Pages Router",{"type":52,"value":1056},{"type":46,"tag":217,"props":1188,"children":1190},{"className":1189},[],[1191],{"type":52,"value":1192},"pages\u002Fproducts\u002F[handle].tsx",{"type":46,"tag":81,"props":1194,"children":1195},{},[1196,1201,1202],{"type":46,"tag":71,"props":1197,"children":1198},{},[1199],{"type":52,"value":1200},"SvelteKit",{"type":52,"value":1056},{"type":46,"tag":217,"props":1203,"children":1205},{"className":1204},[],[1206],{"type":52,"value":1207},"routes\u002Fproducts\u002F[handle]\u002F+page.svelte",{"type":46,"tag":81,"props":1209,"children":1210},{},[1211,1216,1217],{"type":46,"tag":71,"props":1212,"children":1213},{},[1214],{"type":52,"value":1215},"TanStack Start",{"type":52,"value":1056},{"type":46,"tag":217,"props":1218,"children":1220},{"className":1219},[],[1221],{"type":52,"value":1222},"routes\u002Fproducts\u002F$handle.tsx",{"type":46,"tag":81,"props":1224,"children":1225},{},[1226,1231,1232],{"type":46,"tag":71,"props":1227,"children":1228},{},[1229],{"type":52,"value":1230},"Remix",{"type":52,"value":1056},{"type":46,"tag":217,"props":1233,"children":1235},{"className":1234},[],[1236],{"type":52,"value":1237},"routes\u002Fproducts.$handle.tsx",{"type":46,"tag":81,"props":1239,"children":1240},{},[1241],{"type":52,"value":1242},"Why: Dynamic routes scale to any number of products\u002Fcategories without creating individual files",{"type":46,"tag":81,"props":1244,"children":1245},{},[1246],{"type":52,"value":1247},"Static routes are unmaintainable and don't scale (imagine creating 1000 product files)",{"type":46,"tag":61,"props":1249,"children":1251},{"id":1250},"pattern-selection-guides",[1252],{"type":52,"value":1253},"Pattern Selection Guides",{"type":46,"tag":55,"props":1255,"children":1256},{},[1257],{"type":52,"value":1258},"When you need to choose between implementation patterns, load the relevant reference file:",{"type":46,"tag":77,"props":1260,"children":1261},{},[1262,1277,1299,1314,1330,1345,1360,1383],{"type":46,"tag":81,"props":1263,"children":1264},{},[1265,1270,1272],{"type":46,"tag":71,"props":1266,"children":1267},{},[1268],{"type":52,"value":1269},"Checkout strategy",{"type":52,"value":1271}," (single-page vs multi-step) → Load ",{"type":46,"tag":217,"props":1273,"children":1275},{"className":1274},[],[1276],{"type":52,"value":419},{"type":46,"tag":81,"props":1278,"children":1279},{},[1280,1285,1287,1292,1294],{"type":46,"tag":71,"props":1281,"children":1282},{},[1283],{"type":52,"value":1284},"Navigation strategy",{"type":52,"value":1286}," (dropdown vs megamenu) → Load ",{"type":46,"tag":217,"props":1288,"children":1290},{"className":1289},[],[1291],{"type":52,"value":327},{"type":52,"value":1293}," and ",{"type":46,"tag":217,"props":1295,"children":1297},{"className":1296},[],[1298],{"type":52,"value":372},{"type":46,"tag":81,"props":1300,"children":1301},{},[1302,1307,1309],{"type":46,"tag":71,"props":1303,"children":1304},{},[1305],{"type":52,"value":1306},"Product listing strategy",{"type":52,"value":1308}," (pagination vs infinite scroll vs load more) → Load ",{"type":46,"tag":217,"props":1310,"children":1312},{"className":1311},[],[1313],{"type":52,"value":387},{"type":46,"tag":81,"props":1315,"children":1316},{},[1317,1322,1324],{"type":46,"tag":71,"props":1318,"children":1319},{},[1320],{"type":52,"value":1321},"Search strategy",{"type":52,"value":1323}," (autocomplete vs filters vs natural language) → Load ",{"type":46,"tag":217,"props":1325,"children":1327},{"className":1326},[],[1328],{"type":52,"value":1329},"reference\u002Fcomponents\u002Fsearch.md",{"type":46,"tag":81,"props":1331,"children":1332},{},[1333,1338,1340],{"type":46,"tag":71,"props":1334,"children":1335},{},[1336],{"type":52,"value":1337},"Mobile vs desktop priorities",{"type":52,"value":1339}," → Load ",{"type":46,"tag":217,"props":1341,"children":1343},{"className":1342},[],[1344],{"type":52,"value":451},{"type":46,"tag":81,"props":1346,"children":1347},{},[1348,1353,1355],{"type":46,"tag":71,"props":1349,"children":1350},{},[1351],{"type":52,"value":1352},"Variant selection",{"type":52,"value":1354}," (text vs swatches vs configurator) → Load ",{"type":46,"tag":217,"props":1356,"children":1358},{"className":1357},[],[1359],{"type":52,"value":403},{"type":46,"tag":81,"props":1361,"children":1362},{},[1363,1368,1370,1376,1377],{"type":46,"tag":71,"props":1364,"children":1365},{},[1366],{"type":52,"value":1367},"Cart pattern",{"type":52,"value":1369}," (popup vs drawer vs page navigation) → Load ",{"type":46,"tag":217,"props":1371,"children":1373},{"className":1372},[],[1374],{"type":52,"value":1375},"reference\u002Fcomponents\u002Fcart-popup.md",{"type":52,"value":1293},{"type":46,"tag":217,"props":1378,"children":1380},{"className":1379},[],[1381],{"type":52,"value":1382},"reference\u002Flayouts\u002Fcart.md",{"type":46,"tag":81,"props":1384,"children":1385},{},[1386,1391,1392,1397,1398],{"type":46,"tag":71,"props":1387,"children":1388},{},[1389],{"type":52,"value":1390},"Trust signals strategy",{"type":52,"value":1339},{"type":46,"tag":217,"props":1393,"children":1395},{"className":1394},[],[1396],{"type":52,"value":403},{"type":52,"value":1293},{"type":46,"tag":217,"props":1399,"children":1401},{"className":1400},[],[1402],{"type":52,"value":419},{"type":46,"tag":55,"props":1404,"children":1405},{},[1406],{"type":52,"value":1407},"Each reference file contains decision frameworks with specific criteria to help you choose the right pattern for your context.",{"type":46,"tag":61,"props":1409,"children":1411},{"id":1410},"quick-reference",[1412],{"type":52,"value":1413},"Quick Reference",{"type":46,"tag":584,"props":1415,"children":1417},{"id":1416},"general",[1418],{"type":52,"value":1419},"General",{"type":46,"tag":535,"props":1421,"children":1424},{"className":1422,"code":1423,"language":52},[538],"reference\u002Fconnecting-to-backend.md    - Framework detection, API setup, backend integration patterns\nreference\u002Fmedusa.md                    - Medusa SDK integration, pricing, regions, TypeScript types\nreference\u002Fdesign.md                    - User preferences, brand identity, design systems\nreference\u002Fseo.md                       - Meta tags, structured data, Core Web Vitals\nreference\u002Fmobile-responsiveness.md     - Mobile-first design, responsive breakpoints, touch interactions\n",[1425],{"type":46,"tag":217,"props":1426,"children":1427},{"__ignoreMap":543},[1428],{"type":52,"value":1423},{"type":46,"tag":584,"props":1430,"children":1432},{"id":1431},"components",[1433],{"type":52,"value":1434},"Components",{"type":46,"tag":535,"props":1436,"children":1439},{"className":1437,"code":1438,"language":52},[538],"reference\u002Fcomponents\u002Fnavbar.md         - Desktop\u002Fmobile navigation, logo, menu, cart icon, load for ALL pages\nreference\u002Fcomponents\u002Fmegamenu.md       - Category organization, featured products, mobile alternatives\nreference\u002Fcomponents\u002Fcart-popup.md     - Add-to-cart feedback, mini cart display\nreference\u002Fcomponents\u002Fcountry-selector.md - Country\u002Fregion selection, currency, pricing, Medusa regions\nreference\u002Fcomponents\u002Fbreadcrumbs.md    - Category hierarchy, structured data markup\nreference\u002Fcomponents\u002Fsearch.md         - Search input, autocomplete, results, filters\nreference\u002Fcomponents\u002Fproduct-reviews.md - Review display, rating aggregation, submission\nreference\u002Fcomponents\u002Fhero.md           - Hero layouts, CTA placement, image optimization\nreference\u002Fcomponents\u002Fpopups.md         - Newsletter signup, discount popups, exit-intent\nreference\u002Fcomponents\u002Ffooter.md         - Content organization, navigation, social media, load for ALL pages\nreference\u002Fcomponents\u002Fproduct-card.md   - Product images, pricing, add to cart, badges\nreference\u002Fcomponents\u002Fproduct-slider.md - Carousel implementation, mobile swipe, accessibility\n",[1440],{"type":46,"tag":217,"props":1441,"children":1442},{"__ignoreMap":543},[1443],{"type":52,"value":1438},{"type":46,"tag":584,"props":1445,"children":1447},{"id":1446},"layouts",[1448],{"type":52,"value":1449},"Layouts",{"type":46,"tag":535,"props":1451,"children":1454},{"className":1452,"code":1453,"language":52},[538],"reference\u002Flayouts\u002Fhome-page.md         - Hero, featured categories, product listings\nreference\u002Flayouts\u002Fproduct-listing.md   - Grid\u002Flist views, filters, sorting, pagination\nreference\u002Flayouts\u002Fproduct-details.md   - Image gallery, variant selection, related products\nreference\u002Flayouts\u002Fcart.md              - Cart items, quantity updates, promo codes\nreference\u002Flayouts\u002Fcheckout.md          - Multi-step\u002Fsingle-page, address forms, payment\nreference\u002Flayouts\u002Forder-confirmation.md - Order number, summary, delivery info\nreference\u002Flayouts\u002Faccount.md           - Dashboard, order history, address book\nreference\u002Flayouts\u002Fstatic-pages.md      - FAQ, about, contact, shipping\u002Freturns policies\n",[1455],{"type":46,"tag":217,"props":1456,"children":1457},{"__ignoreMap":543},[1458],{"type":52,"value":1453},{"type":46,"tag":584,"props":1460,"children":1462},{"id":1461},"features",[1463],{"type":52,"value":1464},"Features",{"type":46,"tag":535,"props":1466,"children":1469},{"className":1467,"code":1468,"language":52},[538],"reference\u002Ffeatures\u002Fwishlist.md         - Add to wishlist, wishlist page, move to cart\nreference\u002Ffeatures\u002Fpromotions.md       - Promotional banners, discount codes, sale badges\n",[1470],{"type":46,"tag":217,"props":1471,"children":1472},{"__ignoreMap":543},[1473],{"type":52,"value":1468},{"type":46,"tag":61,"props":1475,"children":1477},{"id":1476},"common-implementation-patterns",[1478],{"type":52,"value":1479},"Common Implementation Patterns",{"type":46,"tag":584,"props":1481,"children":1483},{"id":1482},"starting-a-new-storefront",[1484],{"type":52,"value":1485},"Starting a New Storefront",{"type":46,"tag":55,"props":1487,"children":1488},{},[1489],{"type":46,"tag":71,"props":1490,"children":1491},{},[1492],{"type":52,"value":1493},"IMPORTANT: For each step below, load the referenced files BEFORE implementing that step.",{"type":46,"tag":535,"props":1495,"children":1498},{"className":1496,"code":1497,"language":52},[538],"1. Discovery Phase → Read design.md for user preferences\n2. Foundation Setup → Read connecting-to-backend.md (or medusa.md for Medusa), mobile-responsiveness.md, seo.md\n3. Core Components → Implement navbar.md, footer.md\n4. Home Page → Read home-page.md\n5. Product Browsing → Read product-listing.md, product-card.md, search.md\n6. Product Details → Read product-details.md, product-reviews.md\n7. Cart & Checkout → Read cart-popup.md, cart.md, checkout.md, order-confirmation.md\n8. User Account → Read account.md\n9. Additional Features → Read wishlist.md, promotions.md\n10. Optimization → SEO audit (seo.md), mobile testing (mobile-responsiveness.md)\n",[1499],{"type":46,"tag":217,"props":1500,"children":1501},{"__ignoreMap":543},[1502],{"type":52,"value":1497},{"type":46,"tag":55,"props":1504,"children":1505},{},[1506],{"type":52,"value":1507},"Even if you create an implementation plan, refer back to the skill and load relevant reference files when implementing each step.",{"type":46,"tag":584,"props":1509,"children":1511},{"id":1510},"shopping-flow-pattern",[1512],{"type":52,"value":1513},"Shopping Flow Pattern",{"type":46,"tag":535,"props":1515,"children":1518},{"className":1516,"code":1517,"language":52},[538],"Browse → View → Cart → Checkout\n\nBrowse:   home-page.md → product-listing.md\nView:     product-details.md + product-reviews.md\nCart:     cart-popup.md → cart.md\nCheckout: checkout.md → order-confirmation.md\n",[1519],{"type":46,"tag":217,"props":1520,"children":1521},{"__ignoreMap":543},[1522],{"type":52,"value":1517},{"type":46,"tag":584,"props":1524,"children":1526},{"id":1525},"component-selection-guide",[1527],{"type":52,"value":1528},"Component Selection Guide",{"type":46,"tag":55,"props":1530,"children":1531},{},[1532,1537,1539,1545,1546,1552,1557,1558,1563,1568,1569,1575,1576,1582,1587,1588,1594,1599,1600,1606,1611,1612],{"type":46,"tag":71,"props":1533,"children":1534},{},[1535],{"type":52,"value":1536},"For product grids and filtering",{"type":52,"value":1538}," → ",{"type":46,"tag":217,"props":1540,"children":1542},{"className":1541},[],[1543],{"type":52,"value":1544},"product-listing.md",{"type":52,"value":1293},{"type":46,"tag":217,"props":1547,"children":1549},{"className":1548},[],[1550],{"type":52,"value":1551},"product-card.md",{"type":46,"tag":71,"props":1553,"children":1554},{},[1555],{"type":52,"value":1556},"For product cards",{"type":52,"value":1538},{"type":46,"tag":217,"props":1559,"children":1561},{"className":1560},[],[1562],{"type":52,"value":1551},{"type":46,"tag":71,"props":1564,"children":1565},{},[1566],{"type":52,"value":1567},"For navigation",{"type":52,"value":1538},{"type":46,"tag":217,"props":1570,"children":1572},{"className":1571},[],[1573],{"type":52,"value":1574},"navbar.md",{"type":52,"value":1293},{"type":46,"tag":217,"props":1577,"children":1579},{"className":1578},[],[1580],{"type":52,"value":1581},"megamenu.md",{"type":46,"tag":71,"props":1583,"children":1584},{},[1585],{"type":52,"value":1586},"For search functionality",{"type":52,"value":1538},{"type":46,"tag":217,"props":1589,"children":1591},{"className":1590},[],[1592],{"type":52,"value":1593},"search.md",{"type":46,"tag":71,"props":1595,"children":1596},{},[1597],{"type":52,"value":1598},"For checkout flow",{"type":52,"value":1538},{"type":46,"tag":217,"props":1601,"children":1603},{"className":1602},[],[1604],{"type":52,"value":1605},"checkout.md",{"type":46,"tag":71,"props":1607,"children":1608},{},[1609],{"type":52,"value":1610},"For promotions and sales",{"type":52,"value":1538},{"type":46,"tag":217,"props":1613,"children":1615},{"className":1614},[],[1616],{"type":52,"value":1617},"promotions.md",{"type":46,"tag":61,"props":1619,"children":1621},{"id":1620},"design-considerations",[1622],{"type":52,"value":1623},"Design Considerations",{"type":46,"tag":55,"props":1625,"children":1626},{},[1627],{"type":52,"value":1628},"Before implementing, consider:",{"type":46,"tag":483,"props":1630,"children":1631},{},[1632,1650,1660,1670,1680,1690],{"type":46,"tag":81,"props":1633,"children":1634},{},[1635,1640,1642,1648],{"type":46,"tag":71,"props":1636,"children":1637},{},[1638],{"type":52,"value":1639},"User preferences",{"type":52,"value":1641}," - Read ",{"type":46,"tag":217,"props":1643,"children":1645},{"className":1644},[],[1646],{"type":52,"value":1647},"design.md",{"type":52,"value":1649}," to discover design style preferences",{"type":46,"tag":81,"props":1651,"children":1652},{},[1653,1658],{"type":46,"tag":71,"props":1654,"children":1655},{},[1656],{"type":52,"value":1657},"Brand identity",{"type":52,"value":1659}," - Colors, typography, tone that match the brand",{"type":46,"tag":81,"props":1661,"children":1662},{},[1663,1668],{"type":46,"tag":71,"props":1664,"children":1665},{},[1666],{"type":52,"value":1667},"Target audience",{"type":52,"value":1669}," - B2C vs B2B, demographics, device usage",{"type":46,"tag":81,"props":1671,"children":1672},{},[1673,1678],{"type":46,"tag":71,"props":1674,"children":1675},{},[1676],{"type":52,"value":1677},"Product type",{"type":52,"value":1679}," - Fashion vs electronics vs groceries affect layout choices",{"type":46,"tag":81,"props":1681,"children":1682},{},[1683,1688],{"type":46,"tag":71,"props":1684,"children":1685},{},[1686],{"type":52,"value":1687},"Business requirements",{"type":52,"value":1689}," - Multi-currency, multi-language, region-specific",{"type":46,"tag":81,"props":1691,"children":1692},{},[1693,1698],{"type":46,"tag":71,"props":1694,"children":1695},{},[1696],{"type":52,"value":1697},"Backend system",{"type":52,"value":1699}," - API structure affects component implementation",{"type":46,"tag":61,"props":1701,"children":1703},{"id":1702},"integration-with-medusa",[1704],{"type":52,"value":1705},"Integration with Medusa",{"type":46,"tag":55,"props":1707,"children":1708},{},[1709,1715],{"type":46,"tag":730,"props":1710,"children":1713},{"href":1711,"rel":1712},"https:\u002F\u002Fmedusajs.com",[734],[1714],{"type":52,"value":9},{"type":52,"value":1716}," is a modern, flexible ecommerce backend. Consider Medusa when:",{"type":46,"tag":77,"props":1718,"children":1719},{},[1720,1725,1730,1735,1740],{"type":46,"tag":81,"props":1721,"children":1722},{},[1723],{"type":52,"value":1724},"Building a new ecommerce storefront",{"type":46,"tag":81,"props":1726,"children":1727},{},[1728],{"type":52,"value":1729},"Need a headless commerce solution",{"type":46,"tag":81,"props":1731,"children":1732},{},[1733],{"type":52,"value":1734},"Want built-in support for multi-region, multi-currency",{"type":46,"tag":81,"props":1736,"children":1737},{},[1738],{"type":52,"value":1739},"Need powerful promotion and discount engine",{"type":46,"tag":81,"props":1741,"children":1742},{},[1743],{"type":52,"value":1744},"Require flexible product modeling",{"type":46,"tag":55,"props":1746,"children":1747},{},[1748,1750,1755,1757,1762],{"type":52,"value":1749},"For detailed Medusa integration guidance, see ",{"type":46,"tag":217,"props":1751,"children":1753},{"className":1752},[],[1754],{"type":52,"value":310},{"type":52,"value":1756},". For general backend patterns, see ",{"type":46,"tag":217,"props":1758,"children":1760},{"className":1759},[],[1761],{"type":52,"value":293},{"type":52,"value":1763},".",{"type":46,"tag":584,"props":1765,"children":1767},{"id":1766},"framework-agnostic",[1768],{"type":52,"value":1769},"Framework Agnostic",{"type":46,"tag":55,"props":1771,"children":1772},{},[1773],{"type":52,"value":1774},"All guidance is framework-agnostic. Examples use React\u002FTypeScript where code demonstrations are helpful, but patterns apply to:",{"type":46,"tag":77,"props":1776,"children":1777},{},[1778,1783,1787,1792],{"type":46,"tag":81,"props":1779,"children":1780},{},[1781],{"type":52,"value":1782},"Next.js",{"type":46,"tag":81,"props":1784,"children":1785},{},[1786],{"type":52,"value":1200},{"type":46,"tag":81,"props":1788,"children":1789},{},[1790],{"type":52,"value":1791},"Tanstack Start",{"type":46,"tag":81,"props":1793,"children":1794},{},[1795],{"type":52,"value":1796},"Any modern frontend framework",{"type":46,"tag":61,"props":1798,"children":1800},{"id":1799},"minimum-viable-features",[1801],{"type":52,"value":1802},"Minimum Viable Features",{"type":46,"tag":55,"props":1804,"children":1805},{},[1806],{"type":46,"tag":71,"props":1807,"children":1808},{},[1809],{"type":52,"value":1810},"Mandatory for launch (core shopping flow):",{"type":46,"tag":77,"props":1812,"children":1813},{},[1814,1819,1824,1829,1834,1839,1844],{"type":46,"tag":81,"props":1815,"children":1816},{},[1817],{"type":52,"value":1818},"Navbar with cart, categories, search",{"type":46,"tag":81,"props":1820,"children":1821},{},[1822],{"type":52,"value":1823},"Product listing with filtering and pagination",{"type":46,"tag":81,"props":1825,"children":1826},{},[1827],{"type":52,"value":1828},"Product details with variant selection",{"type":46,"tag":81,"props":1830,"children":1831},{},[1832],{"type":52,"value":1833},"Add to cart functionality",{"type":46,"tag":81,"props":1835,"children":1836},{},[1837],{"type":52,"value":1838},"Cart page with item management",{"type":46,"tag":81,"props":1840,"children":1841},{},[1842],{"type":52,"value":1843},"Checkout flow (shipping, payment, review)",{"type":46,"tag":81,"props":1845,"children":1846},{},[1847],{"type":52,"value":1848},"Order confirmation page",{"type":46,"tag":55,"props":1850,"children":1851},{},[1852],{"type":46,"tag":71,"props":1853,"children":1854},{},[1855],{"type":52,"value":1856},"Nice-to-have (add if time permits):",{"type":46,"tag":77,"props":1858,"children":1859},{},[1860,1865,1870,1875,1880,1885,1890,1895,1900],{"type":46,"tag":81,"props":1861,"children":1862},{},[1863],{"type":52,"value":1864},"Related products recommendations",{"type":46,"tag":81,"props":1866,"children":1867},{},[1868],{"type":52,"value":1869},"Product reviews and ratings",{"type":46,"tag":81,"props":1871,"children":1872},{},[1873],{"type":52,"value":1874},"Wishlist functionality",{"type":46,"tag":81,"props":1876,"children":1877},{},[1878],{"type":52,"value":1879},"Image zoom on product pages",{"type":46,"tag":81,"props":1881,"children":1882},{},[1883],{"type":52,"value":1884},"Bottom navigation on mobile",{"type":46,"tag":81,"props":1886,"children":1887},{},[1888],{"type":52,"value":1889},"Mega-menu for navigation",{"type":46,"tag":81,"props":1891,"children":1892},{},[1893],{"type":52,"value":1894},"Newsletter signup",{"type":46,"tag":81,"props":1896,"children":1897},{},[1898],{"type":52,"value":1899},"Product comparison",{"type":46,"tag":81,"props":1901,"children":1902},{},[1903],{"type":52,"value":1904},"Quick view modals",{"type":46,"tag":55,"props":1906,"children":1907},{},[1908],{"type":46,"tag":71,"props":1909,"children":1910},{},[1911],{"type":52,"value":1912},"User-dependent (ask before implementing):",{"type":46,"tag":77,"props":1914,"children":1915},{},[1916,1921,1926,1931,1936],{"type":46,"tag":81,"props":1917,"children":1918},{},[1919],{"type":52,"value":1920},"Guest checkout vs login-required",{"type":46,"tag":81,"props":1922,"children":1923},{},[1924],{"type":52,"value":1925},"Account dashboard features",{"type":46,"tag":81,"props":1927,"children":1928},{},[1929],{"type":52,"value":1930},"Multi-language support",{"type":46,"tag":81,"props":1932,"children":1933},{},[1934],{"type":52,"value":1935},"Multi-currency support",{"type":46,"tag":81,"props":1937,"children":1938},{},[1939],{"type":52,"value":1940},"Live chat support",{"type":46,"tag":61,"props":1942,"children":1944},{"id":1943},"top-ecommerce-mistakes-to-avoid",[1945],{"type":52,"value":1946},"Top Ecommerce Mistakes to Avoid",{"type":46,"tag":55,"props":1948,"children":1949},{},[1950],{"type":52,"value":1951},"Before implementing, watch out for these common ecommerce-specific pitfalls:",{"type":46,"tag":55,"props":1953,"children":1954},{},[1955],{"type":46,"tag":71,"props":1956,"children":1957},{},[1958],{"type":52,"value":1959},"1. Cart and Navigation Mistakes",{"type":46,"tag":77,"props":1961,"children":1962},{},[1963,1968,1973,1992,1997,2002,2070,2075],{"type":46,"tag":81,"props":1964,"children":1965},{},[1966],{"type":52,"value":1967},"❌ Hiding cart indicator in mobile hamburger menu (keep always visible)",{"type":46,"tag":81,"props":1969,"children":1970},{},[1971],{"type":52,"value":1972},"❌ Not showing real-time cart count updates",{"type":46,"tag":81,"props":1974,"children":1975},{},[1976,1978,1990],{"type":52,"value":1977},"❌ ",{"type":46,"tag":71,"props":1979,"children":1980},{},[1981,1983,1988],{"type":52,"value":1982},"CRITICAL: Missing ",{"type":46,"tag":217,"props":1984,"children":1986},{"className":1985},[],[1987],{"type":52,"value":606},{"type":52,"value":1989}," on cart count",{"type":52,"value":1991}," - Screen readers won't announce cart updates without it",{"type":46,"tag":81,"props":1993,"children":1994},{},[1995],{"type":52,"value":1996},"❌ Not displaying variant details (size, color, etc.) in cart popup - only showing product title",{"type":46,"tag":81,"props":1998,"children":1999},{},[2000],{"type":52,"value":2001},"❌ Megamenu closes when hovering over dropdown content (must stay open when hovering trigger OR dropdown)",{"type":46,"tag":81,"props":2003,"children":2004},{},[2005,2006,2011,2013],{"type":52,"value":1977},{"type":46,"tag":71,"props":2007,"children":2008},{},[2009],{"type":52,"value":2010},"CRITICAL: Megamenu positioning errors",{"type":52,"value":2012}," - Three common mistakes:\n",{"type":46,"tag":77,"props":2014,"children":2015},{},[2016,2029,2042],{"type":46,"tag":81,"props":2017,"children":2018},{},[2019,2021,2027],{"type":52,"value":2020},"❌ Navbar doesn't have ",{"type":46,"tag":217,"props":2022,"children":2024},{"className":2023},[],[2025],{"type":52,"value":2026},"position: relative",{"type":52,"value":2028}," (megamenu won't position correctly)",{"type":46,"tag":81,"props":2030,"children":2031},{},[2032,2034,2040],{"type":52,"value":2033},"❌ Megamenu positioned relative to trigger button instead of navbar (use ",{"type":46,"tag":217,"props":2035,"children":2037},{"className":2036},[],[2038],{"type":52,"value":2039},"absolute left-0",{"type":52,"value":2041}," on megamenu)",{"type":46,"tag":81,"props":2043,"children":2044},{},[2045,2047,2053,2054,2060,2062,2068],{"type":52,"value":2046},"❌ Megamenu doesn't span full width (must use ",{"type":46,"tag":217,"props":2048,"children":2050},{"className":2049},[],[2051],{"type":52,"value":2052},"right-0",{"type":52,"value":1108},{"type":46,"tag":217,"props":2055,"children":2057},{"className":2056},[],[2058],{"type":52,"value":2059},"w-full",{"type":52,"value":2061},", not just ",{"type":46,"tag":217,"props":2063,"children":2065},{"className":2064},[],[2066],{"type":52,"value":2067},"w-auto",{"type":52,"value":2069},")",{"type":46,"tag":81,"props":2071,"children":2072},{},[2073],{"type":52,"value":2074},"❌ Hardcoding categories, featured products, or any dynamic content instead of fetching from backend",{"type":46,"tag":81,"props":2076,"children":2077},{},[2078],{"type":52,"value":2079},"❌ No clear indication of current page in category navigation",{"type":46,"tag":55,"props":2081,"children":2082},{},[2083],{"type":46,"tag":71,"props":2084,"children":2085},{},[2086],{"type":52,"value":2087},"2. Product Browsing Mistakes",{"type":46,"tag":77,"props":2089,"children":2090},{},[2091,2109,2114,2119,2124],{"type":46,"tag":81,"props":2092,"children":2093},{},[2094,2096,2101,2103,2108],{"type":52,"value":2095},"❌ Creating static routes for products\u002Fcategories (use dynamic routes like ",{"type":46,"tag":217,"props":2097,"children":2099},{"className":2098},[],[2100],{"type":52,"value":1106},{"type":52,"value":2102}," instead of ",{"type":46,"tag":217,"props":2104,"children":2106},{"className":2105},[],[2107],{"type":52,"value":1122},{"type":52,"value":2069},{"type":46,"tag":81,"props":2110,"children":2111},{},[2112],{"type":52,"value":2113},"❌ Missing \"no products found\" empty state with helpful suggestions",{"type":46,"tag":81,"props":2115,"children":2116},{},[2117],{"type":52,"value":2118},"❌ No loading indicators while fetching products",{"type":46,"tag":81,"props":2120,"children":2121},{},[2122],{"type":52,"value":2123},"❌ Pagination without SEO-friendly URLs (for search engines)",{"type":46,"tag":81,"props":2125,"children":2126},{},[2127],{"type":52,"value":2128},"❌ Filter selections that don't persist on page reload",{"type":46,"tag":55,"props":2130,"children":2131},{},[2132],{"type":46,"tag":71,"props":2133,"children":2134},{},[2135],{"type":52,"value":2136},"3. Product Details Mistakes",{"type":46,"tag":77,"props":2138,"children":2139},{},[2140,2145,2150,2155],{"type":46,"tag":81,"props":2141,"children":2142},{},[2143],{"type":52,"value":2144},"❌ Enabling \"Add to Cart\" before variant selection (size, color, etc.)",{"type":46,"tag":81,"props":2146,"children":2147},{},[2148],{"type":52,"value":2149},"❌ Missing product images optimization (large uncompressed images)",{"type":46,"tag":81,"props":2151,"children":2152},{},[2153],{"type":52,"value":2154},"❌ Navigating away from product page after adding to cart (stay on page)",{"type":46,"tag":81,"props":2156,"children":2157},{},[2158],{"type":52,"value":2159},"❌ Using emojis in UI instead of icons or images (unprofessional, accessibility issues)",{"type":46,"tag":55,"props":2161,"children":2162},{},[2163],{"type":46,"tag":71,"props":2164,"children":2165},{},[2166],{"type":52,"value":2167},"4. Design and Consistency Mistakes",{"type":46,"tag":77,"props":2169,"children":2170},{},[2171,2189,2194,2199,2204],{"type":46,"tag":81,"props":2172,"children":2173},{},[2174,2175,2187],{"type":52,"value":1977},{"type":46,"tag":71,"props":2176,"children":2177},{},[2178,2180,2185],{"type":52,"value":2179},"CRITICAL: Not loading ",{"type":46,"tag":217,"props":2181,"children":2183},{"className":2182},[],[2184],{"type":52,"value":222},{"type":52,"value":2186}," before creating ANY UI component",{"type":52,"value":2188}," - Leads to inconsistent colors, fonts, and styles",{"type":46,"tag":81,"props":2190,"children":2191},{},[2192],{"type":52,"value":2193},"❌ Introducing new colors without checking existing theme first",{"type":46,"tag":81,"props":2195,"children":2196},{},[2197],{"type":52,"value":2198},"❌ Adding new fonts without verifying what's already used",{"type":46,"tag":81,"props":2200,"children":2201},{},[2202],{"type":52,"value":2203},"❌ Using arbitrary Tailwind values when theme tokens exist",{"type":46,"tag":81,"props":2205,"children":2206},{},[2207],{"type":52,"value":2208},"❌ Not detecting Tailwind version (v3 vs v4) - Causes syntax errors",{"type":46,"tag":55,"props":2210,"children":2211},{},[2212],{"type":46,"tag":71,"props":2213,"children":2214},{},[2215],{"type":52,"value":2216},"5. Checkout and Conversion Mistakes",{"type":46,"tag":77,"props":2218,"children":2219},{},[2220,2225,2230,2235,2240],{"type":46,"tag":81,"props":2221,"children":2222},{},[2223],{"type":52,"value":2224},"❌ Requiring account creation to checkout (offer guest checkout if backend supports it)",{"type":46,"tag":81,"props":2226,"children":2227},{},[2228],{"type":52,"value":2229},"❌ Not fetching payment methods from backend - assuming available payment options or skipping payment method selection",{"type":46,"tag":81,"props":2231,"children":2232},{},[2233],{"type":52,"value":2234},"❌ Overly complex multi-step checkout (4+ steps kills conversion) - Optimal is 3 steps: Shipping Info, Delivery Method + Payment, Review",{"type":46,"tag":81,"props":2236,"children":2237},{},[2238],{"type":52,"value":2239},"❌ Missing trust signals (secure checkout badge, return policy link)",{"type":46,"tag":81,"props":2241,"children":2242},{},[2243],{"type":52,"value":2244},"❌ Not handling out-of-stock errors gracefully during checkout",{"type":46,"tag":55,"props":2246,"children":2247},{},[2248],{"type":46,"tag":71,"props":2249,"children":2250},{},[2251],{"type":52,"value":2252},"6. Mobile Experience Mistakes",{"type":46,"tag":77,"props":2254,"children":2255},{},[2256,2261,2266,2271],{"type":46,"tag":81,"props":2257,"children":2258},{},[2259],{"type":52,"value":2260},"❌ Touch targets smaller than 44x44px (buttons, links, form fields)",{"type":46,"tag":81,"props":2262,"children":2263},{},[2264],{"type":52,"value":2265},"❌ Desktop-style hover menus on mobile (use tap\u002Fclick instead)",{"type":46,"tag":81,"props":2267,"children":2268},{},[2269],{"type":52,"value":2270},"❌ Not optimizing images for mobile (loading huge desktop images)",{"type":46,"tag":81,"props":2272,"children":2273},{},[2274],{"type":52,"value":2275},"❌ Missing mobile-specific patterns (bottom nav, drawer filters)",{"type":46,"tag":55,"props":2277,"children":2278},{},[2279],{"type":46,"tag":71,"props":2280,"children":2281},{},[2282],{"type":52,"value":2283},"7. Performance and SEO Mistakes",{"type":46,"tag":77,"props":2285,"children":2286},{},[2287,2292,2304,2309],{"type":46,"tag":81,"props":2288,"children":2289},{},[2290],{"type":52,"value":2291},"❌ Missing structured data (Product schema) for SEO",{"type":46,"tag":81,"props":2293,"children":2294},{},[2295,2297,2302],{"type":52,"value":2296},"❌ No explicit image lazy loading (don't assume browser defaults) - Always add ",{"type":46,"tag":217,"props":2298,"children":2300},{"className":2299},[],[2301],{"type":52,"value":666},{"type":52,"value":2303}," to images below the fold",{"type":46,"tag":81,"props":2305,"children":2306},{},[2307],{"type":52,"value":2308},"❌ Missing meta tags and Open Graph for social sharing",{"type":46,"tag":81,"props":2310,"children":2311},{},[2312,2314,2319],{"type":52,"value":2313},"❌ Not optimizing Core Web Vitals (LCP, FID, CLS) - Use ",{"type":46,"tag":730,"props":2315,"children":2317},{"href":732,"rel":2316},[734],[2318],{"type":52,"value":737},{"type":52,"value":2320}," or Lighthouse to measure",{"type":46,"tag":55,"props":2322,"children":2323},{},[2324],{"type":46,"tag":71,"props":2325,"children":2326},{},[2327],{"type":52,"value":2328},"8. Backend Integration Mistakes",{"type":46,"tag":77,"props":2330,"children":2331},{},[2332,2343,2354,2365,2376,2387,2392,2397,2402,2415,2420,2433,2438,2443,2456,2461,2466,2471,2476,2481],{"type":46,"tag":81,"props":2333,"children":2334},{},[2335,2336,2341],{"type":52,"value":1977},{"type":46,"tag":71,"props":2337,"children":2338},{},[2339],{"type":52,"value":2340},"ERROR: Writing code that calls backend APIs\u002FSDKs without following the 5-step verification workflow",{"type":52,"value":2342}," - You MUST: 1) PAUSE, 2) QUERY docs\u002FMCP, 3) VERIFY with user, 4) Write code, 5) CHECK for type errors",{"type":46,"tag":81,"props":2344,"children":2345},{},[2346,2347,2352],{"type":52,"value":1977},{"type":46,"tag":71,"props":2348,"children":2349},{},[2350],{"type":52,"value":2351},"ERROR: Ignoring TypeScript errors on SDK methods",{"type":52,"value":2353}," - Type errors mean you used wrong method names or parameters. Go back and verify with docs\u002FMCP",{"type":46,"tag":81,"props":2355,"children":2356},{},[2357,2358,2363],{"type":52,"value":1977},{"type":46,"tag":71,"props":2359,"children":2360},{},[2361],{"type":52,"value":2362},"ERROR: Guessing API method names, SDK methods, or parameters",{"type":52,"value":2364}," - Always verify exact method signatures before use",{"type":46,"tag":81,"props":2366,"children":2367},{},[2368,2369,2374],{"type":52,"value":1977},{"type":46,"tag":71,"props":2370,"children":2371},{},[2372],{"type":52,"value":2373},"ERROR: Not using Medusa MCP server when available",{"type":52,"value":2375}," - If using Medusa backend, always query MCP server for methods",{"type":46,"tag":81,"props":2377,"children":2378},{},[2379,2380,2385],{"type":52,"value":1977},{"type":46,"tag":71,"props":2381,"children":2382},{},[2383],{"type":52,"value":2384},"ERROR: Copying code examples without verifying they're current",{"type":52,"value":2386}," - Examples may be outdated, always verify first",{"type":46,"tag":81,"props":2388,"children":2389},{},[2390],{"type":52,"value":2391},"❌ Not detecting which backend is being used (check monorepo, ask user if unsure)",{"type":46,"tag":81,"props":2393,"children":2394},{},[2395],{"type":52,"value":2396},"❌ Assuming API structure without checking backend documentation or MCP server",{"type":46,"tag":81,"props":2398,"children":2399},{},[2400],{"type":52,"value":2401},"❌ Hardcoding dynamic content (categories, regions, products, etc.) instead of fetching from backend",{"type":46,"tag":81,"props":2403,"children":2404},{},[2405,2407,2413],{"type":52,"value":2406},"❌ Defining custom types for Medusa entities instead of using ",{"type":46,"tag":217,"props":2408,"children":2410},{"className":2409},[],[2411],{"type":52,"value":2412},"@medusajs\u002Ftypes",{"type":52,"value":2414}," package",{"type":46,"tag":81,"props":2416,"children":2417},{},[2418],{"type":52,"value":2419},"❌ Initializing Medusa SDK without publishable API key (required for multi-region stores and product pricing)",{"type":46,"tag":81,"props":2421,"children":2422},{},[2423,2425,2431],{"type":52,"value":2424},"❌ Fetching Medusa products without passing ",{"type":46,"tag":217,"props":2426,"children":2428},{"className":2427},[],[2429],{"type":52,"value":2430},"region_id",{"type":52,"value":2432}," query parameter (causes missing or incorrect pricing)",{"type":46,"tag":81,"props":2434,"children":2435},{},[2436],{"type":52,"value":2437},"❌ Showing all countries in Medusa checkout - should only show countries from cart's region",{"type":46,"tag":81,"props":2439,"children":2440},{},[2441],{"type":52,"value":2442},"❌ Dividing Medusa prices by 100 (Medusa stores prices as-is, not in cents like Stripe)",{"type":46,"tag":81,"props":2444,"children":2445},{},[2446,2448,2454],{"type":52,"value":2447},"❌ Missing Vite SSR config for Medusa SDK (add ",{"type":46,"tag":217,"props":2449,"children":2451},{"className":2450},[],[2452],{"type":52,"value":2453},"ssr.noExternal: ['@medusajs\u002Fjs-sdk']",{"type":52,"value":2455}," to vite.config.ts)",{"type":46,"tag":81,"props":2457,"children":2458},{},[2459],{"type":52,"value":2460},"❌ Running Medusa storefront on port other than 8000 (causes CORS errors - Medusa backend expects port 8000 by default)",{"type":46,"tag":81,"props":2462,"children":2463},{},[2464],{"type":52,"value":2465},"❌ Not handling loading, error, and empty states for API calls",{"type":46,"tag":81,"props":2467,"children":2468},{},[2469],{"type":52,"value":2470},"❌ Making API calls on client-side that should be server-side (SEO, security)",{"type":46,"tag":81,"props":2472,"children":2473},{},[2474],{"type":52,"value":2475},"❌ Not implementing proper error messages (\"Error occurred\" vs \"Product out of stock\")",{"type":46,"tag":81,"props":2477,"children":2478},{},[2479],{"type":52,"value":2480},"❌ Missing cache invalidation (stale product data, prices, inventory)",{"type":46,"tag":81,"props":2482,"children":2483},{},[2484,2485,2490],{"type":52,"value":1977},{"type":46,"tag":71,"props":2486,"children":2487},{},[2488],{"type":52,"value":2489},"Not clearing cart state after order is placed",{"type":52,"value":2491}," - Cart popup shows old items because cart wasn't reset from Context\u002FlocalStorage\u002Fcache",{"items":2493,"total":2652},[2494,2507,2523,2538,2550,2565,2575,2588,2605,2617,2630,2643],{"slug":2495,"name":2495,"fn":2496,"description":2497,"org":2498,"tags":2499,"stars":24,"repoUrl":25,"updatedAt":2506},"building-admin-dashboard-customizations","customize Medusa Admin dashboard UI","Load automatically when planning, researching, or implementing Medusa Admin dashboard UI (widgets, custom pages, forms, tables, data loading, navigation). REQUIRED for all admin UI work in ALL modes (planning, implementation, exploration). Contains design patterns, component usage, and data loading patterns that MCP servers don't provide.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2500,2501,2502,2503],{"name":16,"slug":17,"type":14},{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},{"name":2504,"slug":2505,"type":14},"UI Components","ui-components","2026-04-06T18:29:57.203659",{"slug":2508,"name":2508,"fn":2509,"description":2510,"org":2511,"tags":2512,"stars":24,"repoUrl":25,"updatedAt":2522},"building-storefronts","implement Medusa storefront features","Load automatically when planning, researching, or implementing Medusa storefront features (calling custom API routes, SDK integration, React Query patterns, data fetching). REQUIRED for all storefront development in ALL modes (planning, implementation, exploration). Contains SDK usage patterns, frontend integration, and critical rules for calling Medusa APIs.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2513,2514,2517,2518,2519],{"name":16,"slug":17,"type":14},{"name":2515,"slug":2516,"type":14},"Engineering","engineering",{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},{"name":2520,"slug":2521,"type":14},"React","react","2026-04-06T18:29:55.957429",{"slug":2524,"name":2524,"fn":2525,"description":2526,"org":2527,"tags":2528,"stars":24,"repoUrl":25,"updatedAt":2537},"building-with-medusa","implement Medusa backend features","Load automatically when planning, researching, or implementing ANY Medusa backend features (custom modules, API routes, workflows, data models, module links, business logic). REQUIRED for all Medusa backend work in ALL modes (planning, implementation, exploration). Contains architectural patterns, best practices, and critical rules that MCP servers don't provide.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2529,2532,2535,2536],{"name":2530,"slug":2531,"type":14},"Backend","backend",{"name":2533,"slug":2534,"type":14},"Data Modeling","data-modeling",{"name":16,"slug":17,"type":14},{"name":9,"slug":8,"type":14},"2026-04-06T18:29:54.652389",{"slug":2539,"name":2539,"fn":2540,"description":2541,"org":2542,"tags":2543,"stars":24,"repoUrl":25,"updatedAt":2549},"creating-agents-in-medusa","build admin-facing AI agents in Medusa","Use when building an internal admin-facing AI agent in a Medusa project. These agents are operated by merchants and store operators — not customers. Covers data models, module service, agent runtime (tools, system prompt, streamText), streaming API routes (NDJSON), and admin UI chat extensions. Load for any internal agent type: store operations assistant, product audit, cohort analysis, customer service tooling for support staff, etc. Do NOT use for customer-facing agents (storefront chatbots, buyer-side assistants).",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2544,2547,2548],{"name":2545,"slug":2546,"type":14},"Agents","agents",{"name":2530,"slug":2531,"type":14},{"name":9,"slug":8,"type":14},"2026-07-14T05:42:09.367168",{"slug":2551,"name":2551,"fn":2552,"description":2553,"org":2554,"tags":2555,"stars":24,"repoUrl":25,"updatedAt":2564},"db-generate","generate database migrations for Medusa modules","Generate database migrations for a Medusa module",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2556,2557,2560,2561],{"name":2530,"slug":2531,"type":14},{"name":2558,"slug":2559,"type":14},"Database","database",{"name":9,"slug":8,"type":14},{"name":2562,"slug":2563,"type":14},"Migration","migration","2026-04-06T18:29:53.415671",{"slug":2566,"name":2566,"fn":2567,"description":2568,"org":2569,"tags":2570,"stars":24,"repoUrl":25,"updatedAt":2574},"db-migrate","run database migrations in Medusa","Run database migrations in Medusa",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2571,2572,2573],{"name":2558,"slug":2559,"type":14},{"name":9,"slug":8,"type":14},{"name":2562,"slug":2563,"type":14},"2026-04-06T18:29:52.187377",{"slug":2576,"name":2576,"fn":2577,"description":2578,"org":2579,"tags":2580,"stars":24,"repoUrl":25,"updatedAt":2587},"learning-medusa","guide Medusa development learning","Load automatically when user asks to learn Medusa development (e.g., \"teach me how to build with medusa\", \"guide me through medusa\", \"I want to learn medusa\"). Interactive guided tutorial where Claude acts as a coding bootcamp instructor, teaching step-by-step with checkpoints and verification.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2581,2582,2583,2584],{"name":2530,"slug":2531,"type":14},{"name":16,"slug":17,"type":14},{"name":9,"slug":8,"type":14},{"name":2585,"slug":2586,"type":14},"Templates","templates","2026-04-06T18:29:58.461689",{"slug":2589,"name":2589,"fn":2590,"description":2591,"org":2592,"tags":2593,"stars":24,"repoUrl":25,"updatedAt":2604},"mcloud-deployments","manage Medusa Cloud deployments","Execute mcloud deployments commands to list deployments, retrieve deployment details, and fetch build logs. Use when listing deployments, checking deployment status, or reading build output for debugging build failures.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2594,2597,2600,2601],{"name":2595,"slug":2596,"type":14},"Deployment","deployment",{"name":2598,"slug":2599,"type":14},"Logs","logs",{"name":9,"slug":8,"type":14},{"name":2602,"slug":2603,"type":14},"Observability","observability","2026-05-09T05:40:51.727369",{"slug":2606,"name":2606,"fn":2607,"description":2608,"org":2609,"tags":2610,"stars":24,"repoUrl":25,"updatedAt":2616},"mcloud-environments","manage Medusa Cloud environments","Execute mcloud environments commands to list, get, create, delete, redeploy, or trigger builds for Cloud environments. Use when managing environment lifecycle, redeploying after variable changes, or starting new builds from source.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2611,2612,2613],{"name":2595,"slug":2596,"type":14},{"name":9,"slug":8,"type":14},{"name":2614,"slug":2615,"type":14},"Operations","operations","2026-07-17T05:31:36.384292",{"slug":2618,"name":2618,"fn":2619,"description":2620,"org":2621,"tags":2622,"stars":24,"repoUrl":25,"updatedAt":2629},"mcloud-local","reproduce Cloud builds locally","Execute mcloud local build to reproduce a Cloud build on the local machine. Use when debugging a build-failed deployment without pushing to the tracked branch, iterating on a build fix, or testing build-variable changes locally. Requires Docker and must run inside the project's Git repo.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2623,2626,2627,2628],{"name":2624,"slug":2625,"type":14},"Debugging","debugging",{"name":2595,"slug":2596,"type":14},{"name":2515,"slug":2516,"type":14},{"name":9,"slug":8,"type":14},"2026-07-17T06:05:07.199529",{"slug":2631,"name":2631,"fn":2632,"description":2633,"org":2634,"tags":2635,"stars":24,"repoUrl":25,"updatedAt":2642},"mcloud-logs","fetch and stream runtime cloud logs","Execute mcloud logs to fetch and stream runtime logs for Cloud environments. Use when reading backend or storefront logs, filtering by time range, searching for errors, or scoping logs to a specific deployment.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2636,2639,2640,2641],{"name":2637,"slug":2638,"type":14},"Cloud","cloud",{"name":2598,"slug":2599,"type":14},{"name":9,"slug":8,"type":14},{"name":2602,"slug":2603,"type":14},"2026-05-09T05:40:46.707854",{"slug":2644,"name":2644,"fn":2645,"description":2646,"org":2647,"tags":2648,"stars":24,"repoUrl":25,"updatedAt":2651},"mcloud-organizations","manage Medusa Cloud organizations","Execute mcloud organizations commands to list or get Cloud organizations. Use when discovering organizations, resolving organization IDs by name, or retrieving organization details including members and subscription.",{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2649,2650],{"name":9,"slug":8,"type":14},{"name":2614,"slug":2615,"type":14},"2026-05-09T05:40:54.327722",17,{"items":2654,"total":2652},[2655,2662,2670,2677,2683,2690,2696],{"slug":2495,"name":2495,"fn":2496,"description":2497,"org":2656,"tags":2657,"stars":24,"repoUrl":25,"updatedAt":2506},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2658,2659,2660,2661],{"name":16,"slug":17,"type":14},{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},{"name":2504,"slug":2505,"type":14},{"slug":2508,"name":2508,"fn":2509,"description":2510,"org":2663,"tags":2664,"stars":24,"repoUrl":25,"updatedAt":2522},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2665,2666,2667,2668,2669],{"name":16,"slug":17,"type":14},{"name":2515,"slug":2516,"type":14},{"name":19,"slug":20,"type":14},{"name":9,"slug":8,"type":14},{"name":2520,"slug":2521,"type":14},{"slug":2524,"name":2524,"fn":2525,"description":2526,"org":2671,"tags":2672,"stars":24,"repoUrl":25,"updatedAt":2537},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2673,2674,2675,2676],{"name":2530,"slug":2531,"type":14},{"name":2533,"slug":2534,"type":14},{"name":16,"slug":17,"type":14},{"name":9,"slug":8,"type":14},{"slug":2539,"name":2539,"fn":2540,"description":2541,"org":2678,"tags":2679,"stars":24,"repoUrl":25,"updatedAt":2549},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2680,2681,2682],{"name":2545,"slug":2546,"type":14},{"name":2530,"slug":2531,"type":14},{"name":9,"slug":8,"type":14},{"slug":2551,"name":2551,"fn":2552,"description":2553,"org":2684,"tags":2685,"stars":24,"repoUrl":25,"updatedAt":2564},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2686,2687,2688,2689],{"name":2530,"slug":2531,"type":14},{"name":2558,"slug":2559,"type":14},{"name":9,"slug":8,"type":14},{"name":2562,"slug":2563,"type":14},{"slug":2566,"name":2566,"fn":2567,"description":2568,"org":2691,"tags":2692,"stars":24,"repoUrl":25,"updatedAt":2574},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2693,2694,2695],{"name":2558,"slug":2559,"type":14},{"name":9,"slug":8,"type":14},{"name":2562,"slug":2563,"type":14},{"slug":2576,"name":2576,"fn":2577,"description":2578,"org":2697,"tags":2698,"stars":24,"repoUrl":25,"updatedAt":2587},{"slug":8,"name":9,"logoUrl":10,"githubOrg":11},[2699,2700,2701,2702],{"name":2530,"slug":2531,"type":14},{"name":16,"slug":17,"type":14},{"name":9,"slug":8,"type":14},{"name":2585,"slug":2586,"type":14}]