orion/docs/frontend/storefront/ecommerce-components-proposal.md

# E-commerce Components Proposal

**Version:** 1.0
**Created:** December 2025
**Status:** Proposal
**Author:** Development Team

---

## Overview

This document proposes a comprehensive set of reusable Jinja macro components for the shop frontend. These components will standardize the e-commerce experience across all store shops while supporting store-specific theming via CSS variables.

---

## Design Principles

1. **Store Theming** - Use CSS variables (`var(--color-primary)`) for brand colors
2. **Mobile First** - Responsive design starting from mobile
3. **Performance** - Lazy loading, optimized images, minimal JS
4. **Accessibility** - WCAG 2.1 AA compliant
5. **Consistency** - Same UX patterns across all shops

---

## Proposed Components

### Priority 1: Core Shopping Components

#### 1.1 Product Card
**File:** `app/templates/shared/macros/storefront/product-card.html`

A versatile product card for grids, carousels, and lists.

```jinja
{{ product_card(
    product=product,
    show_store=false,
    show_rating=true,
    show_quick_add=true,
    size='md',           {# sm, md, lg #}
    layout='vertical'    {# vertical, horizontal #}
) }}
```

**Features:**
- Product image with lazy loading
- Sale badge / "New" badge
- Product title (truncated)
- Price (with strikethrough for sales)
- Star rating
- Quick "Add to Cart" button
- Wishlist heart icon
- Hover effects

**Variants:**
| Size | Use Case |
|------|----------|
| `sm` | Mobile grids, sidebars |
| `md` | Standard product grids |
| `lg` | Featured products, hero sections |

---

#### 1.2 Product Grid
**File:** `app/templates/shared/macros/storefront/product-grid.html`

Responsive grid layout for product listings.

```jinja
{{ product_grid(
    products=products,
    columns={'sm': 2, 'md': 3, 'lg': 4},
    gap='md',
    show_empty_state=true
) }}
```

**Features:**
- Responsive column configuration
- Loading skeleton state
- Empty state with CTA
- "Load more" or pagination integration

---

#### 1.3 Add to Cart Button
**File:** `app/templates/shared/macros/storefront/add-to-cart.html`

Standardized add-to-cart functionality.

```jinja
{{ add_to_cart_button(
    product_id='product.id',
    variant_id='selectedVariant?.id',
    quantity_model='quantity',
    show_quantity=true,
    size='md',
    full_width=false
) }}
```

**Features:**
- Loading state during add
- Success animation
- Out of stock state
- Quantity selector integration (uses `number_stepper`)
- "Added!" feedback

---

#### 1.4 Quantity Selector (Shop Version)
**File:** Already exists as `number_stepper` in `inputs.html`

Shop-specific wrapper with stock validation:

```jinja
{{ storefront_quantity_selector(
    model='quantity',
    max='product.stock',
    disabled_var='addingToCart',
    out_of_stock_var='product.stock === 0'
) }}
```

---

### Priority 2: Cart Components

#### 2.1 Mini Cart (Header Dropdown)
**File:** `app/templates/shared/macros/storefront/mini-cart.html`

Dropdown cart preview in the header.

```jinja
{{ mini_cart(
    cart_var='cart',
    max_items=3,
    show_checkout_button=true
) }}
```

**Features:**
- Cart item count badge
- Item thumbnails
- Quick quantity adjust
- Remove item button
- Subtotal display
- "View Cart" and "Checkout" CTAs

---

#### 2.2 Cart Item Row
**File:** `app/templates/shared/macros/storefront/cart-item.html`

Individual cart line item.

```jinja
{{ cart_item(
    item='item',
    index='index',
    show_image=true,
    editable=true,
    compact=false
) }}
```

**Features:**
- Product thumbnail
- Product name + variant info
- Unit price
- Quantity stepper (using `number_stepper` with `size='sm'`)
- Line total
- Remove button
- Stock warning if low

---

#### 2.3 Cart Summary
**File:** `app/templates/shared/macros/storefront/cart-summary.html`

Order summary sidebar/section.

```jinja
{{ cart_summary(
    cart_var='cart',
    show_promo_code=true,
    show_shipping_estimate=true,
    checkout_url='/checkout'
) }}
```

**Features:**
- Subtotal
- Discount code input
- Applied discounts
- Estimated shipping
- Tax display
- Order total
- Checkout CTA
- Secure payment badges

