storefront-best-practices

Files (28)

• SKILL.md
• breadcrumbs.md · reference/components/
• cart-popup.md · reference/components/
• country-selector.md · reference/components/
• footer.md · reference/components/
• hero.md · reference/components/
• megamenu.md · reference/components/
• navbar.md · reference/components/
• popups.md · reference/components/
• product-card.md · reference/components/
• product-reviews.md · reference/components/
• product-slider.md · reference/components/
• search.md · reference/components/
• connecting-to-backend.md · reference/
• design.md · reference/
• promotions.md · reference/features/
• wishlist.md · reference/features/
• account.md · reference/layouts/
• cart.md · reference/layouts/
• checkout.md · reference/layouts/
• home-page.md · reference/layouts/
• order-confirmation.md · reference/layouts/
• product-details.md · reference/layouts/
• product-listing.md · reference/layouts/
• static-pages.md · reference/layouts/
• medusa.md · reference/
• mobile-responsiveness.md · reference/
• seo.md · reference/

SKILL.md (first lines)

# Ecommerce Storefront Best Practices

Comprehensive guidance for building modern, high-converting ecommerce storefronts covering UI/UX patterns, component design, layout structures, SEO optimization, and mobile responsiveness.

## When to Apply

**ALWAYS load this skill when working on ANY storefront task:**

- **Adding checkout page/flow** - Payment, shipping, order placement
- **Implementing cart** - Cart page, cart popup, add to cart functionality
- **Building product pages** - Product details, product listings, product grids
- **Creating navigation** - Navbar, megamenu, footer, mobile menu
- **Integrating Medusa backend** - SDK setup, cart, products, payment
- **Any storefront component** - Homepage, search, filters, account pages
- Building new ecommerce storefronts from scratch
- Improving existing shopping experiences and conversion rates
- Optimizing for usability, accessibility, and SEO
- Designing mobile-responsive ecommerce experiences

**Example prompts that should trigger this skill:**
- "Add a checkout page"
- "Implement shopping cart"
- "Create product listing page"
- "Connect to Medusa backend"
- "Add navigation menu"
- "Build homepage for store"

## CRITICAL: Load Reference Files When Needed

**⚠️ ALWAYS load `reference/design.md` BEFORE creating ANY UI component**
- Discovers existing design tokens (colors, fonts, spacing, patterns)
- Prevents introducing inconsistent styles
- Provides guardrails for maintaining brand consistency
- **Required for every component, not just new storefronts**

**Load these references based on what you're implementing:**

- **Starting a new storefront?** → MUST load `reference/design.md` first to discover user preferences
- **Connecting to backend API?** → MUST load `reference/connecting-to-backend.md` first
- **Connecting to Medusa backend?** → MUST load `reference/medusa.md` for SDK setup, pricing, regions, and Medusa patterns
- **Implementing homepage?** → MUST load `reference/components/navbar.md`, `reference/components/hero.md`, `reference/components/footer.md`, and `reference/layouts/home-page.md`
- **Implementing navigation?** → MUST load `reference/components/navbar.md` and optionally `reference/components/megamenu.md`
- **Building product listing?** → MUST load `reference/layouts/product-listing.md` first
- **Building product details?** → MUST load `reference/layouts/product-details.md` first
- **Implementing checkout?** → MUST load `reference/layouts/checkout.md` first
- **Optimizing for SEO?** → MUST load `reference/seo.md` first
- **Optimizing for mobile?** → MUST load `reference/mobile-responsiveness.md` first

**Minimum requirement:** Load at least 1-2 reference files relevant to your specific task before implementing.

## Planning and Implementation Workflow

**IMPORTANT: If you create a plan for implementing storefront features, include the following in your plan:**

When implementing each component, page, layout, or feature in the plan:
1. **Refer back to this skill** before starting implementation
2. **Load relevant reference files** listed above for the specific component/page you're building
3. **Follow the patterns and guidance** in the reference files
4. **Check common mistakes** sections to avoid known pitfalls

**Example plan structure:**

```
Task 1: Implement Navigation
- Load reference/components/navbar.md
- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)
- Refer to skill for common mistakes (e.g., hardcoding categories)

Task 2: Implement Product Listing Page
- Load reference/layouts/product-listing.md
- Follow pagination/filtering patterns from product-listing.md
- Use reference/components/product-card.md for product grid items
- Check skill for backend integration guidance

Task 3: Implement Checkout Flow
- Load reference/layouts/checkout.md
- Load reference/medusa.md for Medusa payment integration
- Follow component architecture recommendations (separate step components)
- Refer to skill for payment method fetching requirements
```

**Why this matters:**
- Plans provide high-level strategy
- Reference files provide detailed implementation patterns
- Skill file contains critical mistakes to avoid
- Following this workflow ensures consistency and best practices

## Critical Ecommerce-Specific Patterns

### Accessibility
- **CRITICAL: Cart count updates require `aria-live="polite"`** - Screen readers won't announce without it
- Ensure keyboard navigation for all cart/checkout interactions

### Mobile
- **Sticky bottom elements MUST use `env(safe-area-inset-bottom)`** - iOS home indicator will cut off purchase buttons otherwise
- 44px minimum touch targets for cart actions, variant selectors, quantity buttons

### Performance
- **ALWAYS add `loading="lazy"` to product images below fold** - Don't rely on browser defaults
- Optimize product images for mobile (<500KB) - Most ecommerce traffic is mobile

### Conversion Optimization
- Clear CTAs throughout shopping flow
- Minimal friction in checkout (guest checkout if supported)
- Trust signals (reviews, security badges, return policy) near purchase buttons
- Clear pricing and shipping information upfront

### SEO
- **Product schema (JSON-LD) required** - Critical for Google Shopping and rich snippets
- Use [PageSpeed Insights](https://pagespeed.web.dev/) to measure Core Web Vitals

### Visual Design
- **NEVER use emojis** in storefront UI - Use icons or images instead (unprofessional, accessibility issues)

### Backend Integration
- **Backend detection**: If in monorepo, check for backend directory. If unsure, ask user which backend is used.
- **NEVER hardcode dynamic content**: Always fetch categories, regions, products, shipping options, etc. from backend - they change frequently
- Never assume API structure - verify endpoints and data formats

From vinitvijal/Meow-Munch-QodeML-Labs, MIT.

More from vinitvijal/Meow-Munch-QodeML-Labs