TenantAtlas/specs/218-homepage-hero/plan.md

# Implementation Plan: Website Homepage Hero

**Branch**: `218-homepage-hero` | **Date**: 2026-04-19 | **Spec**: `specs/218-homepage-hero/spec.md`
**Input**: Feature specification from `specs/218-homepage-hero/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.

## Summary

- Tighten the `apps/website` homepage hero so the first screen satisfies Spec 218: category context, precise headline and supporting copy, one clear CTA pair, a product-near visual, and bounded early trust signals.
- Implement the change by reusing the current `homeHero` content object and `PageHero.astro`, adding only the smallest missing semantic hooks, ordering guarantees, and asset or copy refinements instead of introducing a new hero framework.
- Validate the result with `corepack pnpm build:website` plus focused Playwright smoke coverage for hero composition, CTA hierarchy, visual truthfulness, and mobile meaning order.

## Technical Context

**Language/Version**: Astro 6.0.0 templates + TypeScript 5.9.x  
**Primary Dependencies**: Astro 6, Tailwind CSS v4, existing Astro content modules and section primitives, Playwright browser smoke tests  
**Storage**: Static filesystem content and assets under `apps/website/src` and `apps/website/public`; no database  
**Testing**: `corepack pnpm build:website` plus Playwright smoke coverage in `apps/website/tests/smoke`  
**Validation Lanes**: fast-feedback
**Target Platform**: Static public website for modern desktop and mobile browsers  
**Project Type**: Web application in a monorepo (`apps/platform` plus `apps/website`)  
**Performance Goals**: Keep the hero server-rendered and readable without required client-side hydration, preserve fast first-read clarity on desktop and mobile, and keep the product visual and CTA visible on narrow screens  
**Constraints**: Stay strictly inside `apps/website`; preserve canonical core routes (`/`, `/product`, `/trust`, `/changelog`, `/contact`); keep one dominant primary CTA and one lower-emphasis secondary CTA; avoid unsupported trust claims, generic dashboard visuals, and any runtime coupling to `apps/platform`  
**Scale/Scope**: One homepage route, one shared hero component, one hero content object, one product-near asset, and a focused extension of the existing homepage smoke coverage

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing surface change
- **Native vs custom classification summary**: N/A - public Astro website surface only
- **Shared-family relevance**: none
- **State layers in scope**: page
- **Handling modes by drift class or surface**: N/A
- **Repository-signal treatment**: report-only
- **Special surface test profiles**: N/A
- **Required tests or manual smoke**: manual-smoke plus homepage-focused browser smoke coverage
- **Exception path and spread control**: none
- **Active feature PR close-out entry**: Smoke Coverage

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first / snapshots / Graph contract / deterministic capabilities / RBAC-UX / Filament guardrails: N/A for this feature because all work stays on the public Astro website and changes no `/admin`, `/admin/t/{tenant}/...`, or `/system` runtime surfaces.
- Read/write separation: Pass. The homepage hero remains a static public read surface. No writes, remote calls, queued work, or contact submission backend are introduced in this feature.
- Workspace and tenant isolation: Pass. The hero stays runtime-independent from `apps/platform`, with no shared auth, session, tenant data, or scoped route behavior.
- Data minimization: Pass. The feature only refines public copy, CTA paths, visual assets, and render semantics already owned by `apps/website`.
- Test governance: Pass. Proof remains in `fast-feedback` through static build output and focused browser smoke coverage, with no database, membership, provider, or heavy-suite defaults.
- Proportionality / no premature abstraction: Pass. The plan reuses `home.ts`, `PageHero.astro`, current CTA primitives, and the existing smoke harness instead of introducing a hero registry, CMS layer, or presentation framework.
- Persisted truth / new state: Pass. No database artifacts, queues, or independent state machines are added. Hero trust signals and the product-near visual remain file-based and derived from public website truth.
- UI semantics / few layers: Pass. The hero contract maps directly from `homeHero` content into `PageHero.astro`, with only thin render hooks or test markers if needed.

Status: ✅ No constitution violations identified before research.

## Test Governance Check

- **Test purpose / classification by changed surface**: Browser
- **Affected validation lanes**: fast-feedback
- **Why this lane mix is the narrowest sufficient proof**: The feature changes only public hero rendering, CTA emphasis, visual truthfulness, and responsive visibility. Browser smoke coverage is the narrowest layer that can prove those concerns without introducing backend or heavy browser-matrix cost.
- **Narrowest proving command(s)**: `corepack pnpm build:website` and `cd apps/website && corepack pnpm exec playwright test tests/smoke/home-product.spec.ts`
- **Fixture / helper / factory / seed / context cost risks**: none; public routes do not require database, auth, provider, workspace, or tenant setup
- **Expensive defaults or shared helper growth introduced?**: no; any helper additions stay inside the existing `apps/website/tests/smoke` harness and remain homepage-focused
- **Heavy-family additions, promotions, or visibility changes**: none
- **Surface-class relief / special coverage rule**: N/A
- **Closing validation and reviewer handoff**: Re-run the website build and the focused homepage smoke file after hero changes. If shared smoke helpers change materially, reviewers may also run the full website smoke suite. Reviewers should verify required hero elements, one dominant CTA pair, visible product-near media, bounded trust cues, and mobile visibility order.
- **Budget / baseline / trend follow-up**: none beyond a small increase in homepage smoke assertions
- **Review-stop questions**: Does proof stay homepage-focused and browser-only? Did the change accidentally introduce a new abstraction or shared helper burden? Does the mobile layout keep CTA and product-near visual visible? Are trust claims still bounded and supportable?
- **Escalation path**: document-in-feature
- **Active feature PR close-out entry**: Smoke Coverage
- **Why no dedicated follow-up spec is needed**: Validation remains feature-local to the homepage hero and the existing website smoke harness. A separate follow-up spec is only needed if screenshot governance, visual-regression tooling, or multi-page hero conventions become shared structural concerns.

## Project Structure

### Documentation (this feature)

```text
specs/218-homepage-hero/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── homepage-hero.openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
apps/website/
├── package.json
├── public/
│   └── images/
│       └── hero-product-visual.svg
├── src/
│   ├── content/
│   │   └── pages/
│   │       ├── home.ts
│   │       ├── product.ts
│   │       └── trust.ts
│   ├── components/
│   │   ├── content/
│   │   ├── primitives/
│   │   └── sections/
│   │       └── PageHero.astro
│   ├── pages/
│   │   └── index.astro
│   └── types/
│       └── site.ts
└── tests/
    └── smoke/
        ├── home-product.spec.ts
        └── smoke-helpers.ts
