TenantAtlas/specs/216-homepage-structure/spec.md

# Feature Specification: Website Homepage Structure & Section Model

**Feature Branch**: `216-homepage-structure`  
**Created**: 2026-04-19  
**Status**: Draft  
**Input**: User description: "Define Spec 216 as the website-only homepage structure and section model for `apps/website`, covering required sections, ordering, CTA logic, trust signal placement, product visuals, and onward routing."

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

- **Problem**: Without a clear homepage contract, the public website can drift into template-led marketing, feature dumps, weak trust framing, or premature sales pressure, leaving the product looking less real and less credible than it is.
- **Today's failure**: A first-time visitor can see visually polished sections yet still fail to understand what the product is, why it matters, why it should be trusted, or what the next sensible step should be.
- **User-visible improvement**: Visitors can understand the product category, the operational outcomes, the bounded trust posture, and the next route from the homepage alone without hunting through placeholder or mismatched sections.
- **Smallest enterprise-capable version**: One homepage-only structure contract that fixes the required section jobs, ordering, routing rules, product-visual expectations, trust claim rules, and excluded anti-patterns; no broader design-system rewrite or full-site IA expansion.
- **Explicit non-goals**: No final copy, no pixel or spacing decisions, no pricing surface, no full Product or Trust or Changelog spec, no CMS design, no platform UI work, no Filament theming, and no cross-app behavior changes.
- **Permanent complexity imported**: A stable homepage section vocabulary, CTA hierarchy, trust-claim guardrails, optional-section rules, and a clear structural baseline for follow-up website specs.
- **Why now**: The website foundation already exists, and the homepage needs a precise structural contract before deeper hero, screenshot, trust, and product-detail work can ship consistently.
- **Why not local**: A one-off homepage rewrite without a stated section model would not reliably prevent regression into generic SaaS patterns, weak trust sequencing, or conflicting CTAs as future iterations land.
- **Approval class**: Core Enterprise
- **Red flags triggered**: #1 introduces a homepage section taxonomy; #5 could become vocabulary-heavy if left unconstrained. The scope remains justified because the contract is strictly local to the public homepage and directly improves product clarity, trust, and onward routing.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 1 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**: `/` with onward routing to `/product`, `/trust`, `/changelog`, `/contact`, and supporting footer/legal reachability to `/privacy`, `/imprint`, and `/terms` when published
- **Data Ownership**: Workspace-owned public homepage content, section rules, CTA targets, trust/progress signals, and navigation behavior inside `apps/website`; no tenant-owned records or platform runtime data
- **RBAC**: Public-read runtime only. No authenticated membership or capability checks are required for homepage browsing; publishing remains repo-controlled.

## 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
- **Current operator problem**: Buyers and technical evaluators cannot reliably judge the product from the homepage if structure drifts into generic marketing patterns or hides trust and next-step logic.
- **Existing structure is insufficient because**: The website foundation spec establishes public-site direction broadly, but it does not lock the homepage into mandatory block responsibilities, ordering, product-near rules, or claim/routing guardrails.
- **Narrowest correct implementation**: A homepage-only section model with required blocks, optional-block rules, claim constraints, and onward-routing expectations; no broader content platform, pricing model, or multi-page taxonomy expansion.
- **Ownership cost**: Ongoing review effort to keep homepage sections, CTA hierarchy, trust claims, and downstream route links aligned with the defined contract as follow-up page specs land.
- **Alternative intentionally rejected**: Letting homepage structure emerge ad hoc from design or copy iterations was rejected because it would not reliably prevent template drift, feature walls, trust being buried, or CTA pressure outpacing clarity.
- **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**: The feature is proven by homepage section presence, information order, route discoverability, and responsive behavior rather than by tenant data, authorization, or business-rule execution.
- **New or expanded test families**: Website browser smoke coverage for homepage section order, CTA reachability, and onward route discoverability, plus the existing static build proof.
- **Fixture / helper cost impact**: Minimal. Public homepage coverage does not require seeded tenant data, auth state, or platform helpers.
- **Heavy-family visibility / justification**: none
- **Special surface test profile**: N/A
- **Standard-native relief or required special coverage**: Homepage-specific browser coverage should verify required block presence, CTA hierarchy, and route reachability; no platform-specific fixtures or heavy suites are needed.
- **Reviewer handoff**: Reviewers must confirm that the homepage exposes all required structural blocks, routes visitors to Product, Trust, Changelog, and Contact without dead ends, omits unsubstantial optional routes, and remains understandable on desktop and mobile through build proof and browser smoke coverage.
- **Budget / baseline / trend impact**: Small increase limited to homepage/browser assertions in `apps/website`.
- **Escalation needed**: none
- **Active feature PR close-out entry**: Smoke Coverage
- **Planned validation commands**: `corepack pnpm build:website` and `cd apps/website && corepack pnpm exec playwright test`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Understand the Product Fast (Priority: P1)

