docs: add architecture rules and docs for e-commerce components
Architecture rules added: - FE-008: Use number_stepper macro for quantity inputs - FE-009: Use product_card macro for product displays - FE-010: Use product_grid macro for product listings - FE-011: Use add_to_cart macros for cart interactions - FE-012: Use mini_cart macro for cart dropdown Documentation: - Update ui-components-quick-reference.md with e-commerce section - Add component-standards.md for standardization guidelines - Add ecommerce-components-proposal.md with full 20-component roadmap - Update validate_architecture.py with FE-008 detection 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
622
docs/frontend/shop/ecommerce-components-proposal.md
Normal file
622
docs/frontend/shop/ecommerce-components-proposal.md
Normal file
@@ -0,0 +1,622 @@
|
||||
# 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 vendor shops while supporting vendor-specific theming via CSS variables.
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Vendor 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/shop/product-card.html`
|
||||
|
||||
A versatile product card for grids, carousels, and lists.
|
||||
|
||||
```jinja
|
||||
{{ product_card(
|
||||
product=product,
|
||||
show_vendor=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/shop/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/shop/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
|
||||
{{ shop_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/shop/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/shop/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/shop/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/shop/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/shop/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/shop/product-info.html`
|
||||
|
||||
Product details section.
|
||||
|
||||
```jinja
|
||||
{{ product_info(
|
||||
product='product',
|
||||
show_sku=true,
|
||||
show_stock=true,
|
||||
show_vendor=false
|
||||
) }}
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- Product title (H1)
|
||||
- Price display (sale price handling)
|
||||
- Rating stars + review count
|
||||
- Short description
|
||||
- SKU display
|
||||
- Stock status
|
||||
- Vendor name (marketplace)
|
||||
|
||||
---
|
||||
|
||||
#### 3.4 Product Tabs
|
||||
**File:** `app/templates/shared/macros/shop/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/shop/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/shop/breadcrumbs.html`
|
||||
|
||||
Navigation breadcrumb trail.
|
||||
|
||||
```jinja
|
||||
{{ shop_breadcrumbs(
|
||||
items=[
|
||||
{'label': 'Home', 'url': '/'},
|
||||
{'label': 'Electronics', 'url': '/category/electronics'},
|
||||
{'label': 'Headphones', 'url': none}
|
||||
]
|
||||
) }}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 4.3 Search Bar
|
||||
**File:** `app/templates/shared/macros/shop/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/shop/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/shop/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/shop/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/shop/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/shop/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/shop/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/shop/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 vendor 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/shop/
|
||||
├── 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 vendors 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)
|
||||
Reference in New Issue
Block a user