---

### Priority 3: Product Detail Components

#### 3.1 Product Gallery
**File:** `app/templates/shared/macros/storefront/product-gallery.html`

Image gallery with thumbnails and zoom.

```jinja
{{ product_gallery(
    images='product.images',
    show_thumbnails=true,
    enable_zoom=true,
    enable_fullscreen=true
) }}
```

**Features:**
- Main image display
- Thumbnail navigation
- Image zoom on hover
- Fullscreen lightbox
- Swipe support on mobile
- Video support

---

#### 3.2 Variant Selector
**File:** `app/templates/shared/macros/storefront/variant-selector.html`

Product variant selection (size, color, etc.).

```jinja
{{ variant_selector(
    variants='product.variants',
    selected_var='selectedVariant',
    type='buttons'    {# buttons, dropdown, swatches #}
) }}
```

**Variant Types:**
- **Buttons** - Size selection (S, M, L, XL)
- **Dropdown** - Many options
- **Swatches** - Color selection with preview

**Features:**
- Out of stock variants disabled
- Low stock warning
- Price change on selection
- Image change on color selection

---

#### 3.3 Product Info Block
**File:** `app/templates/shared/macros/storefront/product-info.html`

Product details section.

```jinja
{{ product_info(
    product='product',
    show_sku=true,
    show_stock=true,
    show_store=false
) }}
```

**Features:**
- Product title (H1)
- Price display (sale price handling)
- Rating stars + review count
- Short description
- SKU display
- Stock status
- Store name (marketplace)

---

#### 3.4 Product Tabs
**File:** `app/templates/shared/macros/storefront/product-tabs.html`

Tabbed product information.

```jinja
{{ product_tabs(
    product='product',
    tabs=['description', 'specifications', 'reviews', 'shipping']
) }}
```

**Tab Options:**
- Description (HTML content)
- Specifications (key-value table)
- Reviews (review list + form)
- Shipping info
- Returns policy

---

### Priority 4: Navigation & Discovery

#### 4.1 Category Navigation
**File:** `app/templates/shared/macros/storefront/category-nav.html`

Category browsing sidebar/menu.

```jinja
{{ category_nav(
    categories='categories',
    current_category='currentCategory',
    show_count=true,
    collapsible=true
) }}
```

**Features:**
- Nested category tree
- Product counts
- Active state highlighting
- Collapsible sections
- Mobile drawer version

---

#### 4.2 Breadcrumbs
**File:** `app/templates/shared/macros/storefront/breadcrumbs.html`

Navigation breadcrumb trail.

```jinja
{{ storefront_breadcrumbs(
    items=[
        {'label': 'Home', 'url': '/'},
        {'label': 'Electronics', 'url': '/category/electronics'},
        {'label': 'Headphones', 'url': none}
    ]
) }}
```

---

#### 4.3 Search Bar
**File:** `app/templates/shared/macros/storefront/search-bar.html`

Product search with autocomplete.

```jinja
{{ search_bar(
    placeholder='Search products...',
    show_suggestions=true,
    show_categories=true
) }}
```

**Features:**
- Autocomplete suggestions
- Recent searches
- Category filter
- Voice search (optional)
- Mobile fullscreen mode

---

#### 4.4 Filter Sidebar
**File:** `app/templates/shared/macros/storefront/filter-sidebar.html`

Product filtering panel.

```jinja
{{ filter_sidebar(
    filters='availableFilters',
    active_filters='activeFilters',
    show_price_range=true,
    show_rating_filter=true
) }}
```

**Filter Types:**
- Checkbox (brand, size)
- Color swatches
- Price range slider
- Rating stars
- In-stock toggle

---

### Priority 5: Social Proof & Trust

#### 5.1 Star Rating
**File:** `app/templates/shared/macros/storefront/star-rating.html`

Reusable star rating display.

```jinja
{{ star_rating(
    rating=4.5,
    max=5,
    size='md',
    show_count=true,
    count=127
) }}
```

---

#### 5.2 Review Card
**File:** `app/templates/shared/macros/storefront/review-card.html`

Individual product review.

```jinja
{{ review_card(
    review='review',
    show_verified_badge=true,
    show_helpful_buttons=true
) }}
```

