# Feature Specification: Website Homepage Hero

**Feature Branch**: `218-homepage-hero`  
**Created**: 2026-04-19  
**Status**: Draft  
**Input**: User description: "Define Spec 218 as the website-only homepage hero contract for `apps/website`, covering hero role, required elements, copy and CTA rules, product-near visual constraints, trust subclaims, layout logic, responsive behavior, and explicit anti-patterns."

## Spec Candidate Check *(mandatory - SPEC-GATE-001)*

- **Problem**: Without a clear homepage hero contract, the first screen of `apps/website` can drift into generic SaaS language, abstract visuals, weak product truth, or premature CTA pressure that makes the product feel less credible than it is.
- **Today's failure**: A first-time visitor can see a polished hero yet still fail to understand what the product is, why it matters, why it should be trusted, or which next route is the right one.
- **User-visible improvement**: Visitors can classify the product, understand the problem space, see a product-near signal, and choose a sensible next step from the hero alone.
- **Smallest enterprise-capable version**: One homepage-hero-only contract that defines the hero's role, mandatory elements, content priorities, CTA structure, product-visual rules, trust-subclaim rules, and excluded anti-patterns, without prescribing final copy or detailed visual implementation.
- **Explicit non-goals**: No full homepage structure beyond hero responsibilities, no final visual design, no final production copy, no complete Product or Trust page spec, no Pricing or Docs surface, no platform UI work, no Filament theming, no motion-spec detail, and no implementation detail for Astro or Tailwind.
- **Permanent complexity imported**: A stable website-local hero vocabulary covering category context, headline, supporting copy, CTA roles, product-near visual rules, trust-subclaim rules, information-density guardrails, and hero review criteria.
- **Why now**: The homepage structure is already defined in Spec 217, and the hero needs a tighter contract before screenshot strategy, final copy work, and Stitch exploration harden around weak defaults.
- **Why not local**: A one-off hero iteration would not reliably prevent generic marketing patterns, screenshot drift, overclaiming, or multi-CTA pressure as future design and copy passes land.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New website-local hero taxonomy; risk of drifting into design detail; risk of unsupported trust or compliance language. The scope remains justified because it is narrow, homepage-only, and directly improves product clarity and credibility.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 1 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**: `/` with onward routing from the hero into `/product`, `/trust`, `/changelog`, and `/contact`
- **Data Ownership**: Website-owned homepage-hero semantics, CTA targets, product-visual expectations, trust-subclaim boundaries, and responsive ordering inside `apps/website`; no tenant-owned records, platform runtime data, or shared persistence.
- **RBAC**: None. This feature applies to a public website surface and introduces no authorization model.

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: yes, but only within `apps/website`
- **Current operator problem**: Website contributors and reviewers do not yet have a bounded semantic contract for the most important public screen, so hero work can regress into generic marketing patterns or conflicting hero decisions.
- **Existing structure is insufficient because**: Spec 217 defines the homepage section model broadly, but it does not define the hero's specific semantic responsibilities, content priorities, screenshot truth rules, or CTA boundaries tightly enough for repeatable hero work.
- **Narrowest correct implementation**: One hero-only specification that locks the homepage hero into required semantic parts, bounded trust language, product-near visual expectations, and responsive meaning order without expanding into full page design or implementation detail.
- **Ownership cost**: Future homepage hero reviews must enforce category clarity, CTA discipline, visual truthfulness, and anti-pattern avoidance instead of allowing ad hoc exceptions to accumulate.
- **Alternative intentionally rejected**: Designing the hero directly in a theme or in Stitch without a semantic contract was rejected because it would let aesthetics re-decide product truth, CTA weight, and screenshot honesty each time.
- **Release truth**: Current-release truth

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Browser
- **Validation lane(s)**: fast-feedback
- **Why this classification and these lanes are sufficient**: This specification governs public hero rendering, claim placement, CTA hierarchy, and responsive information order on a static website surface. Browser smoke coverage and website build proof are the narrowest honest validation; no auth, tenant, database, or platform-runtime setup is required.
- **New or expanded test families**: Focused website smoke coverage for homepage hero presence, CTA reachability, visible product-near media, and mobile meaning-order checks.
- **Fixture / helper cost impact**: low; no workspace, tenant, auth, provider, or database fixtures are required.
- **Heavy-family visibility / justification**: none
- **Special surface test profile**: N/A
- **Standard-native relief or required special coverage**: Homepage-specific browser assertions are sufficient; no platform or operator-surface coverage is required.
- **Reviewer handoff**: Reviewers should confirm that the released hero includes the required semantic elements, maintains one dominant primary CTA, routes to real downstream pages, avoids unsupported trust language, and keeps product-near visibility on desktop and mobile.
- **Budget / baseline / trend impact**: none beyond small website smoke-suite growth.
- **Escalation needed**: document-in-feature
- **Active feature PR close-out entry**: Smoke Coverage
- **Planned validation commands**: `corepack pnpm build:website` and `cd apps/website && corepack pnpm exec playwright test tests/smoke/home-product.spec.ts`

