# Research: Website Homepage Hero

## Decision 1: Keep the hero implementation local to the static Astro website

- **Decision**: Continue treating the homepage hero as a static `apps/website` concern composed from the current Astro content module and section component, with no runtime dependency on `apps/platform`.
- **Rationale**: Spec 218 is explicitly website-only. The current website already runs as a standalone Astro app, and the hero changes concern semantics, copy discipline, asset truthfulness, and responsive ordering rather than dynamic runtime behavior.
- **Alternatives considered**:
  - Couple hero content to `apps/platform` or a shared API: rejected because the spec forbids platform obligations and the hero needs no dynamic platform data.
  - Introduce a CMS or hero-builder layer first: rejected because one homepage hero does not justify that operational overhead.

## Decision 2: Reuse the existing `homeHero` content object and `PageHero.astro`

- **Decision**: Preserve `apps/website/src/content/pages/home.ts` as the canonical source for hero content and refine `apps/website/src/components/sections/PageHero.astro` as the render surface instead of creating a new hero abstraction.
- **Rationale**: The current site already uses typed content exports and a shared `PageHero` component. This is the narrowest correct place to express hero-specific semantics without adding a second content shape, a render registry, or a page-builder concept.
- **Alternatives considered**:
  - Build a homepage-hero-specific component tree parallel to `PageHero.astro`: rejected because the existing component already supports eyebrow, CTA pair, product visual, and trust subclaims.
  - Hardcode all hero content directly in `index.astro`: rejected because it would bypass the current typed content pattern and make later hero iteration less disciplined.

## Decision 3: Make hero semantics explicit through direct render structure, not through a new framework

- **Decision**: If stronger hero guarantees are needed, add small render markers and explicit DOM ordering to `PageHero.astro` rather than inventing a new semantic layer.
- **Rationale**: Spec 218 requires stable verification of category context, headline, supporting copy, CTA hierarchy, product-near visual, and optional trust cues. Those guarantees can be expressed directly in the hero render surface and smoke tests.
- **Alternatives considered**:
  - Add a separate hero registry or semantic presenter layer: rejected as premature abstraction for one public surface.
  - Rely on text-only selectors in browser tests: rejected because stable hero markers make long-term regression checks clearer and less brittle.

## Decision 4: Treat the hero visual as a curated product-truth asset

- **Decision**: Keep the hero visual tied to a product-near asset such as the current `hero-product-visual.svg`, and only replace it with another asset that remains truthfully derived from real product structure.
- **Rationale**: Spec 218 explicitly rejects generic dashboard wallpaper and fantasy metrics. The visual must support credibility by showing product-adjacent structure, even if it is stylized for the website.
- **Alternatives considered**:
  - Use abstract shapes or decorative illustration only: rejected because the spec requires product-near credibility.
  - Pull in a theme-provided analytics dashboard placeholder: rejected because it would weaken product truth and create a generic SaaS feel.

## Decision 5: Validate through focused homepage smoke coverage

- **Decision**: Prove Spec 218 with the current website build command and focused Playwright updates in `apps/website/tests/smoke/home-product.spec.ts`, adding shared helpers only if they improve clarity without broadening scope.
- **Rationale**: The hero contract is about visible public rendering, CTA hierarchy, mobile meaning order, and route reachability. Browser smoke coverage is the narrowest proving layer that can validate those concerns.
- **Alternatives considered**:
  - Build-only proof alone: rejected because static output generation does not prove CTA hierarchy, product-visual presence, or mobile ordering.
  - Add full visual regression or multi-browser matrices immediately: rejected because the feature scope does not require that extra cost.