ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
40039337d8
TenantAtlas/specs/216-homepage-structure/research.md
ahmido 40039337d8
Some checks failed
Main Confidence / confidence (push) Failing after 45s
Details
feat: implement homepage structure spec 216 (#254) 
## Summary

Implements Spec 216 for the public website homepage in `apps/website`.

This reworks the homepage into the required narrative flow:
- hero with one dominant CTA, one secondary CTA, product-near visual, and bounded trust subclaims
- outcome framing section
- grouped capability model section
- explicit trust block before the final CTA
- dated progress teaser backed by changelog entries
- final CTA transition to contact

It also adds the full spec-kit artifact set for `specs/216-homepage-structure` and updates the smoke suite to prove section order, CTA hierarchy, onward route reachability, and mobile readability.

## Validation

- `corepack pnpm build:website`
- `cd apps/website && corepack pnpm exec playwright test`

## Notes

- Branch: `216-homepage-structure`
- Commit: `097f8e70`
- Remote branch has been pushed and is ready for review.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #254
2026-04-19 12:56:05 +00:00

4.4 KiB
Raw Blame History

Research: Website Homepage Structure & Section Model

Decision 1: Keep the homepage implementation local to the static Astro website

  • Decision: Continue treating the homepage as a static apps/website route composed from Astro content modules and section components, with no runtime dependency on apps/platform.
  • Rationale: Spec 216 is explicitly website-only. The current website already runs as a standalone Astro app, and the required homepage improvements concern structure, sequencing, and public route discoverability rather than dynamic runtime behavior.
  • Alternatives considered:
    • Couple homepage composition to apps/platform or a shared API: rejected because the spec forbids platform obligations and the homepage needs no dynamic platform data.
    • Introduce a CMS or page-builder layer first: rejected because a single homepage route does not justify that operational overhead.

Decision 2: Extend the existing content-driven homepage model instead of adding a section registry

  • Decision: Preserve apps/website/src/content/pages/home.ts as the homepage source module and extend it with the smallest missing content objects for outcome, capability, trust, and progress sections.
  • Rationale: The current site already uses typed content exports and section components (PageHero, FeatureGrid, CTASection, TrustGrid, LogoStrip). This is the narrowest correct place to express homepage-specific structure without adding a polymorphic section framework.
  • Alternatives considered:
    • Build a generic section registry with discriminated unions and render dispatch: rejected as premature abstraction for one page.
    • Hardcode all new copy and structure directly in index.astro: rejected because it would weaken the existing typed content pattern and make future homepage iteration harder.

Decision 3: Recompose the homepage into an explicit narrative flow

  • Decision: Implement the homepage in the following functional order: header, hero, outcome framing, capability model, trust, progress, CTA, footer. Optional supporting context stays secondary and may only appear if it reinforces clarity.
  • Rationale: Exploration of the current homepage showed that the site already has hero, optional ecosystem context, and CTA pieces, but the middle narrative is misaligned: the current feature grid explains route jobs instead of product outcomes or capabilities, trust is too implicit, and progress is only a CTA target.
  • Alternatives considered:
    • Keep the current hero → ecosystem → route-jobs → proof → CTA sequence: rejected because it does not satisfy Spec 216’s required block responsibilities.
    • Collapse trust or progress into the CTA block: rejected because the spec requires both to appear explicitly before the final CTA.

Decision 4: Reuse existing Trust and Changelog truth for homepage proof blocks

  • Decision: Source homepage trust signals from the existing Trust content (trust.ts) and source homepage progress signals from the published changelog collection rather than inventing homepage-only proof systems.
  • Rationale: The Trust page already contains bounded public claims and principles, while the changelog route already uses dated collection entries. Reusing those sources keeps one truth for proof-oriented content and avoids duplicate claim maintenance.
  • Alternatives considered:
    • Create homepage-only trust claims arrays disconnected from /trust: rejected because it would create duplicate truth and increase drift risk.
    • Create manual homepage progress cards unrelated to the changelog collection: rejected because dated changelog truth already exists and is the stronger source.

Decision 5: Validate through the existing website smoke harness

  • Decision: Prove Spec 216 with the existing website build command and focused Playwright smoke updates for homepage section order, CTA hierarchy, and onward route reachability.
  • Rationale: The homepage contract is about public rendering, navigational clarity, and responsive visibility. Browser smoke coverage is the narrowest proving layer that can validate those concerns.
  • Alternatives considered:
    • Build-only proof alone: rejected because static output generation does not prove section order, CTA hierarchy, or visible route reachability.
    • Add visual regression or heavier browser matrices immediately: rejected because the feature scope does not require that extra cost.