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