init project

docs/architecture/ADR-0003_PHASE_12_COMPONENT_SYSTEM.md

@@ -0,0 +1,26 @@
+# ADR-0003: Phase 12 component-system architecture
+
+- Status: Accepted for implementation; release acceptance remains gated
+- Date: 2026-06-25
+- Owners: Frontend architecture, design systems, accessibility
+
+## Context
+
+Phase 12 requires a reusable marketing component system without assembling the homepage or inventing unresolved product content. Phase 11 approved semantic CSS modules, native platform behavior, server components by default, and a production shell rather than Storybook.
+
+## Decision
+
+1. Keep CSS Modules as the only component styling method and consume only component-facing semantic tokens.
+2. Use native HTML primitives where they provide reliable behavior: `button`, `a`, `details`, `progress`, form controls, and `dialog`.
+3. Add client boundaries only to controls with state, browser APIs, keyboard roving focus, or overlays.
+4. Use a guarded component-lab route as the approved Storybook-equivalent fixture surface. It returns not found unless `COMPONENT_FIXTURES_ENABLED=true`.
+5. Implement the icon set as a small, tree-shakeable internal SVG map to avoid adding a second dependency or shipping an entire icon library.
+6. Keep unresolved claims, destinations, customer evidence, pricing, CRM submission, and approved media represented as blocked inventory entries or disabled typed states.
+7. Add Phase 12 inventory and manifest validators. The package dependency graph remains unchanged.
+
+## Consequences
+
+- Phase 13 receives stable import paths and explicit section patterns.
+- Browser, accessibility, and visual fixtures are deterministic and cannot be exposed accidentally under the default production environment.
+- The internal icon map requires deliberate review when adding icons, which is preferable to casual dependency archaeology.
+- Runtime acceptance still depends on executing the pinned Node 24.17.0 and pnpm 11.9.0 suites in an environment with registry and browser access.