Setting the file. One moment.
Mobile Responsiveness · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs
Back to the top of the page Mcloud
Over 60% of ecommerce traffic is mobile. Mobile-first design is essential for conversion.
Mobile-first CSS (min-width media queries)
44x44px minimum touch targets
Sticky header with cart access
Large form inputs (48px height minimum)
Optimized images for mobile
Fast loading (LCP < 2.5s)
Assumed knowledge : AI agents already know mobile-first design principles, breakpoints, and responsive CSS. This guide focuses on ecommerce-specific mobile patterns.
Cart access always visible:
Sticky header with cart icon (top-right)
Or: Sticky bottom navigation with cart
Never hide cart in hamburger drawer
Shows count badge, updates in real-time
Sticky “Add to Cart” bar (product pages):
Fixed at bottom of screen
Shows: Price + “Add to Cart” button
Appears after scrolling past fold
Always accessible without scrolling
CRITICAL: Must use env(safe-area-inset-bottom) for iOS devices (see Safe Area Insets section)Significantly higher conversion rates
Bottom navigation (optional pattern):
Consider for mobile-heavy stores (>70% mobile traffic)
4-5 primary actions: Home, Categories, Cart, Account, Search
Fixed at bottom (easier thumb access)
Icons + labels for clarity
Mobile-first brands (fashion, beauty)
Younger demographic (18-34)
App-like experience desired
Desktop-heavy traffic
Complex navigation needs (>5 items)
B2B stores (desktop-focused)
Full-width swipeable carousel
Pinch to zoom
Tap to open full-screen view
Dot indicators (1/5, 2/5)
“Filters” button with badge count (e.g., “Filters (3)”)
Slide-out drawer (full-screen or 80% width)
Accordion sections for filter categories
“Apply” button at bottom (batch filtering)
“Clear All” option at top
Why batch filtering on mobile:
Prevents multiple re-renders on slow connections
User adjusts multiple filters before applying
Less disruptive mobile UX
Digital wallets priority (CRITICAL for mobile conversion):
Apple Pay / Google Pay buttons prominent at top (if supported in ecommerce backend)
Can improve mobile checkout conversion by 20-40%
One-click payment with pre-filled shipping addresses (if supported in ecommerce backend)
Consider making digital wallet the default on mobile
Decision: Order summary placement
Collapsible at top (recommended): Saves screen space for form, expandable for review
Fixed at bottom: Always visible but takes space from form
Use collapsible on mobile to prioritize form completion
Single-column layout (never multi-column on mobile)
44-48px input height minimum
Proper keyboard types (inputMode="email", "numeric", "tel")
Autocomplete attributes for autofill (autocomplete="email", "name", "address-line1")
Consider single-page layout over multi-step (less friction on mobile)
Standard touch targets: 44x44px minimum for all interactive elements. Pay special attention to:
Filter checkboxes on product listings
Quantity +/- buttons on product pages
Small action buttons on product cards
Modal close buttons
Swipe gestures for ecommerce:
Product image galleries (critical - users expect swipeable images)
Related product sliders
Category carousels
Mobile input optimization:
16px minimum font size for inputs (prevents iOS auto-zoom)
Proper inputMode attributes: "email", "numeric", "tel"
Autocomplete attributes: autocomplete="email", "name", "address-line1"
Ecommerce performance priorities:
Product images (highest impact): Optimize for mobile (<500KB), lazy load below-fold, responsive images with appropriate sizesOptimistic UI : Cart count updates immediately, instant feedback on add to cartSkeleton screens : Show loading placeholders for product grids, not blank pages Critical mobile performance issues:
Unoptimized product images (>1MB) - most common issue
Loading entire product catalog at once - use pagination or infinite scroll
Heavy analytics scripts on checkout - defer to post-purchase
Target : LCP < 2.5s, mobile-optimized images, server-side rendering for product pages
Use env(safe-area-inset-*) to handle iOS notches and rounded corners on:
Sticky headers (top inset)
Sticky bottom navigation or add-to-cart bars (bottom inset)
Full-screen modals
Critical for ecommerce : Bottom “Add to Cart” bars will be cut off by iOS home indicator without bottom inset (~34px). Test on real iOS devices with notches.
Ecommerce-specific mobile issues:
Hiding cart in drawer - Cart icon hidden in hamburger menu. Keep cart always visible in header (top-right).
No sticky cart access - Cart scrolls off screen on product pages. Use sticky header or sticky bottom “Add to Cart” bar.
Desktop-sized images - Serving 2MB+ product images to mobile. Use responsive images optimized for mobile (<500KB).
Poor form experience - Small inputs, wrong keyboards, no autocomplete. Use 48px inputs, proper inputMode, autocomplete attributes.
Hover-only interactions - Quick view, wishlist only work on hover. Add tap handlers, show on tap instead.
Ignoring safe area insets - Bottom “Add to Cart” bars cut off by iOS home indicator. Use env(safe-area-inset-bottom) for sticky bottom elements.
No digital wallet options - Missing Apple Pay/Google Pay on mobile checkout. Mobile users expect one-tap checkout options.
Essential mobile optimizations:
Not done: Mobile-first CSS (min-width media queries)Not done: 44x44px minimum touch targets throughoutNot done: Adequate spacing between interactive elements (8-16px)Not done: Sticky header with cart icon (always visible)Not done: Or: Sticky bottom “Add to Cart” bar on product pagesNot done: Large form inputs (48px height minimum)Not done: Appropriate input types (inputMode="email", "numeric", "tel")Not done: Swipeable image galleries on product pagesNot done: Filter drawer with batch apply on product listingsNot done: Digital wallets prominent in checkout (Apple Pay, Google Pay)Not done: Collapsible order summary in checkoutNot done: Optimized images for mobile (<500KB)Not done: Lazy loading for below-fold contentNot done: Safe area insets for iOS notches (sticky elements)Not done: 16px minimum font size (prevents iOS auto-zoom)Not done: Test on real mobile devices (not just Chrome DevTools)Not done: Core Web Vitals within targets (LCP < 2.5s, CLS < 0.1, INP < 200ms) reference/mobile-responsiveness.md