## User Scenarios & Testing *(mandatory)*

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

A first-time buyer or technical evaluator lands on the homepage and can understand what the product roughly is, why it matters, and what to do next before leaving the hero.

**Why this priority**: If the hero fails to create immediate product clarity, every deeper page loses value.

**Independent Test**: This can be tested by visiting the homepage only and confirming that the hero provides category context, product/problem framing, and a clear primary next step without requiring deeper page visits.

**Acceptance Scenarios**:

1. **Given** a first-time visitor opens the homepage, **When** they read the hero, **Then** they can describe what kind of product this is and why it is relevant.
2. **Given** a visitor wants to know what to do next, **When** they inspect the hero CTAs, **Then** they can distinguish the primary next step from the secondary deepening route.
3. **Given** a visitor is unsure whether the product is real or just marketing, **When** they inspect the hero visual, **Then** they see a product-near signal rather than pure abstraction.

---

### User Story 2 - Assess credibility before committing (Priority: P2)

A serious evaluator can leave the hero with a preliminary sense that the product is real, technically serious, and careful about trust claims without the hero trying to carry the full Trust page.

**Why this priority**: The hero must establish enough credibility to earn deeper exploration, but not by overclaiming.

**Independent Test**: This can be tested by reviewing the hero only and confirming that trust language remains bounded, product-near evidence is present, and deeper trust routes are available.

**Acceptance Scenarios**:

1. **Given** the hero includes trust subclaims, **When** a reviewer inspects them, **Then** each claim is concise, supportable, and not presented as a legal or compliance guarantee.
2. **Given** a technical stakeholder scans the hero, **When** they read the copy and view the product-near visual, **Then** they see signs of governance, audit, recovery, or drift seriousness without being overwhelmed by detail.

---

### User Story 3 - Choose the right deeper route (Priority: P3)

A qualified visitor can use the hero to move into the Product, Trust, Changelog, or Contact flow instead of being forced into immediate sales contact or a dead-end route.

**Why this priority**: The hero should route intentionally, not absorb the whole website or pressure every visitor into the same action.

**Independent Test**: This can be tested by starting on the homepage hero and verifying that the visible CTA pair leads into real, maintained downstream routes with clear intent.

**Acceptance Scenarios**:

1. **Given** a visitor wants deeper product detail, **When** they use the secondary hero CTA, **Then** they reach a real downstream informational surface such as `/product` or `/trust`.
2. **Given** a visitor is ready to engage, **When** they use the primary hero CTA, **Then** they reach the intended primary next-step route without competing primary actions.

### Edge Cases

- What happens when a publishable real screenshot is not yet ready? The hero may use a curated or stylized product-near visual, but it must still reflect real product structure and must not fall back to generic dashboard wallpaper.
- How does the hero handle trust or compliance language that cannot be substantiated publicly? The claim must be softened or removed instead of implied as a guarantee.
- What happens when mobile space compresses the layout? The meaning order must remain headline, supporting copy, CTA, product-near visual, and optional trust signals, without hiding the CTA or product reality.
- What happens when too many chips, badges, or CTA ideas compete for space? The hero must reduce visible signals rather than turning into several mini-sections at once.
- What happens when a secondary CTA would lead to a weak or placeholder route? The hero must route to a stronger maintained surface or suppress that CTA until the downstream page is real.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature changes only the public homepage hero in `apps/website`. It introduces no Microsoft Graph calls, no queueing, no long-running operations, no authorization changes, and no Filament or operator-facing surface changes. Its contract is explicitly local to `apps/website` and must not create obligations for `apps/platform`.

