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.

{{ 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.

{{ 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.

{{ 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:

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.).

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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.

{{ 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:

: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
• Shop Architecture
• Theme System
• UI Components Quick Reference