Rental-operations-platform/docs/architecture/ADR-0003_PHASE_12_COMPONENT_SYSTEM.md

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.