ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
712576c447
TenantAtlas/specs/218-homepage-hero/research.md
ahmido cebd5ee1b0
Some checks failed
Main Confidence / confidence (push) Failing after 50s
Details
Agent: commit workspace changes (217-homepage-hero-session-1776809852) (#259) 
Automated commit by agent: commits workspace changes for feature 217-homepage-hero. Please review and merge into `dev`.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #259
2026-04-21 22:24:29 +00:00

4.2 KiB
Raw Blame History

Research: Website Homepage Hero

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

  • Decision: Continue treating the homepage hero as a static apps/website concern composed from the current Astro content module and section component, with no runtime dependency on apps/platform.
  • Rationale: Spec 218 is explicitly website-only. The current website already runs as a standalone Astro app, and the hero changes concern semantics, copy discipline, asset truthfulness, and responsive ordering rather than dynamic runtime behavior.
  • Alternatives considered:
    • Couple hero content to apps/platform or a shared API: rejected because the spec forbids platform obligations and the hero needs no dynamic platform data.
    • Introduce a CMS or hero-builder layer first: rejected because one homepage hero does not justify that operational overhead.

Decision 2: Reuse the existing homeHero content object and PageHero.astro

  • Decision: Preserve apps/website/src/content/pages/home.ts as the canonical source for hero content and refine apps/website/src/components/sections/PageHero.astro as the render surface instead of creating a new hero abstraction.
  • Rationale: The current site already uses typed content exports and a shared PageHero component. This is the narrowest correct place to express hero-specific semantics without adding a second content shape, a render registry, or a page-builder concept.
  • Alternatives considered:
    • Build a homepage-hero-specific component tree parallel to PageHero.astro: rejected because the existing component already supports eyebrow, CTA pair, product visual, and trust subclaims.
    • Hardcode all hero content directly in index.astro: rejected because it would bypass the current typed content pattern and make later hero iteration less disciplined.

Decision 3: Make hero semantics explicit through direct render structure, not through a new framework

  • Decision: If stronger hero guarantees are needed, add small render markers and explicit DOM ordering to PageHero.astro rather than inventing a new semantic layer.
  • Rationale: Spec 218 requires stable verification of category context, headline, supporting copy, CTA hierarchy, product-near visual, and optional trust cues. Those guarantees can be expressed directly in the hero render surface and smoke tests.
  • Alternatives considered:
    • Add a separate hero registry or semantic presenter layer: rejected as premature abstraction for one public surface.
    • Rely on text-only selectors in browser tests: rejected because stable hero markers make long-term regression checks clearer and less brittle.

Decision 4: Treat the hero visual as a curated product-truth asset

  • Decision: Keep the hero visual tied to a product-near asset such as the current hero-product-visual.svg, and only replace it with another asset that remains truthfully derived from real product structure.
  • Rationale: Spec 218 explicitly rejects generic dashboard wallpaper and fantasy metrics. The visual must support credibility by showing product-adjacent structure, even if it is stylized for the website.
  • Alternatives considered:
    • Use abstract shapes or decorative illustration only: rejected because the spec requires product-near credibility.
    • Pull in a theme-provided analytics dashboard placeholder: rejected because it would weaken product truth and create a generic SaaS feel.

Decision 5: Validate through focused homepage smoke coverage

  • Decision: Prove Spec 218 with the current website build command and focused Playwright updates in apps/website/tests/smoke/home-product.spec.ts, adding shared helpers only if they improve clarity without broadening scope.
  • Rationale: The hero contract is about visible public rendering, CTA hierarchy, mobile meaning order, and route reachability. 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 CTA hierarchy, product-visual presence, or mobile ordering.
    • Add full visual regression or multi-browser matrices immediately: rejected because the feature scope does not require that extra cost.