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

Feature Specification: Website Homepage Structure & Section Model

Feature Branch: 217-homepage-structure
Created: 2026-04-19
Status: Draft
Input: User description: "Define Spec 217 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.

Hero Direction Addendum (Homepage Hero Refinement / Anti-Generic Direction)

This addendum sharpens Spec 217 without widening scope beyond apps/website. The base homepage contract already fixes structure, routing, trust sequencing, and CTA discipline. This refinement adds the missing art-direction guardrail: the hero must not be merely correct and calm; it must also be distinct, product-specific, and immediately recognizable as TenantAtlas.

Additional Problem Definition

• A hero can satisfy the structural contract and still fail if it has no clear visual stance, feels like a neat shadcn or Tailwind midpoint, spreads attention evenly, or uses so many similar neutral surfaces that nothing leads.
• TenantAtlas needs a hero that reads as a serious governance surface, not as a generic friendly SaaS shell with better spacing.
• The failure mode to avoid is not visual loudness but visual anonymity: a clean hero that nobody remembers after ten seconds is still a failed hero.

Direction Principles

• Distinctive restraint: The hero SHOULD remain calm, but calmness MUST still feel intentional and ownable rather than default-neutral.
• One dominant idea: The hero MUST have one clearly dominant focal point, whether that is the headline, the product visual, or a deliberately weighted composition of both.
• Product-first art direction: The hero SHOULD feel like an entry into the product, not a generic marketing scaffold decorated with UI.
• Controlled brand signal: Brand signal MUST come primarily from typography, contrast, composition, product truth, and accent discipline rather than from decorative effects.
• No neutral drift: Neutral-first styling MAY remain the baseline, but the hero MUST NOT flatten into washed-out sameness, accidental softness, or brandless enterprise blandness.

Hero Anti-Patterns

• Correct but forgettable: Everything is structurally right, but nothing leaves a mark.
• Neutral mush: Too many similar light surfaces and too little hierarchy or focus.
• Dashboard wallpaper: The product visual exists, but it behaves as decorative scenery rather than as a meaning-carrying surface.
• Generic shadcn marketing: Good spacing and clean cards, but no product-specific identity or visual stance.
• Over-disciplined minimalism: The hero becomes so restrained that it stops leading.
• Brandless enterprise: The page looks professional, but not like TenantAtlas.

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.
• FR-022: The homepage hero MUST be distinct and memorable enough to signal TenantAtlas as a serious governance surface; structural correctness and visual cleanliness alone are not sufficient.
• FR-023: The hero MUST establish one clear primary anchor through the headline, the product visual, or a deliberately weighted composition of both. Text, CTA, badge, and product visual MUST NOT all compete as equally weak elements.
• FR-024: The hero MUST create internal contrast through scale, whitespace, typography, surface hierarchy, accent placement, or a combination of these. Near-identical surface values across the text block, supporting elements, and visual block are not sufficient.
• FR-025: Hero typography SHOULD create more tension than standard UI copy through a clear size hierarchy, controlled line breaks, display treatment, or similarly intentional framing. The headline MUST remain scannable and formally deliberate rather than blocky or purely utilitarian.
• FR-026: Supporting copy in the hero MUST serve the headline focus and MUST NOT claim equal visual priority.
• FR-027: The hero product visual MUST depict governance-, audit-, drift-, review-, restore-, evidence-, or bounded-access-oriented product truth and MUST NOT read as a generic analytics dashboard, vague KPI slab, or decorative admin table.
• FR-028: The hero product visual SHOULD feel compositionally integrated with the hero surface and MUST NOT read as a generic screenshot box inserted beside unrelated marketing copy.
• FR-029: Neutral-first color usage MAY remain the baseline, but the hero MUST still provide a clear hierarchy and MUST NOT collapse into washed-out sameness or accidental softness.
• FR-030: Brand signal in the hero MUST come primarily from typography, contrast, composition, product specificity, and disciplined accent usage rather than from decorative effects or scattered color.
• FR-031: Hero CTA composition MUST reinforce the primary anchor. The primary CTA MUST remain clearly dominant, and the secondary CTA SHOULD remain legible without reading as a generic outline fallback detached from the rest of the hero.
• FR-032: The hero MUST avoid the following additional anti-patterns: correct but forgettable, neutral mush, dashboard wallpaper, generic shadcn marketing, over-disciplined minimalism, and brandless enterprise.

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.
• Hero Primary Anchor: The single dominant focal point in the hero, formed by the headline, the product visual, or an intentionally weighted composition of both.
• Governance-Specific Product Visual: A hero visual that communicates change history, baselines, drift, findings, review workflows, restore planning, evidence, or scoped actions rather than generic KPI output.
• Hero Anti-Pattern: A hero failure mode such as neutral mush or dashboard wallpaper that can satisfy structural correctness while still failing memorability or product specificity.

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.
• SC-007: In a homepage review, a reviewer can identify the hero's primary anchor within 10 seconds and can distinguish headline, product visual, and CTA hierarchy without ambiguity.
• SC-008: The hero visual communicates at least one TenantAtlas-specific governance concept such as drift, review, restore, evidence, or bounded access rather than generic dashboard activity.
• SC-009: Reviewers can identify at least one typographic or compositional cue and one product-truth cue that distinguish the hero from a generic shadcn or Tailwind marketing layout.
• SC-010: On desktop and mobile, the hero retains clear contrast between the dominant element, supporting copy, product visual, and CTA instead of flattening into visually equal neutral surfaces.
• SC-011: The released homepage hero avoids the anti-patterns of neutral mush and correct-but-forgettable minimalism while remaining calm and trust-oriented.

Spec 223 Rebuild Status

• Classification: continuing
• Forward owner: ../223-astrodeck-website-rebuild/mappings/spec-217-homepage-structure.md
• Material drift: none logged. Optional AstroDeck proof sections are handled as remove/adapt decisions inside the mapping sheet, not as structural homepage truth changes.
• Forward-work rule: AstroDeck homepage work must preserve the required block order of hero, outcome, product model, trust, progress, CTA, and footer.