Setting the file. One moment. Hero · Storefront Best Practices · medusajs/medusa-agent-skills · Skills DocsMcloud
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.
- Above the fold (immediately visible)
- Clear value proposition or promotional message
- High-quality imagery
- Strong call-to-action
- Fast loading (critical for first impression)
- Spans entire viewport width
- Large background image or video
- Text overlay with headline + CTA
- Single focused message
- 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”
- 50/50 or 60/40 split layout
- Image on one side, text content on other
- No text overlay on image
- Cleaner, easier to read
- 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%)
- Large image, minimal text
- Image does storytelling
- Subtle headline, small CTA
- Emphasis on visual brand
- Luxury brands (sophisticated aesthetic)
- Lifestyle brands (aspirational imagery)
- Photography-focused products
- Brand over promotion
- Background video (muted, looping)
- Text overlay on video
- Fallback image for slow connections
- 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.
- Multiple featured products in hero
- Grid of 2-4 products
- Quick links to product pages
- Less promotional, more discovery
- Multi-category stores
- Product-focused (not campaign-focused)
- Quick product discovery
- Minimal marketing, maximum browsing
- 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”)
- 10-20 words maximum
- Expand on headline benefit
- Add context or details
- Not always necessary (clean design)
- 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)
- 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)
- 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)
- 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)
- 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 adjustments (CRITICAL):
- Full-width, portrait aspect (2:3 or 3:4)
- Vertical composition (text overlays center/bottom)
- Larger text for readability
- Simplified message (shorter headline)
- Stack vertically (image top, text bottom)
- Don’t use side-by-side (too cramped)
- Smaller images (<300KB)
- Different image crop for mobile portrait
- Use
srcset or <picture> for responsive images
- Consider static image instead of video (mobile data)
- Large CTA button (48px height minimum)
- Easy carousel controls (if used)
- Swipe gesture for carousel slides
Critical for first impression:
- 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
- <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)
- 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)
- LCP < 2.5 seconds
- No layout shift (CLS < 0.1)
- Fast interaction (hero CTA clickable immediately)
- Not done: Above the fold (immediately visible)
- Not done: Clear headline (5-10 words, value proposition)
- Not done: High-quality image (professional, on-brand)
- Not done: Primary CTA button (action-oriented, high contrast)
- Not done: Fast loading (<500KB image desktop, <300KB mobile)
- Not done: Responsive images (different sizes/crops for devices)
- Not done: Mobile: Portrait aspect ratio (2:3 or 3:4)
- Not done: Mobile: Vertical text placement (center/bottom)
- Not done: Mobile: Large CTA (48px height minimum)
- Not done: Text overlay readable (adequate contrast, background overlay)
- Not done: If carousel: Max 3-4 slides
- Not done: If carousel: Auto-rotate 5-7 seconds
- Not done: If carousel: Pause on hover/focus
- Not done: If carousel: Manual controls (arrows, dots)
- Not done: If video: Muted, autoplay, loop
- Not done: If video: Poster image fallback
- Not done: If video: <5MB file size
- Not done: Preload hero image (LCP optimization)
- Not done: No layout shift (set image dimensions)
- Not done: ARIA labels on carousel controls
- Not done: Keyboard accessible (Tab to CTA, arrow keys for carousel)
reference/components/hero.md