A first-time buyer or technical evaluator lands on the homepage and can quickly understand what TenantAtlas is, why it matters, why it appears credible, and what to do next.

**Why this priority**: If the homepage fails to create immediate product clarity and trust, every deeper surface loses value.

**Independent Test**: This can be tested by visiting the homepage alone and confirming that the product category, relevance, credibility signals, and next-step route are all understandable without opening additional pages.

**Acceptance Scenarios**:

1. **Given** a first-time visitor opens the homepage, **When** they read the hero and immediate follow-on sections, **Then** they can describe what the product is and who it is for.
2. **Given** a visitor is unsure why the product matters, **When** they read the outcome framing, **Then** they can identify the operational problem space and the type of improvement the product offers.
3. **Given** a visitor wants to know what to do next, **When** they reach the CTA hierarchy, **Then** they can distinguish the primary next step from deeper exploratory routes.

---

### User Story 2 - Evaluate Product Model and Trust Without a Feature Wall (Priority: P2)

A serious evaluator can understand the connected product model, see credible trust and progress signals, and avoid mistaking the homepage for a generic feature dump.

**Why this priority**: Homepage structure must translate capabilities into a coherent operating model and establish seriousness early enough to qualify deeper interest.

**Independent Test**: This can be tested by reviewing only the homepage sections that explain outcomes, capabilities, trust, and progress and confirming that they form one coherent story rather than disconnected cards.

**Acceptance Scenarios**:

1. **Given** a visitor wants to understand the product logic, **When** they reach the capability section, **Then** they see grouped capability areas rather than an endless list of equal-weight features.
2. **Given** a visitor needs proof the product is credible, **When** they reach the trust and progress blocks, **Then** they see bounded claims and a visible route to deeper substantiation.
3. **Given** a visitor reads the homepage end-to-end, **When** they compare the sections, **Then** trust appears early enough to support the CTA instead of arriving as an afterthought.

---

### User Story 3 - Move Into the Right Next Route (Priority: P3)

A qualified visitor can choose whether to go deeper into Product, Trust, Changelog, or Contact without guessing which route answers the next question.

**Why this priority**: The homepage should route deliberately instead of trying to absorb every downstream page or forcing immediate sales contact.

**Independent Test**: This can be tested by starting on the homepage and verifying that each next-question route is visible, understandable, and reachable without dead ends or conflicting CTAs.

**Acceptance Scenarios**:

1. **Given** a visitor wants deeper product detail, **When** they act on the capability model section, **Then** the homepage routes them to `/product`.
2. **Given** a visitor wants trust or hosting context, **When** they act on the trust block or related CTA, **Then** the homepage routes them to `/trust`.
3. **Given** a visitor wants visible product movement or a direct conversation, **When** they inspect the progress block or final CTA, **Then** they can reach `/changelog` or `/contact` through clear, non-competing actions.

