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)

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

Source Code (repository root)

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.