Setting the file. One moment. Mcloud
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.
- 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)
- 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%)
- 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)
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
Key challenge: Products with variants require variant selection before adding to cart.
- Add first variant by default - Click adds
product.variants[0]. Fast for simple products (1-2 variants).
- Redirect to product page - Navigate to detail page for variant selection. Best for complex products (size + color + material).
- Quick View modal - Variant selector in modal. Good middle ground (desktop only).
- 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
- 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.
Badge priority (show max 1-2 per card):
- Out of Stock (highest) - Gray/black overlay on image, disables add-to-cart
- Sale/Discount - “Sale” or “-20%”, red/accent, top-left corner
- New - “New” for recent products, blue/green, top-left corner
- Low Stock (optional) - “Only 3 left”, orange, creates urgency
Display: Top-left corner (except Out of Stock overlay), small but readable, high contrast.
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)
No hover states on mobile:
- Don’t hide actions behind hover
- Always show primary button
- Use tap states (active state) instead of hover
- Not done: Clear product image (optimized, lazy loaded)
- Not done: Product title (truncated to 2 lines max)
- Not done: Price prominently displayed
- Not done: Sale price shown correctly (struck-through original price)
- Not done: Currency symbol included
- Not done: For Medusa: Price displayed as-is (not divided by 100)
- Not done: Add to Cart button with loading state
- Not done: Variant handling strategy (first variant, redirect, or Quick View)
- Not done: Optimistic UI update (cart count immediately)
- Not done: Success feedback (toast or cart popup)
- Not done: Don’t navigate away after adding to cart
- Not done: Out of Stock badge (disables add-to-cart)
- Not done: Sale badge when price reduced
- Not done: Responsive grid (1 col mobile, 2-3 tablet, 3-4 desktop)
- Not done: Touch-friendly on mobile (44px buttons)
- Not done: Keyboard accessible (focus states, Enter to activate)
- Not done: Descriptive alt text on images
- Not done: Semantic HTML (
<article> wrapper)
reference/components/product-card.md