From 65e06c90efc576bb7a35d9463bc62407acd19977 Mon Sep 17 00:00:00 2001 From: Samir Boulahtit Date: Sun, 7 Dec 2025 17:14:52 +0100 Subject: [PATCH] docs: add architecture rules for Priority 3 e-commerce components MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add rules FE-013 through FE-016: - FE-013: Use product_gallery macro for image galleries - FE-014: Use variant_selector macros for product options - FE-015: Use product_info macros for product details - FE-016: Use product_tabs macro for product content tabs Update ui-components-quick-reference.md with: - Product Gallery usage and features - Variant Selector macros - Product Info macros - Product Tabs configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .architecture-rules.yaml | 100 ++++++++++++++++++ .../shared/ui-components-quick-reference.md | 73 +++++++++++++ 2 files changed, 173 insertions(+) diff --git a/.architecture-rules.yaml b/.architecture-rules.yaml index 32d425f2..0e9b259d 100644 --- a/.architecture-rules.yaml +++ b/.architecture-rules.yaml @@ -802,6 +802,106 @@ frontend_component_rules: encouraged_patterns: - "{% from 'shared/macros/shop/mini-cart.html' import" + - id: "FE-013" + name: "Use product_gallery macro for image galleries" + severity: "info" + description: | + Use the shared product_gallery macros for product image displays. + Import from shared/macros/shop/product-gallery.html. + + Available macros: + - product_gallery() - Full gallery with thumbnails, zoom, lightbox + - gallery_thumbnails() - Standalone thumbnail strip + - simple_image_viewer() - Single image with optional lightbox + + Features: + - Thumbnail navigation + - Hover zoom on main image + - Fullscreen lightbox with keyboard navigation + - Responsive design + + Usage: + {% from 'shared/macros/shop/product-gallery.html' import product_gallery %} + {{ product_gallery(images_var='product.images', enable_zoom=true) }} + pattern: + file_pattern: "app/templates/shop/**/*.html" + encouraged_patterns: + - "{% from 'shared/macros/shop/product-gallery.html' import" + + - id: "FE-014" + name: "Use variant_selector macros for product options" + severity: "info" + description: | + Use the shared variant_selector macros for product variant selection. + Import from shared/macros/shop/variant-selector.html. + + Available macros: + - variant_selector() - Generic selector (buttons/dropdown/swatches) + - size_selector() - Specialized for sizes with size guide link + - color_swatches() - Color selection with hex preview + - multi_variant_selector() - Multiple option types (size + color) + + Features: + - Out of stock indicators + - Low stock warnings + - Selected state highlighting + + Usage: + {% from 'shared/macros/shop/variant-selector.html' import size_selector, color_swatches %} + {{ size_selector(sizes_var='product.sizes') }} + {{ color_swatches(colors_var='product.colors') }} + pattern: + file_pattern: "app/templates/shop/**/*.html" + encouraged_patterns: + - "{% from 'shared/macros/shop/variant-selector.html' import" + + - id: "FE-015" + name: "Use product_info macros for product details" + severity: "info" + description: | + Use the shared product_info macros for product detail sections. + Import from shared/macros/shop/product-info.html. + + Available macros: + - product_info() - Complete info block (title, price, rating, stock) + - product_price() - Price display with sale support + - product_rating() - Star rating with review count + - stock_status() - Stock availability indicator + - product_badges() - Sale/New/Bestseller badges + - trust_indicators() - Shipping/returns/secure badges + + Usage: + {% from 'shared/macros/shop/product-info.html' import product_info %} + {{ product_info(product_var='product', show_vendor=true) }} + pattern: + file_pattern: "app/templates/shop/**/*.html" + encouraged_patterns: + - "{% from 'shared/macros/shop/product-info.html' import" + + - id: "FE-016" + name: "Use product_tabs macro for product content tabs" + severity: "info" + description: | + Use the shared product_tabs macros for tabbed product information. + Import from shared/macros/shop/product-tabs.html. + + Available macros: + - product_tabs() - Complete tabbed container + - tab_description() - Description content panel + - tab_specifications() - Specs table panel + - tab_reviews() - Reviews list with summary + - tab_shipping() - Shipping & returns panel + - tab_warranty() - Warranty info panel + - review_card() - Individual review display + + Usage: + {% from 'shared/macros/shop/product-tabs.html' import product_tabs %} + {{ product_tabs(tabs=['description', 'specifications', 'reviews', 'shipping']) }} + pattern: + file_pattern: "app/templates/shop/**/*.html" + encouraged_patterns: + - "{% from 'shared/macros/shop/product-tabs.html' import" + # ============================================================================ # FRONTEND STYLING RULES # ============================================================================ diff --git a/docs/frontend/shared/ui-components-quick-reference.md b/docs/frontend/shared/ui-components-quick-reference.md index 9c13491f..d2e30d38 100644 --- a/docs/frontend/shared/ui-components-quick-reference.md +++ b/docs/frontend/shared/ui-components-quick-reference.md @@ -417,6 +417,73 @@ Reusable macros for shop/storefront functionality. Located in `app/templates/sha - `cart_item()` - Individual item display - `cart_summary()` - Subtotal, shipping, total +### 🖼️ Product Gallery (Priority 3) +```html +{% from 'shared/macros/shop/product-gallery.html' import product_gallery %} + +{# Full gallery with thumbnails, zoom, and lightbox #} +{{ product_gallery(images_var='product.images', enable_zoom=true, enable_lightbox=true) }} + +{# Simple single image viewer #} +{{ simple_image_viewer(image_var='product.image_url') }} +``` + +**Features:** +- Thumbnail navigation +- Hover zoom on main image +- Fullscreen lightbox with keyboard navigation +- Responsive design + +### 🎨 Variant Selector (Priority 3) +```html +{% from 'shared/macros/shop/variant-selector.html' import size_selector, color_swatches %} + +{# Size buttons with size guide link #} +{{ size_selector(sizes_var='product.sizes', show_guide=true) }} + +{# Color swatches with out-of-stock indicators #} +{{ color_swatches(colors_var='product.colors', selected_var='selectedColor') }} +``` + +**Macros available:** +- `variant_selector()` - Generic (buttons/dropdown/swatches) +- `size_selector()` - Specialized for sizes +- `color_swatches()` - Color selection with hex preview +- `multi_variant_selector()` - Multiple option types + +### 📄 Product Info (Priority 3) +```html +{% from 'shared/macros/shop/product-info.html' import product_info, product_price %} + +{# Complete info block #} +{{ product_info(product_var='product', show_vendor=true, show_rating=true) }} + +{# Individual components #} +{{ product_price(product_var='product', size='lg') }} +{{ product_rating(product_var='product', clickable=true) }} +{{ stock_status(product_var='product') }} +``` + +**Macros available:** +- `product_info()` - Complete info section +- `product_price()` - Price with sale support +- `product_rating()` - Star rating display +- `stock_status()` - Stock indicator +- `trust_indicators()` - Shipping/returns badges + +### 📑 Product Tabs (Priority 3) +```html +{% from 'shared/macros/shop/product-tabs.html' import product_tabs %} + +{# Tabbed product information #} +{{ product_tabs( + product_var='product', + tabs=['description', 'specifications', 'reviews', 'shipping'] +) }} +``` + +**Tab options:** `description`, `specifications`, `reviews`, `shipping`, `warranty` + ### E-commerce Alpine.js State ```javascript // Required state variables for e-commerce components @@ -439,6 +506,12 @@ Reusable macros for shop/storefront functionality. Located in `app/templates/sha addingToCart: false, addedToCart: false, + // Product detail (Priority 3) + selectedImage: 0, + selectedSize: null, + selectedColor: null, + activeProductTab: 'description', + // Wishlist toggleWishlist(product) { product.in_wishlist = !product.in_wishlist;