### Edge Cases

- What happens when optional surfaces such as Resources, Docs, Blog, Demo, or social proof are not yet substantive? The homepage must hide or de-emphasize them rather than linking to empty or immature routes.
- How does the homepage handle trust or residency claims that cannot yet be substantiated publicly? The claim must be omitted or softened instead of being implied broadly or theatrically.
- What happens if a real screenshot is not yet ready for publication? The hero may use a credible product-near visual, but it must still communicate real product structure and must not collapse into abstract decoration.
- How does the homepage behave on narrow screens? The same meaning order must survive mobile compression, and trust, progress, product-near context, and the primary CTA must remain visible without horizontal scrolling.
- What happens when the changelog surface has only a small amount of published history? The progress signal may stay concise, but it must still indicate real dated movement and link into the actual changelog route.

## Requirements *(mandatory)*

This feature changes only the public homepage in `apps/website`. It introduces no Microsoft Graph calls, no platform authorization changes, no Filament surfaces, no queued work, and no runtime coupling to `apps/platform`.

### Functional Requirements

- **FR-001**: The homepage MUST act as a product-near routing, positioning, and trust hub for `apps/website` rather than as full product documentation, a pure feature landing page, or a generic SaaS template.
- **FR-002**: The homepage MUST answer, within the initial reading flow, what the product is, who it is for, what problem it addresses, why it should be taken seriously, and what the next sensible step is.
- **FR-003**: The homepage MUST preserve the following functional block set: header or global navigation, hero, product outcome or why-it-matters section, core capability or product model section, trust or credibility signal block, product progress or changelog signal block, primary CTA or contact-transition block, and footer. Visual combination is allowed only when each block's functional job remains clear.
- **FR-004**: The homepage MUST follow a logical order of global context, hero, outcome framing, product model, trust, progress, CTA, and footer. Minor compression is allowed, but the page MUST NOT collapse into an unordered card stack or feature wall.
- **FR-005**: The header MUST include brand navigation to `/`, access to Product, Trust, Changelog, and Contact, and MAY include Resources only when substantive content exists. It MUST present one clear primary CTA and MUST NOT expose empty or immature routes.
- **FR-006**: The hero MUST include a positioning headline, supporting copy, one primary CTA, one secondary deepening CTA, and a product-near visual. The visual SHOULD be a real screenshot or a credible UI-near representation and MUST NOT rely only on abstract shapes to convey product truth.
- **FR-007**: Hero-adjacent trust subclaims MAY appear only when they are factually supportable, narrowly phrased, non-exaggerated, and traceable to the Trust surface for deeper context.
- **FR-008**: The product outcome or why-it-matters section MUST translate the product from capabilities into buyer-relevant outcomes, friction reduction, or operational improvements. It MUST explain why the problem space matters and MUST NOT rely on buzzwords or internal feature naming alone.
- **FR-009**: The core capability or product model section MUST explain the connected product model and the major capability areas without becoming full documentation. It MUST communicate grouped capability coverage spanning backup, restore, version history, auditability, inventory or drift visibility, and governance or evidence-oriented review work.
- **FR-010**: Capability explanation MUST use grouped clusters or another clear hierarchy, MUST route deeper product understanding to `/product`, and MUST NOT present the homepage as an endless list of equal-weight feature cards.
- **FR-011**: The homepage MUST include an explicit trust or credibility block before the final CTA. This block MUST signal technical seriousness and a bounded trust posture and MUST route to `/trust` for deeper context.
- **FR-012**: Any trust, hosting, residency, security, or governance claims shown on the homepage MUST be factually substantiated, narrowly phrased, and supportable by the Trust surface. The homepage MUST NOT imply unverified compliance or use invented badges, seals, or pseudo-certifications.
- **FR-013**: The homepage MUST include a dated or clearly progress-oriented signal that the product is active and evolving, such as a changelog teaser or recent public updates. It MUST route to `/changelog` and MUST NOT behave like a padded marketing news feed.
- **FR-014**: The homepage MUST provide a clear lower-page CTA transition to `/contact` or `/demo`. Until a distinct public `/demo` route exists, the primary conversion target MUST default to `/contact`.
- **FR-015**: The CTA system MUST keep exactly one dominant primary CTA and at least one secondary deepening CTA. The homepage MUST NOT present multiple equally loud primary sales actions in parallel.
- **FR-016**: The footer MUST keep Product, Trust, Changelog, Contact, Privacy, and Imprint reachable and MAY include Terms, Resources, or Docs only when those surfaces are real and maintained.
- **FR-017**: Optional homepage sections such as social proof, use-case spotlights, FAQ, or content teasers MAY be used only when backed by real substance and MUST NOT displace required sections or fake maturity.
- **FR-018**: The homepage MUST route visitors cleanly into `/product`, `/trust`, `/changelog`, and `/contact` without attempting to replace those pages completely.
- **FR-019**: The homepage MUST stay understandable and structurally equivalent on mobile. Hero, outcome, capability, trust, progress, and CTA blocks MUST remain recognizable on narrow screens, and mobile compression MUST NOT effectively hide trust or product-near context.
- **FR-020**: The homepage MUST avoid the following disallowed patterns: template-first SaaS framing, abstract-only storytelling, unstructured feature walls, hidden trust, demo-only pressure, fake social proof, and enterprise-theater claims.
- **FR-021**: The homepage MUST remain strictly local to `apps/website` and MUST NOT create implementation or contract requirements for `apps/platform`.

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

