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.

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

This session only. Nothing lands on disk.

referencecomponentshero.md

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

Hero Section Component

Contents

Overview

Hero section is the prominent banner at top of homepage, immediately below navigation. First content users see - sets tone for shopping experience.

Assumed knowledge: AI agents know how to build full-width banners with images and text overlays. This focuses on ecommerce hero patterns.

Key requirements:

  • Above the fold (immediately visible)
  • Clear value proposition or promotional message
  • High-quality imagery
  • Strong call-to-action
  • Fast loading (critical for first impression)

Hero Types and When to Use

1. Full-Width Banner (Most Common)

Characteristics:

  • Spans entire viewport width
  • Large background image or video
  • Text overlay with headline + CTA
  • Single focused message

Best for:

  • Seasonal campaigns ("Summer Sale")
  • New product arrivals
  • Brand storytelling
  • Single promotional focus
  • Simple, bold message

Example: Background image of products, headline "40% Off Summer Sale", CTA "Shop Now"

2. Split Hero (Image + Content)

Characteristics:

  • 50/50 or 60/40 split layout
  • Image on one side, text content on other
  • No text overlay on image
  • Cleaner, easier to read

Best for:

  • Product launches (show product clearly)
  • Detailed messaging (more text space)
  • Accessibility (no text-on-image contrast issues)
  • Professional/B2B stores

Example: Product image (left 50%), headline + benefits + CTA (right 50%)

3. Minimal Hero

Characteristics:

  • Large image, minimal text
  • Image does storytelling
  • Subtle headline, small CTA
  • Emphasis on visual brand

Best for:

  • Luxury brands (sophisticated aesthetic)
  • Lifestyle brands (aspirational imagery)
  • Photography-focused products
  • Brand over promotion

4. Video Hero

Characteristics:

  • Background video (muted, looping)
  • Text overlay on video
  • Fallback image for slow connections

Best for:

  • Fashion brands (show products in motion)
  • Lifestyle products (demonstrate usage)
  • High-budget campaigns
  • Brand storytelling with motion

Important: Auto-play muted, provide play/pause controls, optimize file size (<5MB), use poster image fallback.

5. Product Showcase Hero

Characteristics:

  • Multiple featured products in hero
  • Grid of 2-4 products
  • Quick links to product pages
  • Less promotional, more discovery

Best for:

  • Multi-category stores
  • Product-focused (not campaign-focused)
  • Quick product discovery
  • Minimal marketing, maximum browsing

Content Guidelines

Headline best practices:

  • Short and impactful (5-10 words)
  • Clear value proposition ("Free Shipping on All Orders")
  • Urgency if time-sensitive ("48-Hour Flash Sale")
  • Benefit-focused ("Upgrade Your Style")
  • Avoid generic ("Welcome to Our Store")

Subtext (optional):

  • 10-20 words maximum
  • Expand on headline benefit
  • Add context or details
  • Not always necessary (clean design)

Call-to-action:

  • Single primary CTA button
  • Action-oriented text ("Shop Now", "Explore Category", "Get Started")
  • High contrast (stands out on image)
  • Large enough (48px height minimum)
  • Link to relevant landing page (sale, category, product listing)

Image selection:

  • High quality, professional photography
  • Shows products or lifestyle context
  • Represents brand aesthetic
  • Optimized for web (<500KB)
  • Responsive (different crops for mobile)
  • Ensure text overlay is readable (adequate contrast)

Multiple Heroes (Carousel)

Carousel pattern:

  • 2-4 slides rotating automatically
  • Each slide = independent hero (own message, image, CTA)
  • Auto-rotate every 5-7 seconds (slow enough to read)
  • Manual controls (prev/next arrows, dot indicators)
  • Pause on hover (accessibility)

When to use carousel:

  • Multiple concurrent campaigns (Winter Sale + New Arrivals)
  • Different audience segments (Men/Women/Kids)
  • Seasonal variety showcase
  • Limited above-fold space

When NOT to use carousel:

  • Single focused campaign (just use one hero)
  • Users rarely see slides beyond first (carousel blindness)
  • Slower page load (multiple images)
  • Accessibility concerns (auto-rotating content)

Carousel best practices:

  • Max 3-4 slides (more = ignored)
  • First slide most important (most viewed)
  • Consistent layout across slides
  • Clear indicators showing progress
  • Don't rely on later slides for critical info
  • Pause on interaction (hover, focus)

Mobile Hero

Mobile adjustments (CRITICAL):

Layout:

  • Full-width, portrait aspect (2:3 or 3:4)
  • Vertical composition (text overlays center/bottom)
  • Larger text for readability
  • Simplified message (shorter headline)

Split hero on mobile:

  • Stack vertically (image top, text bottom)
  • Don't use side-by-side (too cramped)

Performance:

  • Smaller images (<300KB)
  • Different image crop for mobile portrait
  • Use srcset or <picture> for responsive images
  • Consider static image instead of video (mobile data)

Touch interactions:

  • Large CTA button (48px height minimum)
  • Easy carousel controls (if used)
  • Swipe gesture for carousel slides

Performance

Critical for first impression:

Image optimization:

  • WebP format with JPEG fallback
  • Lazy load below-fold content (not hero - it's above fold)
  • Responsive images (mobile gets smaller size)
  • Target: <500KB desktop, <300KB mobile
  • Use CDN for faster delivery

Video optimization:

  • <5MB file size maximum
  • Muted, autoplay, loop
  • Poster image (shows before video loads)
  • Fallback to image on slow connections
  • Consider not using on mobile (data/performance)

LCP optimization:

  • Hero image is often Largest Contentful Paint
  • Preload hero image: <link rel="preload" as="image" href="hero.jpg">
  • Inline critical CSS for hero
  • Avoid layout shift (set image dimensions)

Target metrics:

  • LCP < 2.5 seconds
  • No layout shift (CLS < 0.1)
  • Fast interaction (hero CTA clickable immediately)

Checklist

Essential features:

  • Above the fold (immediately visible)
  • Clear headline (5-10 words, value proposition)
  • High-quality image (professional, on-brand)
  • Primary CTA button (action-oriented, high contrast)
  • Fast loading (<500KB image desktop, <300KB mobile)
  • Responsive images (different sizes/crops for devices)
  • Mobile: Portrait aspect ratio (2:3 or 3:4)
  • Mobile: Vertical text placement (center/bottom)
  • Mobile: Large CTA (48px height minimum)
  • Text overlay readable (adequate contrast, background overlay)
  • If carousel: Max 3-4 slides
  • If carousel: Auto-rotate 5-7 seconds
  • If carousel: Pause on hover/focus
  • If carousel: Manual controls (arrows, dots)
  • If video: Muted, autoplay, loop
  • If video: Poster image fallback
  • If video: <5MB file size
  • Preload hero image (LCP optimization)
  • No layout shift (set image dimensions)
  • ARIA labels on carousel controls
  • Keyboard accessible (Tab to CTA, arrow keys for carousel)

Source: SKILL.md on GitHub

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

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