**Features:**
- Reviewer name/avatar
- Star rating
- Review date
- Review text
- Verified purchase badge
- Helpful/Not helpful buttons
- Review images

---

#### 5.3 Trust Badges
**File:** `app/templates/shared/macros/storefront/trust-badges.html`

Trust and security indicators.

```jinja
{{ trust_badges(
    badges=['secure_payment', 'free_shipping', 'returns', 'support']
) }}
```

**Badge Options:**
- Secure payment
- Free shipping over X
- Easy returns
- 24/7 support
- Money back guarantee
- SSL secured

---

### Priority 6: Promotional Components

#### 6.1 Sale Banner
**File:** `app/templates/shared/macros/storefront/sale-banner.html`

Promotional banner with countdown.

```jinja
{{ sale_banner(
    title='Summer Sale',
    subtitle='Up to 50% off',
    end_date='2025-08-31',
    show_countdown=true,
    cta_text='Shop Now',
    cta_url='/sale'
) }}
```

---

#### 6.2 Product Badge
**File:** `app/templates/shared/macros/storefront/product-badge.html`

Product overlay badges.

```jinja
{{ product_badge(type='sale', value='-20%') }}
{{ product_badge(type='new') }}
{{ product_badge(type='bestseller') }}
{{ product_badge(type='low_stock', value='Only 3 left') }}
```

---

#### 6.3 Recently Viewed
**File:** `app/templates/shared/macros/storefront/recently-viewed.html`

Recently viewed products carousel.

```jinja
{{ recently_viewed(
    products='recentlyViewed',
    max_items=6,
    title='Recently Viewed'
) }}
```

---

## Implementation Phases

### Phase 1: Core Components (Week 1-2)
- [ ] Product Card
- [ ] Product Grid
- [ ] Add to Cart Button
- [ ] Mini Cart
- [ ] Cart Item Row
- [ ] Cart Summary

### Phase 2: Product Detail (Week 3-4)
- [ ] Product Gallery
- [ ] Variant Selector
- [ ] Product Info Block
- [ ] Product Tabs
- [ ] Star Rating

### Phase 3: Navigation (Week 5-6)
- [ ] Category Navigation
- [ ] Breadcrumbs
- [ ] Search Bar
- [ ] Filter Sidebar

### Phase 4: Social & Promo (Week 7-8)
- [ ] Review Card
- [ ] Trust Badges
- [ ] Sale Banner
- [ ] Product Badge
- [ ] Recently Viewed

---

## CSS Variables for Theming

All shop components will use these CSS variables set by the store theme:

```css
:root {
  /* Primary brand colors */
  --color-primary: #7c3aed;
  --color-primary-hover: #6d28d9;
  --color-primary-light: #8b5cf6;

  /* Secondary colors */
  --color-secondary: #f3f4f6;
  --color-secondary-hover: #e5e7eb;

  /* Text colors */
  --color-text-primary: #111827;
  --color-text-secondary: #6b7280;

  /* Status colors */
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-sale: #dc2626;

  /* UI colors */
  --color-border: #e5e7eb;
  --color-background: #ffffff;
  --color-surface: #f9fafb;

  /* Spacing */
  --spacing-unit: 0.25rem;

  /* Border radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-full: 9999px;
}
```

---

## File Structure

```
app/templates/shared/macros/storefront/
├── product-card.html
├── product-grid.html
├── add-to-cart.html
├── mini-cart.html
├── cart-item.html
├── cart-summary.html
├── product-gallery.html
├── variant-selector.html
├── product-info.html
├── product-tabs.html
├── category-nav.html
├── breadcrumbs.html
├── search-bar.html
├── filter-sidebar.html
├── star-rating.html
├── review-card.html
├── trust-badges.html
├── sale-banner.html
├── product-badge.html
└── recently-viewed.html
```

---

## Next Steps

1. **Review & Approve** - Team reviews this proposal
2. **Prioritize** - Confirm component priority order
3. **Design Mockups** - Create visual designs for key components
4. **Implementation** - Build components in priority order
5. **Documentation** - Add to component reference page
6. **Testing** - Test across stores and themes

---

## Related Documentation

- [Component Standards](../shared/component-standards.md)
- [Shop Architecture](architecture.md)
- [Theme System](../../architecture/theme-system/overview.md)
- [UI Components Quick Reference](../shared/ui-components-quick-reference.md)