**Constitution alignment (UI-SEM-001 / LAYER-001 / BLOAT-001):** This feature intentionally introduces a website-local hero semantic layer because ad hoc hero styling and copy decisions are insufficient to preserve product truth, CTA hierarchy, and trust boundaries. The layer remains narrow, homepage-only, and must not expand into a shared website-platform design contract.

**Implementation boundary:** Any implementation under this specification MUST preserve the existing website working contract by keeping `@tenantatlas/website`, `WEBSITE_PORT`, and the root `dev:website` / `build:website` workflows intact, and it MUST NOT introduce runtime or package coupling to `apps/platform`.

### Functional Requirements

- **FR-001**: The homepage hero MUST act as a positioning, product-near, and trust-capable entry point for `apps/website`, not as a decorative splash screen.
- **FR-002**: Within the hero alone, a first-time visitor MUST be able to answer what the product roughly is, why it matters, who it is plausibly for, why it is worth exploring further, and what the next sensible step is.
- **FR-003**: The hero MUST functionally include category context, a primary headline, supporting copy, one dominant primary CTA, one secondary CTA, and a product-near visual. Trust subclaims MAY be included when supportable.
- **FR-004**: The hero MUST prioritize product and problem understanding first, a clear next step second, product reality third, early trust signals fourth, and stylistic finish fifth.
- **FR-005**: The hero MUST include a positioning eyebrow, category context, or equivalent descriptor that anchors the product category or problem space, and it MUST NOT be pure marketing filler or the only place where category context exists.
- **FR-006**: The primary headline MUST frame the product category, problem space, or intended outcome clearly enough for quick orientation, and it MUST NOT rely on buzzwords, stacked messages, or unsupported superlatives.
- **FR-007**: Supporting copy MUST translate the headline into clearer product and problem language, MUST sharpen relevance, and MUST NOT become a miniature product page or a simple paraphrase of the headline.
- **FR-008**: The hero MUST present exactly one dominant primary CTA aligned to the current maturity of the website and product story. It MUST NOT present several equally loud primary sales actions in parallel.
- **FR-009**: The hero MUST present one secondary CTA that deepens understanding through a real maintained downstream route. It MUST remain lower-emphasis than the primary CTA and MUST NOT point to an immature or empty surface.
- **FR-010**: The hero MUST include a product-near visual. That visual MUST be credible, relevant to the product, compositionally integrated into the hero, and stronger than pure abstraction as a proof-of-product signal.
- **FR-011**: If the hero uses a screenshot, crop, or stylized product shot, it SHOULD be derived from real product reality and truthful simplification. It MUST NOT invent fantasy product UI, fake metrics, or generic analytics-template dashboards.
- **FR-012**: Optional trust subclaims or trust chips MAY appear only when they are factually correct, concise, and supportable by deeper public context such as `/trust`. They MUST NOT turn into a badge wall or imply legal, compliance, or security guarantees that the website cannot responsibly substantiate.
- **FR-013**: The hero MUST keep information density controlled: one main headline, one supporting-copy block, one dominant primary CTA, one secondary CTA, one visual focus, and only a small number of trust signals.
- **FR-014**: The hero MUST include a clear text core and a clear visual focus. It MAY use left-right or top-bottom composition, but text clarity and CTA visibility MUST remain primary.
- **FR-015**: The product-near visual SHOULD feel like part of the same hero composition rather than a detached block. The hero MUST NOT become image-only, text-only where product-near material is available, or readability-damaging decorative layering.
- **FR-016**: Any design or Stitch exploration based on this specification MUST preserve the semantic hero structure of category context, headline, supporting copy, primary CTA, secondary CTA, product-near visual, and optional trust chips. Exploration MUST NOT re-decide homepage IA or product positioning from scratch.
- **FR-017**: On mobile, the hero MUST preserve the meaning order of headline, supporting copy, CTA, product-near visual, and optional trust signals.
- **FR-018**: Mobile simplification MAY crop, reduce, or reorder the visual, but it MUST NOT remove a product-near visual entirely when that visual is a key credibility signal, and it MUST NOT bury the CTA.
- **FR-019**: The hero MUST avoid the following disallowed patterns: generic startup hero, abstract-only hero, dashboard-wallpaper hero, badge-overload hero, sales-pressure hero, and compliance-theater hero.
- **FR-020**: The hero MUST support both buyer-oriented clarity and first-pass technical plausibility by signaling that governance, audit, recovery, drift, or similar operational concerns are real parts of the product without trying to explain the full product in one screen.
- **FR-021**: This specification MUST remain strictly local to `apps/website` and MUST NOT create implementation, design, routing, or runtime obligations for `apps/platform`.
- **FR-022**: This specification MUST define, at minimum, the hero's functional role, mandatory elements, copy rules, CTA rules, product-visual rules, trust-subclaim rules, information-density rules, prohibited anti-patterns, and the hero semantic structure required for downstream design exploration.

