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>

.architecture-rules.yaml

@@ -686,6 +686,122 @@ frontend_component_rules:
       encouraged_patterns:
         - "{% from 'shared/macros/forms.html' import"
 
+  - id: "FE-008"
+    name: "Use number_stepper macro for quantity inputs"
+    severity: "warning"
+    description: |
+      Use the shared number_stepper macro instead of raw <input type="number">.
+      This ensures consistent styling, proper dark mode support, and hides
+      native browser spinners that render inconsistently.
+
+      WRONG (raw number input):
+        <input type="number" x-model="quantity" min="1" max="99" />
+
+      RIGHT (use macro):
+        {% from 'shared/macros/inputs.html' import number_stepper %}
+        {{ number_stepper(model='quantity', min=1, max=99) }}
+
+      Exceptions (use noqa):
+        - ID fields where users type specific values (add {# noqa: FE-008 #})
+        - Fields that are better as regular text inputs
+
+      Suppress with:
+        - {# noqa: FE-008 #} on the line or at file level
+    pattern:
+      file_pattern: "app/templates/**/*.html"
+      anti_patterns:
+        - 'type="number"'
+        - "type='number'"
+      exceptions:
+        - "shared/macros/inputs.html"  # The macro file itself
+        - "components.html"  # Showcase page
+
+  - id: "FE-009"
+    name: "Use product_card macro for product displays"
+    severity: "info"
+    description: |
+      Use the shared product_card macro for consistent product presentation.
+      Import from shared/macros/shop/product-card.html.
+
+      Features:
+      - Size variants (sm, md, lg)
+      - Sale badge, new badge, out-of-stock badge
+      - Star ratings with review count
+      - Wishlist toggle button
+      - Quick add to cart button
+
+      Usage:
+        {% from 'shared/macros/shop/product-card.html' import product_card %}
+        {{ product_card(product_var='item', size='md') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/product-card.html' import"
+
+  - id: "FE-010"
+    name: "Use product_grid macro for product listings"
+    severity: "info"
+    description: |
+      Use the shared product_grid macro for responsive product grids.
+      Import from shared/macros/shop/product-grid.html.
+
+      Features:
+      - Responsive column count (auto or fixed)
+      - Loading state with skeleton placeholders
+      - Empty state with customizable icon/message
+      - Integrated product_card component
+
+      Usage:
+        {% from 'shared/macros/shop/product-grid.html' import product_grid %}
+        {{ product_grid(products_var='products', loading_var='loading') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/product-grid.html' import"
+
+  - id: "FE-011"
+    name: "Use add_to_cart macros for cart interactions"
+    severity: "info"
+    description: |
+      Use the shared add-to-cart macros for consistent cart functionality.
+      Import from shared/macros/shop/add-to-cart.html.
+
+      Available macros:
+      - add_to_cart_button() - Simple add to cart button
+      - add_to_cart_form() - Complete form with quantity selector
+      - buy_now_button() - Direct checkout button
+      - shop_quantity_selector() - Stock-aware quantity selector
+
+      Usage:
+        {% from 'shared/macros/shop/add-to-cart.html' import add_to_cart_form %}
+        {{ add_to_cart_form(product_var='product') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/add-to-cart.html' import"
+
+  - id: "FE-012"
+    name: "Use mini_cart macro for cart dropdown"
+    severity: "info"
+    description: |
+      Use the shared mini_cart macros for header cart functionality.
+      Import from shared/macros/shop/mini-cart.html.
+
+      Available macros:
+      - mini_cart_icon() - Cart icon with item count badge
+      - mini_cart_dropdown() - Expandable cart preview
+      - mini_cart() - Combined icon + dropdown
+      - cart_item() - Individual cart item display
+      - cart_summary() - Subtotal, shipping, total
+
+      Usage:
+        {% from 'shared/macros/shop/mini-cart.html' import mini_cart %}
+        {{ mini_cart(cart_var='cart', show_var='showCart') }}
+    pattern:
+      file_pattern: "app/templates/shop/**/*.html"
+      encouraged_patterns:
+        - "{% from 'shared/macros/shop/mini-cart.html' import"
+
 # ============================================================================
 # FRONTEND STYLING RULES
 # ============================================================================