- **Homepage Block**: A functionally distinct section of the homepage such as Hero, Outcome, Capability Model, Trust, Progress, CTA, or Footer.
- **Product-Near Visual**: A screenshot or credible UI-adjacent visual that signals a real product rather than abstract marketing decoration.
- **Trust Claim**: A bounded public assertion about hosting, residency, seriousness, isolation, governance posture, or similar credibility signals that must be supportable by the Trust surface.
- **Progress Signal**: A homepage block or teaser that shows visible dated product movement and routes to the changelog.
- **CTA Target**: A next-question route reached from the homepage, especially Product, Trust, Changelog, or Contact.

## Assumptions & Dependencies

- `/product`, `/trust`, `/changelog`, `/contact`, `/privacy`, and `/imprint` remain the canonical core routes surfaced from the homepage in `apps/website`.
- `/contact` remains the primary conversion route unless and until a distinct public `/demo` surface exists and is substantively different.
- Optional surfaces such as Resources, Docs, Blog, Demo, customer references, or social proof remain hidden or secondary until they contain real, maintained content.
- If a publishable real screenshot is not yet ready, the initial hero may use a credible product-near visual that still reflects actual product structure rather than abstract illustration.
- Trust, hosting, residency, and governance claims will be limited to statements the team can substantiate publicly at release time.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: A first-time visitor can state what the product is, why it matters, why it appears credible, and the next step after 60 seconds or less on the homepage.
- **SC-002**: The released homepage exposes all eight mandatory functional blocks, or combined equivalents without loss of function, and each of `/product`, `/trust`, `/changelog`, and `/contact` is reachable from the homepage without dead links.
- **SC-003**: The hero presents exactly one primary CTA, at least one secondary deepening CTA, and a product-near visual on both desktop and mobile layouts.
- **SC-004**: Trust and progress signals appear before the final CTA and remain discoverable without leaving the homepage, while deeper substantiation stays reachable in one click to `/trust` and `/changelog`.
- **SC-005**: No released homepage version contains unsupported trust claims, fake logos or badges, placeholder routes, or more than one equally dominant primary conversion action.
- **SC-006**: On mobile widths, visitors can still identify the hero, outcome framing, capability model, trust block, progress block, and CTA transition without horizontal scrolling or hidden primary navigation.