skilld
All skills
medusajs avatar

/storefront-best-practices

@f08f937 official
by Medusamedusajs/medusa-agent-skills225 stars
29

ALWAYS use this skill when working on ecommerce storefronts, online stores, shopping sites. Use for ANY storefront component including checkout pages, cart, payment flows, product pages, product listings, navigation, homepage, or ANY page/component in a storefront. CRITICAL for adding checkout, implementing cart, integrating Medusa backend, or building any ecommerce functionality. Framework-agnostic (Next.js, SvelteKit, TanStack Start, React, Vue). Provides patterns, decision frameworks, backend integration guidance.

Ask your Agent

Use this Skill: https://skilld.dev/gh/medusajs/medusa-agent-skills/storefront-best-practices

This session only. Nothing lands on disk.

referencecomponentsproduct-card.md

≈1.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Product Card Component

Contents

Overview

Product cards display products in grids (product listings, search results, related products). Key ecommerce considerations: clear pricing, quick add-to-cart, and stock indicators.

Assumed knowledge: AI agents know how to build cards with images, titles, and buttons. This guide focuses on ecommerce-specific patterns.

Key Ecommerce Requirements

  • Clear, prominent pricing (including sale prices)
  • Variant handling for add-to-cart
  • Stock status indicators
  • Sale/New/Out of Stock badges
  • Responsive grid (1 col mobile, 2-3 tablet, 3-4 desktop)
  • Fast image loading (lazy load, optimized)

Price Display (Ecommerce-Specific)

Regular vs Sale Pricing

Sale price display:

  • Sale price: Larger, bold, red or accent color
  • Original price: Smaller, struck through ($79.99), gray
  • Position sale price before original price
  • Optional: Show discount percentage badge (-20%)

Format consistently:

  • Always include currency symbol ($49.99)
  • Consistent decimals ($49.99 not $49.9 or $50)
  • For Medusa: Display prices as-is (no divide by 100)

Price Range (Multiple Variants)

When variants have different prices:

  • Show "From $49" or "$49 - $79"
  • Makes it clear price varies by selection
  • Don't show range if all variants same price

Action Buttons and Variant Handling

Add to Cart with Variants (CRITICAL)

Key challenge: Products with variants require variant selection before adding to cart.

Handling strategies:

  1. Add first variant by default - Click adds product.variants[0]. Fast for simple products (1-2 variants).
  2. Redirect to product page - Navigate to detail page for variant selection. Best for complex products (size + color + material).
  3. Quick View modal - Variant selector in modal. Good middle ground (desktop only).

Decision:

  • Simple products (1-2 variants): Add first variant
  • Fashion/apparel with sizes: Require size selection (redirect or Quick View)
  • Complex products (3+ variant types): Redirect to product page

Button behavior:

  • Loading state ("Adding..."), disable during loading
  • Optimistic UI update (cart count immediately)
  • Success feedback (toast, cart popup, or checkmark)
  • Don't navigate away (stay on listing page)
  • Handle errors (out of stock, API failure)

Wishlist button (optional): Heart icon, top-right over image. Empty when not saved, filled (red) when saved. Refer to wishlist.md for more details.

Badges and Labels

Badge priority (show max 1-2 per card):

  1. Out of Stock (highest) - Gray/black overlay on image, disables add-to-cart
  2. Sale/Discount - "Sale" or "-20%", red/accent, top-left corner
  3. New - "New" for recent products, blue/green, top-left corner
  4. Low Stock (optional) - "Only 3 left", orange, creates urgency

Display: Top-left corner (except Out of Stock overlay), small but readable, high contrast.

Mobile Considerations

Grid Layout

Mobile-specific adjustments:

  • 2 columns maximum on mobile (never 3+)
  • Larger touch targets (44px minimum for buttons)
  • Always show "Add to Cart" button (no hover-only)
  • Simplified content (hide optional elements like brand)
  • Smaller images for performance (<400px wide)

Touch Interactions

No hover states on mobile:

  • Don't hide actions behind hover
  • Always show primary button
  • Use tap states (active state) instead of hover

Ecommerce Checklist

Essential features:

  • Clear product image (optimized, lazy loaded)
  • Product title (truncated to 2 lines max)
  • Price prominently displayed
  • Sale price shown correctly (struck-through original price)
  • Currency symbol included
  • For Medusa: Price displayed as-is (not divided by 100)
  • Add to Cart button with loading state
  • Variant handling strategy (first variant, redirect, or Quick View)
  • Optimistic UI update (cart count immediately)
  • Success feedback (toast or cart popup)
  • Don't navigate away after adding to cart
  • Out of Stock badge (disables add-to-cart)
  • Sale badge when price reduced
  • Responsive grid (1 col mobile, 2-3 tablet, 3-4 desktop)
  • Touch-friendly on mobile (44px buttons)
  • Keyboard accessible (focus states, Enter to activate)
  • Descriptive alt text on images
  • Semantic HTML (<article> wrapper)

Source: SKILL.md on GitHub

Third-party checks

1 warning16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill consists entirely of comprehensive reference documentation and design patterns for building ecommerce storefronts with a focus on Medusa backend integration. It contains no executable scripts, code, or security risks.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    25/28 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at f08f937. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 8 months ago

README badge

README badge for medusajs/medusa-agent-skills/storefront-best-practices