#### Out of Scope

- Full homepage composition beyond the hero
- Final pixel-level visual design
- Final production copy
- Full Product page, Trust page, Pricing page, Docs surface, or Contact flow specification
- Platform UI, Filament theming, or `apps/platform` behavior
- Astro, Tailwind, animation, or implementation-detail prescriptions
- A full screenshot strategy beyond hero truthfulness and credibility boundaries

### Key Entities *(include if feature involves data)*

- **Category Context**: The short eyebrow, descriptor, or context cue that anchors the hero in a believable product category or problem space.
- **Product-Near Visual**: A screenshot, crop, or truthful stylized product shot that signals real product existence and supports positioning.
- **Hero CTA Pair**: The primary action and lower-emphasis secondary deepening route that move visitors into the correct next step.
- **Trust Subclaim**: A concise early trust signal that is factual, bounded, and supportable by a deeper public trust surface.
- **Hero Semantic Structure**: The ordered set of content roles that design exploration must preserve even as visual execution evolves.

## Assumptions & Dependencies

- This specification builds on [Spec 214](../214-website-visual-foundation/spec.md), [Spec 215](../215-website-core-pages/spec.md), and [Spec 217](../217-homepage-structure/spec.md).
- `/product`, `/trust`, `/changelog`, and `/contact` remain the canonical downstream routes surfaced from the homepage hero.
- A publishable product-near screenshot or truthful visual approximation can be prepared without inventing product functionality.
- Trust, hosting, residency, governance, and compliance-adjacent language will stay limited to claims the team can support publicly.
- Later hero copy exploration, screenshot strategy, and Stitch design work must treat this specification as a semantic boundary rather than as optional inspiration.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: A first-time visitor can state what the product roughly is, why it matters, and the next sensible action within 60 seconds of reading the homepage hero.
- **SC-002**: The released hero includes all required functional roles: category context, primary headline, supporting copy, one dominant primary CTA, one secondary CTA, and a product-near visual on both desktop and mobile presentations.
- **SC-003**: Zero released hero variants contain unsupported compliance or security-guarantee language, fake trust badges, or fabricated product metrics.
- **SC-004**: From the hero alone, a visitor can reach at least one deeper informational surface and one primary next-step surface in one click, with no competing equally dominant primary actions.
- **SC-005**: On representative desktop and mobile widths, the primary CTA and the product-near visual remain visible without horizontal scrolling or loss of headline-first reading order.
- **SC-006**: Reviewers can map the shipped hero to the allowed semantic structure and confirm that it does not match any prohibited anti-pattern family defined by this specification.

## Planned Follow-on Work

- Product-visual and screenshot strategy
- Final hero copy exploration
- Stitch-based hero design exploration
- Downstream homepage-section detail work that assumes this hero contract rather than redefining it

## Spec 223 Rebuild Status

- **Classification**: continuing
- **Forward owner**: `../223-astrodeck-website-rebuild/mappings/spec-218-homepage-hero.md`
- **Material drift**: none logged. AstroDeck can provide the hero shell, but it does not change the allowed semantic structure or anti-pattern rules.
- **Forward-work rule**: mapped AstroDeck hero primitives must keep one clear anchor, one CTA pair, product-near visual truth, and bounded trust cues on desktop and mobile.
