docs: add architecture rules FE-017 to FE-023 for e-commerce macros

Add frontend architecture rules for Priority 4 and 5 components:

Priority 4 - Navigation & Discovery:
- FE-017: Use category_nav macros for category navigation
- FE-018: Use breadcrumbs macros for breadcrumb navigation
- FE-019: Use search_bar macros for search functionality
- FE-020: Use filter_sidebar macros for product filtering

Priority 5 - Social Proof & Trust:
- FE-021: Use star_rating macros for rating displays
- FE-022: Use review macros for review displays
- FE-023: Use trust_badges macros for trust signals

Each rule documents available macros, features, and usage examples.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.architecture-rules.yaml

@@ -902,6 +902,209 @@ frontend_component_rules:
       encouraged_patterns:
         - "{% from 'shared/macros/shop/product-tabs.html' import"
 
+  - id: "FE-017"
+    name: "Use category_nav macros for category navigation"
+    severity: "info"
+    description: |
+      Use the shared category_nav macros for category navigation sidebars and menus.
+      Import from shared/macros/shop/category-nav.html.
+
+      Available macros:
+      - category_nav() - Sidebar with nested collapsible categories
+      - category_tree() - Flat list (vertical or horizontal)
+      - category_menu() - Horizontal dropdown menu
+      - category_drawer() - Mobile full-screen drawer
+
+      Features:
+      - Product counts per category
+      - Active state tracking
+      - Auto-expand parent of active category
+      - Collapsible nested levels
+
+      Usage:
+        {% from 'shared/macros/shop/category-nav.html' import category_nav, category_tree %}
+        {{ category_nav(categories_var='categories', current_var='currentCategory') }}
+        {{ category_tree(categories_var='categories', layout='horizontal') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/category-nav.html' import"
+
+  - id: "FE-018"
+    name: "Use breadcrumbs macros for breadcrumb navigation"
+    severity: "info"
+    description: |
+      Use the shared breadcrumbs macros for navigation trails.
+      Import from shared/macros/shop/breadcrumbs.html.
+
+      Available macros:
+      - shop_breadcrumbs() - Standard breadcrumb trail (static or dynamic)
+      - auto_breadcrumbs() - Auto-generated from category hierarchy
+      - compact_breadcrumbs() - Mobile-friendly parent + current
+
+      Features:
+      - Home link with icon
+      - Customizable separator icon
+      - Support for icons per item
+      - Responsive design
+
+      Usage:
+        {% from 'shared/macros/shop/breadcrumbs.html' import shop_breadcrumbs %}
+        {{ shop_breadcrumbs(items=[
+            {'label': 'Electronics', 'url': '/electronics'},
+            {'label': 'Headphones'}
+        ]) }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/breadcrumbs.html' import"
+
+  - id: "FE-019"
+    name: "Use search_bar macros for product search"
+    severity: "info"
+    description: |
+      Use the shared search_bar macros for product search functionality.
+      Import from shared/macros/shop/search-bar.html.
+
+      Available macros:
+      - search_bar() - Basic search input with optional button
+      - search_autocomplete() - Search with dropdown suggestions
+      - mobile_search() - Full-screen mobile search overlay
+      - search_trigger() - Button to open mobile search
+      - instant_search_results() - Inline results component
+
+      Features:
+      - Autocomplete suggestions
+      - Recent searches (localStorage)
+      - Popular searches
+      - Size variants (sm, md, lg)
+
+      Usage:
+        {% from 'shared/macros/shop/search-bar.html' import search_bar, search_autocomplete %}
+        {{ search_bar(placeholder='Search products...') }}
+        {{ search_autocomplete(search_endpoint='/api/search') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/search-bar.html' import"
+
+  - id: "FE-020"
+    name: "Use filter_sidebar macros for product filtering"
+    severity: "info"
+    description: |
+      Use the shared filter_sidebar macros for product filtering panels.
+      Import from shared/macros/shop/filter-sidebar.html.
+
+      Available macros:
+      - filter_sidebar() - Complete filter panel with all filter types
+      - price_filter() - Standalone price range filter
+      - rating_filter() - Standalone star rating filter
+      - sort_dropdown() - Product sorting dropdown
+      - mobile_filter_drawer() - Full-screen mobile filter panel
+      - filter_trigger() - Button to open mobile filters
+
+      Features:
+      - Category & brand checkboxes
+      - Price range with dual inputs
+      - Color swatches & size buttons
+      - Star rating filter
+      - Collapsible filter groups
+      - Active filter tags with clear
+
+      Usage:
+        {% from 'shared/macros/shop/filter-sidebar.html' import filter_sidebar, sort_dropdown %}
+        {{ filter_sidebar(filters_var='filters', active_filters_var='activeFilters') }}
+        {{ sort_dropdown(value_var='sortBy', on_change='sortProducts()') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/filter-sidebar.html' import"
+
+  - id: "FE-021"
+    name: "Use star_rating macros for rating displays"
+    severity: "info"
+    description: |
+      Use the shared star_rating macros for all rating displays and inputs.
+      Import from shared/macros/shop/star-rating.html.
+
+      Available macros:
+      - star_rating() - Display star ratings (static or dynamic)
+      - rating_input() - Interactive rating input for reviews
+      - rating_summary() - Rating distribution with bars
+      - compact_rating() - Inline compact rating for lists
+
+      Features:
+      - Half-star and exact precision support
+      - Multiple sizes (xs, sm, md, lg, xl)
+      - Alpine.js dynamic binding
+      - Interactive input with hover effects
+      - Rating distribution visualization
+
+      Usage:
+        {% from 'shared/macros/shop/star-rating.html' import star_rating, rating_input %}
+        {{ star_rating(rating=4.5, show_count=true, count=127) }}
+        {{ rating_input(model='userRating', size='lg', allow_half=true) }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/star-rating.html' import"
+
+  - id: "FE-022"
+    name: "Use review macros for review displays"
+    severity: "info"
+    description: |
+      Use the shared review macros for product reviews.
+      Import from shared/macros/shop/reviews.html.
+
+      Available macros:
+      - review_card() - Single review display with actions
+      - review_list() - Sortable list of reviews
+      - review_form() - Review submission form
+      - review_summary_section() - Complete rating summary
+
+      Features:
+      - Verified purchase badges
+      - Helpful/not helpful voting
+      - Image attachments
+      - Sort by newest/oldest/helpful
+      - Star rating input integration
+
+      Usage:
+        {% from 'shared/macros/shop/reviews.html' import review_card, review_form %}
+        {{ review_card(review_var='review', on_helpful='markHelpful(review.id)') }}
+        {{ review_form(rating_model='rating', on_submit='submitReview()') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/reviews.html' import"
+
+  - id: "FE-023"
+    name: "Use trust_badges macros for trust signals"
+    severity: "info"
+    description: |
+      Use the shared trust_badges macros for security and trust indicators.
+      Import from shared/macros/shop/trust-badges.html.
+
+      Available macros:
+      - trust_badges() - Grid or flex layout of trust badges
+      - trust_banner() - Horizontal trust banner
+      - payment_icons() - Payment method icons
+      - guarantee_badge() - Money-back/satisfaction guarantee
+      - security_seals() - SSL and checkout security seals
+      - checkout_trust_section() - Complete checkout trust block
+
+      Badge types: secure_payment, free_shipping, easy_returns,
+      support_24_7, money_back, ssl_secured, fast_delivery, quality_guarantee
+
+      Usage:
+        {% from 'shared/macros/shop/trust-badges.html' import trust_badges, payment_icons %}
+        {{ trust_badges(badges=['secure_payment', 'free_shipping'], layout='grid') }}
+        {{ payment_icons(methods=['visa', 'mastercard', 'paypal']) }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/trust-badges.html' import"
+
 # ============================================================================
 # FRONTEND STYLING RULES
 # ============================================================================