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>

docs/development/architecture-rules.md

@@ -663,6 +663,124 @@ Show empty state when lists have no items.
 
 ---
 
+### Jinja Macro Rules (app/templates/**/*.html)
+
+#### MAC-001: Use Shared Macros for Repeated Patterns
+**Severity:** Error
+
+Never copy-paste HTML patterns. Use or create shared macros in `app/templates/shared/macros/`.
+
+```jinja
+{# ✅ Good - Using shared macro #}
+{% from 'shared/macros/tables.html' import table_wrapper, table_header %}
+{% call table_wrapper() %}
+    {{ table_header(['Name', 'Email', 'Status']) }}
+    <tbody>...</tbody>
+{% endcall %}
+
+{# ❌ Bad - Copy-pasting table HTML #}
+<div class="w-full overflow-hidden rounded-lg shadow-xs">
+    <div class="w-full overflow-x-auto">
+        <table class="w-full whitespace-no-wrap">
+            <thead>...</thead>
+            <tbody>...</tbody>
+        </table>
+    </div>
+</div>
+```
+
+#### MAC-002: Import Macros at Template Top
+**Severity:** Warning
+
+All macro imports should be at the top of the template, after `{% extends %}`.
+
+```jinja
+{# ✅ Good #}
+{% extends "admin/base.html" %}
+{% from 'shared/macros/pagination.html' import pagination %}
+{% from 'shared/macros/tables.html' import table_wrapper %}
+{% from 'shared/macros/alerts.html' import loading_state %}
+
+{% block content %}
+...
+{% endblock %}
+```
+
+#### MAC-003: Use {% call %} for Wrapper Macros
+**Severity:** Error
+
+Wrapper macros that use `{{ caller() }}` must be invoked with `{% call %}`.
+
+```jinja
+{# ✅ Good #}
+{% call table_wrapper() %}
+    {{ table_header(['Col1', 'Col2']) }}
+{% endcall %}
+
+{% call tabs_nav() %}
+    {{ tab_button('tab1', 'First') }}
+{% endcall %}
+
+{# ❌ Bad - Missing call block #}
+{{ table_wrapper() }}  {# This won't render inner content! #}
+```
+
+#### MAC-004: Document New Macros
+**Severity:** Warning
+
+New macros must have JSDoc-style documentation comments.
+
+```jinja
+{# ✅ Good #}
+{#
+  Number Stepper
+  ==============
+  A number input with +/- buttons.
+
+  Parameters:
+    - model: Alpine.js x-model variable (required)
+    - min: Minimum value (default: 1)
+    - max: Maximum value (optional)
+
+  Usage:
+    {{ number_stepper(model='quantity', min=1, max=99) }}
+#}
+{% macro number_stepper(model, min=1, max=none) %}
+...
+{% endmacro %}
+```
+
+#### MAC-005: Add Components to Reference Page
+**Severity:** Warning
+
+New shared components should be added to `/admin/components` page with live demos.
+
+---
+
+### Frontend Component Rules (app/templates/**/*.html)
+
+#### FE-008: Use number_stepper Macro for Quantity Inputs
+**Severity:** Warning
+
+Use the shared `number_stepper` macro instead of raw `<input type="number">` for consistent styling and dark mode support.
+
+```jinja
+{# ✅ Good - Using number_stepper macro #}
+{% from 'shared/macros/inputs.html' import number_stepper %}
+{{ number_stepper(model='quantity', min=1, max=99) }}
+
+{# ❌ Bad - Raw number input #}
+<input type="number" x-model="quantity" min="1" max="99" />
+```
+
+**Suppress with `noqa` for ID fields:**
+```jinja
+{# noqa: FE-008 - User ID is typed directly, not incremented #}
+<input type="number" x-model="userId" placeholder="User ID" />
+```
+
+---
+
 ### Styling Rules (app/templates/**/*.html)
 
 #### CSS-001: Use Tailwind Utility Classes
@@ -885,13 +1003,15 @@ All rules are defined in `.architecture-rules.yaml`. To modify rules:
 | Backend | 20 | 15 | 5 |
 | Frontend JS | 7 | 6 | 1 |
 | Frontend Templates | 7 | 3 | 4 |
+| Frontend Macros | 5 | 2 | 3 |
+| Frontend Components | 1 | 0 | 1 |
 | Frontend Styling | 4 | 1 | 3 |
 | Naming | 5 | 3 | 2 |
 | Security | 5 | 5 | 0 |
 | Quality | 3 | 2 | 1 |
-| **Total** | **51** | **35** | **16** |
+| **Total** | **57** | **37** | **20** |
 
 ---
 
-**Last Updated:** 2025-12-04
-**Version:** 2.2
+**Last Updated:** 2025-12-07
+**Version:** 2.3