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
256 lines
17 KiB
Markdown
256 lines
17 KiB
Markdown
# Implementation Plan: Website Homepage Structure & Section Model
|
||
|
||
**Branch**: `216-homepage-structure` | **Date**: 2026-04-19 | **Spec**: `specs/216-homepage-structure/spec.md`
|
||
**Input**: Feature specification from `specs/216-homepage-structure/spec.md`
|
||
|
||
**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.
|
||
|
||
## Summary
|
||
|
||
- Rework the `apps/website` homepage into the explicit section flow required by Spec 216: hero, outcome framing, capability model, trust, progress, CTA, while preserving existing header and footer shells.
|
||
- Implement the change by extending the current Astro content-driven homepage model (`src/content/pages/home.ts`) and existing section primitives instead of adding a new section registry or CMS-like composition layer.
|
||
- Reuse existing Trust and Changelog truth for homepage proof signals, and validate the result with the current website build proof plus focused Playwright smoke coverage.
|
||
|
||
## Technical Context
|
||
|
||
**Language/Version**: Astro 6.0.0 templates + TypeScript 5.9.x
|
||
**Primary Dependencies**: Astro 6, Tailwind CSS v4, local Astro layout/section primitives, Astro content collections, Playwright browser smoke tests
|
||
**Storage**: Static filesystem content, Astro content collections, and assets under `apps/website/src` and `apps/website/public`; no database
|
||
**Testing**: `corepack pnpm build:website` plus Playwright smoke coverage in `apps/website/tests/smoke`
|
||
**Validation Lanes**: fast-feedback
|
||
**Target Platform**: Static public website for modern desktop and mobile browsers
|
||
**Project Type**: Web application in a monorepo (`apps/platform` plus `apps/website`)
|
||
**Performance Goals**: Preserve static HTML output for homepage and linked public routes, keep reading/navigation flows usable without required client-side framework hydration, and keep the primary homepage narrative legible on desktop and mobile
|
||
**Constraints**: Stay strictly inside `apps/website`; preserve canonical core routes (`/`, `/product`, `/trust`, `/changelog`, `/contact`); keep one dominant primary CTA; hide unsubstantial optional routes; avoid unsupported trust claims and platform runtime coupling
|
||
**Scale/Scope**: One homepage route, eight required functional blocks, four canonical onward routes, existing shared section components, and a small extension to the current browser smoke suite
|
||
|
||
## UI / Surface Guardrail Plan
|
||
|
||
- **Guardrail scope**: no operator-facing surface change
|
||
- **Native vs custom classification summary**: N/A - public Astro website surface only
|
||
- **Shared-family relevance**: none
|
||
- **State layers in scope**: page
|
||
- **Handling modes by drift class or surface**: N/A
|
||
- **Repository-signal treatment**: report-only
|
||
- **Special surface test profiles**: N/A
|
||
- **Required tests or manual smoke**: manual-smoke plus homepage-focused browser smoke coverage
|
||
- **Exception path and spread control**: none
|
||
- **Active feature PR close-out entry**: Smoke Coverage
|
||
|
||
## Constitution Check
|
||
|
||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||
|
||
- Inventory-first / snapshots / Graph contract / deterministic capabilities / RBAC-UX / Filament guardrails: N/A for this feature because all work stays on the public Astro website and changes no `/admin`, `/admin/t/{tenant}/...`, or `/system` runtime surfaces.
|
||
- Read/write separation: Pass. The homepage remains a static public read surface. No writes, remote calls, queued work, or contact submission backend are introduced in this feature.
|
||
- Workspace and tenant isolation: Pass. The homepage stays runtime-independent from `apps/platform`, with no shared auth, session, tenant data, or tenant-scoped route behavior.
|
||
- Data minimization: Pass. The feature only rearranges and extends public content, navigation, and collection-backed teasers inside `apps/website`.
|
||
- Test governance: Pass. Proof remains in `fast-feedback` through static build output and focused browser smoke coverage, with no database, membership, provider, or heavy-suite defaults.
|
||
- Proportionality / no premature abstraction: Pass. The implementation extends the existing `home.ts` content module and current section primitives instead of introducing a generic section registry, CMS abstraction, or separate homepage framework.
|
||
- Persisted truth / new state: Pass. No database artifacts, queues, or independent state machines are added. Homepage progress visibility stays derived from the existing changelog collection.
|
||
- UI semantics / few layers: Pass. The homepage contract maps directly to existing content objects and section components, with thin additions for missing blocks rather than a presentation meta-layer.
|
||
|
||
Status: ✅ No constitution violations identified before research.
|
||
|
||
## Test Governance Check
|
||
|
||
- **Test purpose / classification by changed surface**: Browser
|
||
- **Affected validation lanes**: fast-feedback
|
||
- **Why this lane mix is the narrowest sufficient proof**: The feature changes only public HTML composition, route discoverability, CTA hierarchy, and responsive section visibility. Browser smoke coverage is the narrowest layer that can prove those concerns without introducing backend or heavy end-to-end cost.
|
||
- **Narrowest proving command(s)**: `corepack pnpm build:website` and `cd apps/website && corepack pnpm exec playwright test`
|
||
- **Fixture / helper / factory / seed / context cost risks**: none; public routes do not require database, auth, provider, workspace, or tenant setup
|
||
- **Expensive defaults or shared helper growth introduced?**: no; test updates stay inside the existing `apps/website/tests/smoke` harness
|
||
- **Heavy-family additions, promotions, or visibility changes**: none
|
||
- **Surface-class relief / special coverage rule**: N/A
|
||
- **Closing validation and reviewer handoff**: Re-run the website build and smoke suite after homepage/content changes. Reviewers should verify required homepage block order, clear CTA hierarchy, reachability of `/product`, `/trust`, `/changelog`, and `/contact`, and continued mobile readability without optional-route leakage.
|
||
- **Budget / baseline / trend follow-up**: none beyond the existing lightweight website smoke runtime
|
||
- **Review-stop questions**: Does proof stay browser-focused and route-focused? Did the feature accidentally add shared helper cost or client-side runtime coupling? Are optional unpublished routes still hidden from homepage prominence?
|
||
- **Escalation path**: document-in-feature
|
||
- **Active feature PR close-out entry**: Smoke Coverage
|
||
- **Why no dedicated follow-up spec is needed**: Validation remains feature-local to the homepage and the existing website smoke harness. A separate test-governance spec is only needed if the public site later grows interactive flows or broader browser coverage families.
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/216-homepage-structure/
|
||
├── plan.md
|
||
├── research.md
|
||
├── data-model.md
|
||
├── quickstart.md
|
||
├── contracts/
|
||
│ └── homepage-surface.openapi.yaml
|
||
└── tasks.md
|
||
```
|
||
|
||
### Source Code (repository root)
|
||
|
||
```text
|
||
apps/website/
|
||
├── package.json
|
||
├── src/
|
||
│ ├── content.config.ts
|
||
│ ├── content/
|
||
│ │ ├── changelog/
|
||
│ │ └── pages/
|
||
│ │ ├── changelog.ts
|
||
│ │ ├── home.ts
|
||
│ │ ├── product.ts
|
||
│ │ └── trust.ts
|
||
│ ├── components/
|
||
│ │ ├── content/
|
||
│ │ ├── layout/
|
||
│ │ ├── primitives/
|
||
│ │ └── sections/
|
||
│ │ ├── CTASection.astro
|
||
│ │ ├── FeatureGrid.astro
|
||
│ │ ├── LogoStrip.astro
|
||
│ │ ├── PageHero.astro
|
||
│ │ └── TrustGrid.astro
|
||
│ ├── lib/
|
||
│ │ └── site.ts
|
||
│ ├── pages/
|
||
│ │ ├── changelog.astro
|
||
│ │ ├── contact.astro
|
||
│ │ ├── index.astro
|
||
│ │ ├── product.astro
|
||
│ │ └── trust.astro
|
||
│ └── types/
|
||
│ └── site.ts
|
||
└── tests/
|
||
└── smoke/
|
||
├── changelog-core-ia.spec.ts
|
||
├── home-product.spec.ts
|
||
└── smoke-helpers.ts
|
||
```
|
||
|
||
**Structure Decision**: Keep the feature completely inside `apps/website`, using the existing Astro page/content/component split. Extend `src/content/pages/home.ts`, reuse current section components where possible, and add only the smallest missing homepage composition pieces required by Spec 216.
|
||
|
||
## Complexity Tracking
|
||
|
||
None.
|
||
|
||
## Proportionality Review
|
||
|
||
- **Current operator problem**: The homepage currently explains route jobs and product seriousness only partially, which makes the public first-read weaker than the product truth already available elsewhere on the site.
|
||
- **Existing structure is insufficient because**: The current homepage composition lacks an explicit outcome section, uses the capability section for information architecture rather than product model explanation, keeps trust too implicit, and surfaces progress only as a CTA target instead of a real signal.
|
||
- **Narrowest correct implementation**: Recompose the existing homepage route with one explicit outcome block, grouped capability clusters, a dedicated trust block, and a real changelog teaser while reusing current content modules, section primitives, and collection truth.
|
||
- **Ownership cost created**: Ongoing maintenance of a slightly richer `home.ts` content shape, homepage section ordering, and a few additional browser assertions.
|
||
- **Alternative intentionally rejected**: A generic section registry or CMS-like homepage builder was rejected because only one homepage route needs this contract now, and the existing Astro content model is already sufficient.
|
||
- **Release truth**: Current-release truth
|
||
|
||
## Phase 0 — Outline & Research (complete)
|
||
|
||
- Output: `specs/216-homepage-structure/research.md`
|
||
- Key decisions captured:
|
||
- Keep the homepage local to the static Astro website and preserve runtime separation from `apps/platform`.
|
||
- Extend the current content-driven homepage model instead of adding a new section framework.
|
||
- Reorder the homepage into the explicit Spec 216 narrative flow while preserving optional supporting context only where it helps clarity.
|
||
- Reuse existing Trust page truth and changelog collection data for homepage proof signals.
|
||
- Validate via the current website build proof plus focused Playwright smoke coverage.
|
||
|
||
## Phase 1 — Design & Contracts (complete)
|
||
|
||
### Data model
|
||
|
||
- Output: `specs/216-homepage-structure/data-model.md`
|
||
- Model remains file- and route-based. No database schema changes are required.
|
||
|
||
### Public homepage contract
|
||
|
||
- Output: `specs/216-homepage-structure/contracts/homepage-surface.openapi.yaml`
|
||
- Contract captures the homepage route plus the required onward routes (`/product`, `/trust`, `/changelog`, `/contact`) and the structural rules the homepage must satisfy.
|
||
|
||
### Quickstart
|
||
|
||
- Output: `specs/216-homepage-structure/quickstart.md`
|
||
- Quickstart covers local development, homepage verification points, build proof, and smoke-test execution.
|
||
|
||
### Agent context update
|
||
|
||
- Completed via `.specify/scripts/bash/update-agent-context.sh copilot` after plan artifacts were generated.
|
||
|
||
### Constitution re-check (post-design)
|
||
|
||
- ✅ The plan remains website-only and static, with no platform-runtime coupling.
|
||
- ✅ No new persistence, state machines, background operations, or auth flows are introduced.
|
||
- ✅ The chosen shape reuses existing Astro content modules and components instead of adding speculative abstraction.
|
||
- ✅ Validation remains cheap, local, and aligned with the current website smoke harness.
|
||
|
||
## Phase 2 — Implementation Plan (next)
|
||
|
||
### Story 1 (P1): Understand the Product Fast
|
||
|
||
- Update `apps/website/src/pages/index.astro` so the homepage first-read flow establishes the hero, product-near visual, outcome framing, and clear CTA hierarchy required for immediate product understanding.
|
||
- Preserve the current header, footer, and existing hero shell while leaving clean insertion points for the later capability, trust, and progress blocks owned by the following story slices.
|
||
- Extend the homepage hero so it supports a product-near visual and optional bounded trust subclaims when they are factually supportable and traceable to `/trust`.
|
||
- Keep any optional supporting context, such as the ecosystem strip, only if it reinforces clarity instead of displacing the first-read story.
|
||
- Tests / validation:
|
||
- Extend `apps/website/tests/smoke/home-product.spec.ts` to assert the required blocks are visible in order, that the hero exposes a product-near visual, and that CTA hierarchy remains singular and clear.
|
||
- Re-run `corepack pnpm build:website`.
|
||
|
||
### Story 2 (P2): Evaluate Product Model and Trust Without a Feature Wall
|
||
|
||
- Refactor the remaining mid-page homepage content in `apps/website/src/content/pages/home.ts` so it explains grouped product capabilities instead of homepage information architecture.
|
||
- Add the smallest missing homepage content objects needed for grouped capability clusters, explicit trust proof, and dated progress signaling.
|
||
- Reuse `trust.ts` and the `TrustGrid` section to place a dedicated homepage trust block ahead of the final CTA.
|
||
- Add a homepage progress teaser backed by the changelog collection or a thin helper derived from it, keeping the signal dated and routed to `/changelog`.
|
||
- Ensure homepage claims remain bounded and traceable to `/trust`, with no fake proof systems or unsupported badges.
|
||
- Tests / validation:
|
||
- Update existing homepage smoke assertions for revised headings, grouped capability clusters, explicit trust visibility, and dated progress signaling.
|
||
- Verify the hero still exposes exactly one primary CTA and one secondary deepening CTA.
|
||
|
||
### Story 3 (P3): Move Into the Right Next Route
|
||
|
||
- Align homepage CTA targets, secondary deep links, and optional-route suppression so the homepage routes into Product, Trust, Changelog, and Contact without competing conversion paths.
|
||
- Tighten header and footer discoverability, including footer/legal reachability, while keeping optional unpublished routes de-emphasized.
|
||
- Finalize homepage onward routing in `apps/website/src/pages/index.astro` while preserving mobile readability and narrow-screen discoverability.
|
||
- Tests / validation:
|
||
- Expand smoke coverage to assert visible reachability of `/product`, `/trust`, `/changelog`, and `/contact`, plus footer/legal discoverability on desktop and narrow mobile widths.
|
||
- Add explicit narrow-screen assertions so the homepage stays readable and does not leak optional unpublished routes.
|
||
|
||
---
|
||
|
||
## Close-Out Notes
|
||
|
||
**Implementation completed**: All 19 tasks (T001–T019) across 6 phases.
|
||
|
||
### Build & Test Proof
|
||
|
||
- `corepack pnpm build:website`: ✅ 12 pages built, 0 errors
|
||
- `cd apps/website && corepack pnpm exec playwright test`: ✅ 20/20 tests pass
|
||
|
||
### Summary of Changes
|
||
|
||
**New files**:
|
||
- `apps/website/src/components/sections/OutcomeSection.astro` — outcome framing block
|
||
- `apps/website/src/components/sections/ProgressTeaser.astro` — dated progress signals
|
||
- `apps/website/src/components/sections/CapabilityGrid.astro` — grouped capability clusters
|
||
- `apps/website/src/lib/changelog.ts` — shared helper for recent changelog entries
|
||
- `apps/website/public/images/hero-product-visual.svg` — product-near hero visual
|
||
|
||
**Modified files**:
|
||
- `apps/website/src/types/site.ts` — 7 new interfaces for Spec 216 section model
|
||
- `apps/website/src/content/pages/home.ts` — full rewrite with Spec 216 content
|
||
- `apps/website/src/pages/index.astro` — full rewrite with new section flow
|
||
- `apps/website/src/components/sections/PageHero.astro` — added productVisual + trustSubclaims support
|
||
- `apps/website/src/components/primitives/Section.astro` — forward rest attributes (data-section)
|
||
- `apps/website/src/components/primitives/Card.astro` — forward rest attributes (data-hero-visual)
|
||
- `apps/website/tests/smoke/home-product.spec.ts` — rewritten for Spec 216 homepage structure
|
||
- `apps/website/tests/smoke/smoke-helpers.ts` — 4 new assertion helpers
|
||
- `apps/website/tests/smoke/visual-foundation-guardrails.spec.ts` — updated CTA labels
|
||
|
||
### Homepage Section Flow (Spec 216)
|
||
|
||
1. **PageHero** — eyebrow, headline, description, primary/secondary CTA, product visual, trust subclaims
|
||
2. **LogoStrip** — ecosystem fit (Microsoft Graph, Entra ID, Intune, Review workflows)
|
||
3. **OutcomeSection** — 3 outcome cards explaining why TenantAtlas matters
|
||
4. **CapabilityGrid** — 4 grouped capability clusters (Backup, Restore, Inventory, Governance)
|
||
5. **TrustGrid** — 3 trust signals with link to /trust
|
||
6. **ProgressTeaser** — dated changelog entries (or fallback link) with link to /changelog
|
||
7. **CTASection** — final CTA: "Request a working session" (primary) + "See the product model" (secondary)
|
||
|
||
### Removed Exports
|
||
|
||
- `homeMetrics`, `homePillars`, `homeProofBlocks` from `home.ts` (replaced by outcome/capability/trust/progress model) |