Initial commit

.agents/skills/storefront-best-practices/reference/components/product-card.md

@@ -0,0 +1,125 @@
+# Product Card Component
+
+## Contents
+
+- [Overview](#overview)
+- [Price Display (Ecommerce-Specific)](#price-display-ecommerce-specific)
+- [Action Buttons and Variant Handling](#action-buttons-and-variant-handling)
+- [Badges and Labels](#badges-and-labels)
+- [Mobile Considerations](#mobile-considerations)
+- [Ecommerce Checklist](#ecommerce-checklist)
+
+## 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)