# Phase 13 Handoff: Homepage Assembly

## Handoff status

The Phase 12 component source is implemented and usable for Phase 13 development. Static validation, formatting, lint, strict type checking, unit tests, coverage, production build, and standalone HTTP locale checks pass in the available environment. Formal Phase 12 acceptance remains gated by P12-001 through P12-005.

## Authoritative inputs

Read first:

1. `docs/PHASE_12_IMPLEMENTATION_REPORT_v1.0.md`
2. `docs/phase12/COMPONENT_INVENTORY_v1.0.json`
3. `docs/phase12/COMPONENT_CATALOG_v1.0.md`
4. `docs/phase12/COMPONENT_SPECIFICATION_TRACEABILITY_v1.0.csv`
5. `docs/phase12/ACCESSIBILITY_BEHAVIOR_MATRIX_v1.0.csv`
6. `docs/phase12/RTL_BEHAVIOR_MATRIX_UPDATE_v1.0.csv`
7. `docs/phase12/RESPONSIVE_VALIDATION_MATRIX_v1.0.csv`
8. `docs/DECISION_LOG_v12.0.md`
9. `docs/IMPLEMENTATION_ISSUE_REGISTER_v1.2.csv`
10. `PHASE_12_PACKAGE_MANIFEST_v1.0.json`

Earlier Phase 7 homepage composition, Phase 8 findings, Phase 9 contracts, and Phase 11 token/localization/shell foundations remain authoritative where Phase 12 does not supersede implementation detail.

## Approved component inventory and import paths

The exact import path, variants, accessibility behavior, RTL behavior, theme behavior, responsive behavior, prohibited usage, tests, limitations, and expected homepage consumers for every public component are documented in `docs/phase12/COMPONENT_CATALOG_v1.0.md` and the machine-readable inventory.

Primary families:

```text
@/components/actions/*
@/components/controls/*
@/components/feedback/*
@/components/forms/*
@/components/foundation/*
@/components/marketing/*
@/components/media/*
@/components/navigation/*
@/components/overlays/*
@/components/surfaces/*
@/components/typography/*
```

Do not duplicate a component because a page section wants a slightly different margin. Compose it or propose an explicit semantic variant.

## Variant restrictions

- Use semantic intents such as `conversion`, `secondary`, `available`, or `warning`.
- Do not expose arbitrary raw colors, shadows, radii, spacing, or classes as product APIs.
- Use `Button` for actions and `ActionLink` for navigation.
- Icon-only controls require accessible labels.
- Interactive cards may not contain independent nested interactive controls.
- Heading appearance is independent of semantic heading level.
- Evidence marked `research-only` or `prohibited` must never render as production proof.

## Composition guidance

Use explicit section patterns rather than one universal section with a landfill of Boolean props. Keep route composition responsible for copy, ordering, and content models. Components remain content-independent. The guarded component lab at `/{locale}/component-lab` shows representative composition when `COMPONENT_FIXTURES_ENABLED=true`.

## Section-pattern inventory

Approved patterns include `SectionHeader`, split content, media-and-copy, feature grid, workflow section, comparison section, metric/evidence strip, testimonial shell, FAQ shell, CTA section, and alternating feature section. Sticky media and bento layouts require Phase 7 approval before use.

## Homepage section-to-component mapping

| Homepage section            | Primary components                                                       |
| --------------------------- | ------------------------------------------------------------------------ |
| Header verification         | Existing `SiteHeader`, navigation items, locale/theme controls           |
| Hero                        | `SectionHeader`, `CTAGroup`, `MediaFrame`, `ProductPreview`              |
| Trust proof shell           | `EvidenceShell`, `Metric`, logo/quote shells with governed status        |
| Fragmented versus connected | `Comparison`, `ComparisonCard`, `Callout`                                |
| Rental workflow             | `Workflow`, `WorkflowStep`, `SectionHeader`                              |
| Feature/capability sections | `FeatureGrid`, `FeatureCard`, media-and-copy pattern                     |
| Product UI previews         | `ProductPreview`, responsive table/media shells, `BidiText`              |
| Operational benefits        | `Metric`, `Callout`, `FeatureCard` without unsupported quantified claims |
| Evidence/testimonial shells | `EvidenceShell`, quote shell, source note; approved content only         |
| FAQ                         | FAQ/accordion section shell                                              |
| Final CTA                   | CTA section, primary conversion action, disabled unresolved alternatives |
| Footer verification         | Existing `SiteFooter`, footer link groups                                |

## Translation and content locations

- Runtime locale catalogs: `src/content/locales/{en,fr,ar}`.
- Guarded development fixtures: `src/content/development/component-lab.ts`.
- Homepage copy must be added as complete semantic messages, never concatenated fragments.
- Use existing format utilities for dates, numbers, currency, identifiers, and bidi isolation.
- Native French and Arabic review remains required under P9-005/P11-004.

## Typed homepage content models

Phase 13 should define route-level content objects that reference component semantics rather than presentation accidents. Evidence must use the Phase 12 `EvidenceStatus` model. Actions must distinguish navigational links from button actions and unresolved destinations.

## Route-generation utilities

