docs: add architecture rules for Priority 3 e-commerce components

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 <noreply@anthropic.com>

.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
 # ============================================================================

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;