```

**Structure Decision**: Keep the feature completely inside `apps/website`, reusing the existing `HeroContent` data shape, `PageHero.astro`, and homepage smoke suite. Prefer small edits to `home.ts`, `PageHero.astro`, and homepage smoke assertions over new hero components, registries, or cross-page content frameworks.

## Complexity Tracking

None.

## Proportionality Review

- **Current operator problem**: The homepage hero is the highest-risk public screen for drift into generic marketing or weak product truth, so small regressions there have disproportionate impact on credibility and next-step clarity.
- **Existing structure is insufficient because**: Spec 217 establishes homepage section flow broadly, but the current implementation still needs a hero-specific contract to lock down required semantics, CTA hierarchy, product-near truth, and mobile meaning order.
- **Narrowest correct implementation**: Reuse the existing `homeHero` content object and `PageHero.astro`, tightening content, render semantics, and smoke coverage only where Spec 218 requires stronger guarantees.
- **Ownership cost created**: Ongoing maintenance of explicit hero content rules, a product-near visual asset, and a slightly richer homepage smoke suite.
- **Alternative intentionally rejected**: A generic hero framework or a separate CMS-like hero configuration layer was rejected because only one homepage hero needs this contract now and the current Astro content model already fits the problem.
- **Release truth**: Current-release truth

## Phase 0 — Outline & Research (complete)

- Output: `specs/218-homepage-hero/research.md`
- Key decisions captured:
  - Keep the hero local to the static Astro website and preserve runtime separation from `apps/platform`.
  - Reuse the existing `homeHero` content object and `PageHero.astro` instead of adding a new hero abstraction.
  - Treat hero semantics as explicit render responsibilities that can be tested directly.
  - Keep the product visual truthful and derived from real product structure rather than decorative SaaS wallpaper.
  - Validate through focused Playwright homepage smoke coverage plus build proof.

## Phase 1 — Design & Contracts (complete)

### Data model

- Output: `specs/218-homepage-hero/data-model.md`
- Model remains file- and route-based. No database schema changes are required.

### Public hero contract

- Output: `specs/218-homepage-hero/contracts/homepage-hero.openapi.yaml`
- Contract captures the homepage route plus the hero-only semantic requirements and downstream route expectations for Product, Trust, Changelog, and Contact.

### Quickstart

- Output: `specs/218-homepage-hero/quickstart.md`
- Quickstart covers local development, hero-specific verification points, build proof, and focused smoke-test execution.

### Agent context update

- Completed via `.specify/scripts/bash/update-agent-context.sh copilot` after plan artifacts were generated.

### Constitution re-check (post-design)

- ✅ The plan remains website-only and static, with no platform-runtime coupling.
- ✅ No new persistence, state machines, background operations, or auth flows are introduced.
- ✅ The chosen shape reuses existing Astro content modules, CTA primitives, and section components instead of adding speculative abstraction.
- ✅ Validation remains cheap, local, and aligned with the current website smoke harness.

## Phase 2 — Implementation Plan (next)

### Story 1 (P1): Understand the product from the first screen

- Review and tighten `apps/website/src/content/pages/home.ts` so the hero eyebrow, headline, supporting copy, CTA pair, and visual all align with Spec 218 language and positioning rules without hype or stacked claims.
- Keep hero composition inside `apps/website/src/components/sections/PageHero.astro`; add only the smallest missing semantic hooks and DOM structure needed to expose category context, headline, supporting copy, CTA pair, product-near visual, and optional trust subclaims as explicit hero elements.
- Preserve one dominant primary CTA to `/contact` and one secondary deepening CTA to `/product`, unless a stronger already-supported secondary destination is chosen during copy review.
- Tests / validation:
  - Extend `apps/website/tests/smoke/home-product.spec.ts` and `apps/website/tests/smoke/smoke-helpers.ts` only as needed to assert the required hero elements and one clear CTA pair.
  - Re-run `corepack pnpm build:website`.

### Story 2 (P2): Establish credibility without overclaiming

- Review `homeHero.trustSubclaims` against the current `/trust` public truth so any hero subclaim remains bounded, factual, concise, and supportable.
- Confirm `apps/website/public/images/hero-product-visual.svg` and its alt text remain product-near and truthfully derived from real UI structure; replace or tighten only if the asset reads like a generic dashboard or decorative placeholder.
- Ensure the hero stays product-near even if the visual remains stylized, and avoid introducing a separate trust badge, compliance matrix, or homepage-only proof system.
- Tests / validation:
  - Add smoke assertions for visible product-near media, concise trust signals, and continued homepage reachability to `/trust` and other downstream routes.
  - Keep assertions inside homepage smoke coverage; do not add a new visual-regression matrix.

### Story 3 (P3): Preserve correct next-step routing on desktop and mobile

- Verify the hero meaning order stays stable across desktop and narrow screens: category context and headline, supporting copy, CTA pair, product-near visual, and optional trust signals.
- Tighten responsive composition inside `PageHero.astro` only as needed to keep CTA and product visual visible without reordering semantics or hiding credibility cues on mobile.
- Finalize targeted smoke coverage for mobile visibility and hero-first route reachability into `/product`, `/contact`, and supporting public surfaces.
- Tests / validation:
  - Extend `apps/website/tests/smoke/home-product.spec.ts` with narrow-screen hero checks or extracted helper assertions in `smoke-helpers.ts`.
  - Run `cd apps/website && corepack pnpm exec playwright test tests/smoke/home-product.spec.ts`.

## Implementation Close-out

- Homepage hero delivery stayed local to `apps/website` and reused the existing `homeHero` content object plus `PageHero.astro` with no new hero framework or platform coupling.
- The shipped hero now exposes explicit semantic hooks for category context, headline, supporting copy, CTA pair, product-near visual, and trust cues, while keeping one primary CTA to `/contact` and one secondary deepening CTA to `/product`.
- The product visual was replaced with a product-near operating-record illustration that avoids fake KPI cards or generic analytics-dashboard theater.
- Shared smoke-helper growth stayed homepage-focused in `apps/website/tests/smoke/smoke-helpers.ts`; no auth, backend, provider, or database fixtures were introduced.
- Validation completed on 2026-04-19 with `corepack pnpm build:website` and `cd apps/website && corepack pnpm exec playwright test tests/smoke/home-product.spec.ts`.