Use the existing localization route manifest and route helpers. Do not hard-code locale prefixes or use `href="#"`. Preserve only approved campaign parameters during locale changes. Unknown login, demo, sales, tour, and contact destinations remain disabled or issue-linked.

## Theme rules

Consume semantic tokens only. All sections must pass light, dark, and system. Do not add page-local raw brand colors or global transitions. Conversion orange remains restricted to the dominant approved action.

## RTL rules

- Arabic uses true document-level RTL.
- Use logical properties.
- Mirror only semantically directional icons.
- Do not mirror brand marks, vehicle/product media, or universal media controls.
- Preserve process chronology and conceptual comparison meaning.
- Isolate plates, VINs, reservation IDs, phone numbers, email addresses, URLs, and currency values.

## Responsive rules

Validate 1440, 1024, 768, 390, and 320 CSS-pixel widths, reduced viewport height, landscape mobile where relevant, 200-percent zoom, required 400-percent reflow, long French/Arabic text, and RTL at each principal width. No horizontal page overflow is permitted. Component-level overflow must be explicit and accessible.

## Accessibility rules

Preserve heading hierarchy, landmarks, focus order, visible focus, touch targets, error descriptions, live-region restraint, reduced motion, forced-colors fallbacks, and logical reading order. Complete the P12 browser/axe/manual gates before acceptance. Automated tests do not replace keyboard and screen-reader review, a fact software teams rediscover with impressive regularity.

## Image and media rules

Use approved responsive image behavior with explicit intrinsic dimensions and alt semantics. Do not mirror media automatically. Final product screenshots, customer photography, logos, video, and poster assets remain blocked until approved. Development placeholders must remain unmistakably non-production.

## Evidence-status handling

Only approved evidence may render as production proof. Pending review may appear only in governed preview contexts. Research-only and prohibited evidence are suppressed from production rendering. Never invent metrics, quotes, customer names, logos, or quantified improvements to make a section feel complete.

## CTA destination handling

Use localized route and destination contracts. A missing destination renders disabled or development-marked behavior, not an empty link or guessed URL. Demo submission, CRM, analytics, consent, login, sales, and product-tour integrations remain outside Phase 13 unless separately approved.

## Known blockers

P12-001 through P12-005 plus inherited P9/P10/P11 content, evidence, legal, integration, branding, market, and destination issues. See `docs/IMPLEMENTATION_ISSUE_REGISTER_v1.2.csv`.

## Files Phase 13 may modify

- Add homepage composition under `src/app/[locale]`.
- Add localized homepage catalogs under `src/content/locales/{en,fr,ar}`.
- Add typed homepage content models under `src/content` or the approved route-content location.
- Add narrowly scoped component variants only when the existing API cannot express an approved design.
- Add homepage browser/a11y/visual tests and deterministic fixtures.
- Update Phase 13 reports, issue records, decision records, and package manifest.

## Files Phase 13 must not modify without an architecture decision

- `contracts/phase9/**`.
- Phase 11 semantic token foundations.
- Locale and route core utilities.
- Theme persistence/bootstrap behavior.
- CSP/security foundations.
- Existing component semantics or public APIs in breaking ways.
- Evidence suppression and unresolved-destination controls.
- Package manager, runtime pins, styling method, icon foundation, or testing stack.

## Required validation commands

```bash
pnpm install --frozen-lockfile
pnpm validate
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:browser
pnpm test:a11y
pnpm test:visual
SITE_ORIGIN=https://approved.example pnpm build
pnpm audit
pnpm manifest:generate
pnpm validate:package
```

## Screenshot and visual-regression matrix

At minimum capture the full homepage for:

- EN light/dark desktop and mobile.
- FR light/dark desktop and mobile with long content.
- AR light/dark desktop and mobile with true RTL and mixed identifiers.
- Focus-visible navigation and primary CTA.
- Mobile drawer open.
- Evidence pending/suppressed development state.
- Error and unavailable destination states.
- 320 CSS-pixel and approved tablet widths.

Stabilize dates, identifiers, animations, fonts, and fixtures before baseline generation.

## Recommended homepage implementation order

1. Header integration verification.
2. Hero.
3. Trust-proof shell.
4. Fragmented-versus-connected comparison.
5. End-to-end rental workflow.
6. Feature or capability sections.
7. Product UI previews.
8. Operational benefits.
9. Evidence or testimonial shells.
10. FAQ.
11. Final CTA.
12. Footer integration verification.

## Phase 13 definition of done

- The approved homepage sequence is assembled from Phase 12 components without duplicate component families.
- EN, FR, and AR content is externalized and reviewed.
- Arabic document RTL and mixed-direction identifiers are correct.
- Light, dark, and system themes pass.
- All approved responsive widths, zoom/reflow, reduced motion, and forced-colors checks pass.
- Browser, axe, visual, keyboard, touch, and screen-reader evidence is recorded.
- Unsupported claims, evidence, logos, testimonials, pricing, URLs, CRM, analytics, consent, and media remain blocked or suppressed.
- The production build and package manifest pass on Node 24.17.0 and pnpm 11.9.0.
- Open Critical/High issues are visible and release gates are not waived by silence.