ahmido
cebd5ee1b0
Some checks failed
Main Confidence / confidence (push) Failing after 50s
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
41 lines
4.2 KiB
Markdown
41 lines
4.2 KiB
Markdown
# 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. |