# ADR-0002: Phase 11 Foundation Architecture

- **Status:** Accepted for implementation; browser evidence pending
- **Date:** 2026-06-25
- **Scope:** Design tokens, theme, localization, routing, metadata, application shell, and global states
- **Supersedes:** No Phase 9 or Phase 10 product decision

## Context

Phase 11 must extend the Phase 10 repository without mutating the immutable Phase 9 contract, weakening CSP, inventing unresolved destinations, or creating a second styling, routing, or localization authority.

## Decisions

### Token pipeline

Keep Phase 9 raw and semantic token files unchanged. Add `src/styles/component-tokens.css` as an additive component-facing layer. Application CSS may not consume raw palette tokens or literal colors.

### Theme persistence and bootstrap

Keep `hpc-theme` as the server-readable canonical preference and `hpc.theme.preference` as a client continuity copy. Preference remains distinct from resolved theme. The nonce-bearing head bootstrap resolves before paint. A CSS media-query fallback gives readable system-dark behavior when JavaScript is delayed or unavailable. Same-window theme selectors synchronize through a custom event; cross-tab selectors synchronize through the storage event.

### Locale routing and negotiation

The route path remains the active locale authority. Root negotiation uses the locale cookie, then `Accept-Language`, then English. Locale switching resolves the current semantic route ID, preserves only allowlisted campaign parameters, and preserves only hashes approved for that route.

### Translation loading

Server components load typed catalogs through `getMessages`. Interaction-only global states use a small client shell-catalog map. Missing-key and type parity remain CI failures. No runtime fallback silently substitutes English for French or Arabic.

### Formatting

Centralized `Intl` formatters require an explicit locale and, where relevant, time zone or currency. Language never implies market, country, currency, or jurisdiction. Gregorian dates and Latin digits remain the inherited baseline until product research approves alternatives.

### Font loading

Use the pinned local Fontsource variable packages for Inter and Noto Sans Arabic. Arabic receives its own line-height and does not inherit forced Latin metrics.

### Application shell composition

The locale layout owns document attributes, theme bootstrap, skip navigation, header, footer, and theme controller. The header is server-rendered except for route-aware navigation, selectors, and the native modal mobile drawer. The drawer uses `<dialog>` for modal semantics, Escape behavior, background interaction blocking, and focus containment, with explicit focus return.

### Unresolved destinations

Authoritative route-manifest paths are generated for login and legal routes, but those pages render localized noindex pending shells. Demo, contact, and login actions do not receive invented production integrations. They remain visibly disabled or lead to an explicit pending route.

### Metadata

A single server helper generates canonical URLs, reciprocal `hreflang`, Open Graph locale data, social summary metadata, and release-safe robots behavior from route IDs. No structured organization, review, rating, pricing, or contact data is emitted.

### CSS organization

- `tokens.css`: immutable Phase 9 tokens
- `component-tokens.css`: Phase 11 component-facing roles
- `globals.css`: reset, typography, focus, selection, accessibility utilities
- CSS Modules: component and page layout

### Visual regression

Playwright Chromium is the canonical snapshot engine. Functional projects remain Chromium, Firefox, WebKit, mobile Chromium, and mobile WebKit. Snapshot generation and approval are blocked until the pinned browser environment can execute.

## Consequences

The application foundation is traceable and does not encode unresolved product decisions. The cost is an explicit set of pending route shells and disabled conversion destinations until owners close the inherited gates. Full acceptance still requires Node 24.17.0 CI, Playwright execution, and reviewed visual snapshots.
