# Phase 9: Developer Handoff

## 1. Scope

This handoff converts the approved homePageCar design system and Phase 8 prototype into implementation contracts for a multilingual rental-car SaaS marketing website. It covers the homepage, demo-booking flow, guided product tour, responsive navigation, theme selection, locale routing, SEO language relationships, analytics boundaries, accessibility, assets, validation, and release gates.

It does **not** approve unverified capabilities, customer evidence, integrations, certifications, service levels, prices, legal language, CRM behavior, or usability acceptance.

## 2. Implementation authority

Use this precedence when files disagree:

1. `DECISION_LOG_v9.0.md`
2. `09_DEVELOPER_HANDOFF_v1.0.md`
3. component, localization, interaction, token, and QA contracts in this package
4. Phase 8 prototype as behavioral reference only

The prototype is not production source code. Its inline rendering, simulated submission, local research logging, illustrative product UI, and placeholder contact destination must not be copied blindly.

## 3. Required architecture properties

The implementation must:

- render public pages server-side or statically with correct `lang`, `dir`, canonical, and reciprocal `hreflang` before hydration;
- use strict TypeScript for application code;
- consume semantic CSS custom properties, never component-local brand hex values;
- use one component tree for LTR and RTL;
- use locale-prefixed routes and stable route IDs;
- persist explicit theme preference in a first-party cookie and mirror it in local storage;
- run the pre-paint theme bootstrap before blocking styles;
- keep all public strings outside component source except documented proper names and immutable technical identifiers;
- use native semantic controls unless a documented accessibility review approves a replacement;
- provide deterministic state URLs or test fixtures for every visual-regression state;
- gate production analytics behind approved consent rules and exclude form values and free text.

## 4. Breakpoints and layout modes

Breakpoints are layout decisions, not device labels.

| Mode    |         CSS range | Reference frames | Required behavior                                                                                       |
| ------- | ----------------: | ---------------- | ------------------------------------------------------------------------------------------------------- |
| Compact |          0–767 px | 320, 390         | One-column sections; mobile drawer; stacked CTAs; product preview simplified; no horizontal page scroll |
| Medium  |       768–1119 px | 768, 1024        | Two-column where specified; mobile drawer remains; 4-column workflow allowed; balanced content widths   |
| Wide    | 1120 px and above | 1280, 1440       | Desktop navigation and controls; 12-column composition; hero 7/5 split; max container 1280 px           |

Do not infer new behavior between breakpoints. Follow `components/RESPONSIVE_BEHAVIOR_MATRIX_v1.0.csv`.

## 5. Theme contract

Supported preferences are exactly `light`, `dark`, and `system`. Preference and resolved theme are separate values.

- Cookie: `hpc-theme`, value `light|dark|system`, `Path=/`, `SameSite=Lax`, one-year max age, `Secure` in production.
- Local storage mirror: `hpc.theme.preference`.
- Root attributes: `data-theme-preference` and resolved `data-theme` (`light|dark`).
- Cookie wins if cookie and local storage disagree.
- Default with no stored preference: `system`.
- System updates live on `prefers-color-scheme` changes.
- Theme application has no global transition.
- Set `color-scheme` to the resolved theme.
- The bootstrap must run in `<head>` before blocking CSS and use a CSP nonce or approved hash.

See `interaction/theme-bootstrap_v1.0.js` and `implementation/theme-config_v1.0.ts`.

## 6. Localization and routing contract

Public routes are locale-prefixed: `/en`, `/fr`, `/ar`. English is source/default/fallback, but missing translations fail CI.

- Root `/` may redirect using explicit cookie, then `Accept-Language`, then English.
- Explicit locale URLs are never overridden automatically.
- Arabic renders `<html lang="ar" dir="rtl">`; English and French render `dir="ltr"`.
- Locale switching maps by stable route ID, preserves query parameters approved in the route manifest, and preserves valid section hashes.
- Atomic LTR values inside Arabic use `<bdi dir="ltr">` or an equivalent isolation primitive.
- Language does not determine currency, country, timezone, tax, or phone formatting.
- Reciprocal `hreflang` entries include `en`, `fr`, `ar`, plus `x-default` pointing to `/en`.

See the localization directory for exact rules and generated resources.

## 7. Component implementation

Every public component must implement:

- semantic anatomy and heading rules;
- props and state enums from `implementation/component-contracts_v1.0.ts`;
- explicit compact/medium/wide behavior;
- light/dark behavior via tokens;
- LTR/RTL behavior via logical CSS and selective icon mirroring;
- keyboard and focus behavior;
- visible-copy keys and content bounds;
- stable test IDs only where semantic selectors are insufficient.

No component may introduce a fixed height for translated text, validation messages, cards, buttons, or headings.

## 8. Demo form production contract

Required fields: full name, work email, company, fleet-size range. Optional fields: market/country, preferred language, message.

Submission state machine:

`idle → validating → submitting → success | recoverable_error | terminal_error`

Rules:

- preserve entered data on recoverable service failure;
- focus the first invalid field after summary announcement;
- show inline errors and a form-level summary;
- do not use a toast as the only error record;
- disable duplicate submission while a request is in flight;
- attach an idempotency key to each intentional submission;
- do not log names, emails, company names, messages, or raw server responses;
- render final consent only after Legal approval;
- provide an alternate contact path only after Sales approves a real destination;
- success copy must accurately describe what the backend actually did.

The CRM endpoint, consent language, routing, retries, spam controls, and duplicate policy are release blockers in the issue register.

## 9. Motion and overlays

- Drawer opens from inline-start: left in LTR, right in RTL.
- Drawer and dialogs trap focus, make background inert, support Escape, and return focus to the trigger.
- Backdrop dismissal is allowed for non-destructive dialogs; pending form submission blocks accidental dismissal.
- Animations are 160–220 ms and use opacity/transform only.
- `prefers-reduced-motion: reduce` removes smooth scrolling, transforms, shimmer, and non-essential progress animation.
- No information, success, or error state may depend on animation.

## 10. Assets and evidence

Only assets in `assets/ASSET_MANIFEST_v1.0.csv` with status `approved` may ship. The current product preview is `illustrative` and must either receive written approval or be replaced by an evidence-governed product capture before launch.

Product captures require metadata for locale, direction, theme, capture date, product version, approval owner, and expiry/review date. Never mirror, recolor, or invert captures.

## 11. Quality gates

A production candidate must pass:

- locale key parity and linguistic review;
- all listed browser and viewport scenarios;
- keyboard, screen-reader, zoom, reflow, forced-colors, and reduced-motion checks;
- light/dark/system and LTR/RTL visual regression;
- form validation, network failure, duplicate, retry, consent, and CRM integration tests;
- performance budgets in `qa/PERFORMANCE_BUDGETS_v1.0.json`;
- zero open Critical or High issues;
- approved evidence and legal content only;
- the complete definition of done.

## 12. Explicitly unresolved

The final framework, browser policy owner, analytics vendor, CRM, consent implementation, spam protection, product-tour media, market assumptions, multi-location claim, pricing, integrations, security evidence, legal documents, and participant acceptance are not approved. The package supplies a vendor-neutral implementation and a default technical profile, but each unresolved item remains visible and owned in `OPEN_ISSUE_REGISTER_v1.0.csv`.
