206 lines
12 KiB
Markdown
206 lines
12 KiB
Markdown
# Tasks: Website Homepage Structure & Section Model
|
|
|
|
**Input**: Design documents from `/specs/216-homepage-structure/`
|
|
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `quickstart.md`, `contracts/homepage-surface.openapi.yaml`
|
|
|
|
**Tests**: Browser smoke coverage and the root website build proof are required for this runtime-changing website feature.
|
|
|
|
## Test Governance Checklist
|
|
|
|
- [X] Lane assignment stays `Browser` in `fast-feedback`, which is the narrowest sufficient proof for this homepage-only change.
|
|
- [X] New or changed tests stay in the existing website smoke suite instead of widening into a heavier family.
|
|
- [X] Shared helpers stay cheap by default; no backend, auth, database, or provider fixtures are introduced.
|
|
- [X] Planned validation commands remain the feature-local website build proof and Playwright smoke suite.
|
|
- [X] No additional budget, baseline, or escalation path is required beyond `document-in-feature` for this slice.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Establish the homepage-specific content/type surface before story work begins.
|
|
|
|
- [X] T001 Add homepage-specific section content types for hero visuals, optional trust subclaims, outcome framing, capability clusters, trust signals, and progress teasers in `apps/website/src/types/site.ts`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Add the reusable homepage helpers and scaffolds that every story slice depends on.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T002 [P] Create reusable homepage section scaffolds in `apps/website/src/components/sections/OutcomeSection.astro` and `apps/website/src/components/sections/ProgressTeaser.astro`
|
|
- [X] T003 [P] Add a shared recent-changelog helper for homepage progress signals in `apps/website/src/lib/changelog.ts`
|
|
- [X] T004 [P] Extend homepage smoke helpers for ordered section, product-near visual, mobile viewport, and CTA assertions in `apps/website/tests/smoke/smoke-helpers.ts`
|
|
|
|
**Checkpoint**: Homepage foundations are ready. User-story work can proceed.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Understand the Product Fast (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make the homepage explain what TenantAtlas is, why it matters, and what the next step is within the first reading pass.
|
|
|
|
**Independent Test**: Visit `/` and confirm the hero, outcome framing, and CTA hierarchy make the product category, buyer relevance, and next step understandable without opening any other route.
|
|
|
|
### Tests for User Story 1
|
|
|
|
> **NOTE**: Write this test first and confirm it fails before implementing the story.
|
|
|
|
- [X] T005 [P] [US1] Write failing homepage smoke assertions for hero clarity, product-near visual presence, outcome framing, and one dominant CTA hierarchy in `apps/website/tests/smoke/home-product.spec.ts`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T006 [P] [US1] Add Spec 216 hero content, product-near visual data, optional bounded trust subclaims, and outcome blocks in `apps/website/src/content/pages/home.ts`
|
|
- [X] T007 [US1] Implement the hero-to-outcome homepage flow and hero visual rendering in `apps/website/src/pages/index.astro` and `apps/website/src/components/sections/PageHero.astro`
|
|
|
|
**Checkpoint**: The homepage delivers the MVP story of product clarity, buyer relevance, and one clear next step.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Evaluate Product Model and Trust Without a Feature Wall (Priority: P2)
|
|
|
|
**Goal**: Turn the homepage middle section into a grouped product model with explicit trust and visible progress instead of route-job cards.
|
|
|
|
**Independent Test**: Visit `/` and confirm the homepage shows grouped capability coverage, an explicit trust block, and a dated progress signal before the final CTA.
|
|
|
|
### Tests for User Story 2
|
|
|
|
> **NOTE**: Write this test first and confirm it fails before implementing the story.
|
|
|
|
- [X] T008 [P] [US2] Write failing homepage smoke assertions for grouped capability clusters, explicit trust visibility, and pre-CTA progress signaling in `apps/website/tests/smoke/home-product.spec.ts` and `apps/website/tests/smoke/changelog-core-ia.spec.ts`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T009 [P] [US2] Replace route-job homepage cards with grouped capability and trust/progress content data in `apps/website/src/content/pages/home.ts` and `apps/website/src/content/pages/trust.ts`
|
|
- [X] T010 [US2] Render the grouped capability model and explicit trust block on the homepage in `apps/website/src/pages/index.astro` and `apps/website/src/components/sections/TrustGrid.astro`
|
|
- [X] T011 [US2] Use the shared changelog helper to wire a dated homepage progress teaser in `apps/website/src/components/sections/ProgressTeaser.astro` and `apps/website/src/pages/index.astro`
|
|
|
|
**Checkpoint**: The homepage explains the connected product model, shows explicit trust, and proves visible product movement.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Move Into the Right Next Route (Priority: P3)
|
|
|
|
**Goal**: Make Product, Trust, Changelog, Contact, and legal follow-through obvious from the homepage without multiple competing conversion paths.
|
|
|
|
**Independent Test**: Start on `/` and confirm the homepage routes clearly into `/product`, `/trust`, `/changelog`, and `/contact`, while footer/legal links remain discoverable and optional unpublished routes stay de-emphasized.
|
|
|
|
### Tests for User Story 3
|
|
|
|
> **NOTE**: Write this test first and confirm it fails before implementing the story.
|
|
|
|
- [X] T012 [P] [US3] Write failing homepage smoke assertions for Product, Trust, Changelog, Contact, footer/legal discoverability, and narrow-screen/mobile visibility in `apps/website/tests/smoke/home-product.spec.ts` and `apps/website/tests/smoke/contact-legal.spec.ts`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T013 [P] [US3] Align homepage CTA targets, secondary deep links, and optional-route suppression in `apps/website/src/content/pages/home.ts` and `apps/website/src/lib/site.ts`
|
|
- [X] T014 [P] [US3] Tighten header and footer route discoverability for the homepage journey on desktop and narrow screens in `apps/website/src/components/layout/Navbar.astro` and `apps/website/src/components/layout/Footer.astro`
|
|
- [X] T015 [US3] Finalize homepage onward routing to `/product`, `/trust`, `/changelog`, and `/contact` in `apps/website/src/pages/index.astro`
|
|
|
|
**Checkpoint**: The homepage routes qualified visitors into the right next page without dead ends or competing primary actions.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Validate proof commands, tighten claim wording, and capture close-out notes.
|
|
|
|
- [X] T016 [P] Review homepage proof and trust wording against bounded-claim rules in `apps/website/src/content/pages/home.ts`, `apps/website/src/content/pages/trust.ts`, and `apps/website/src/content/pages/changelog.ts`
|
|
- [X] T017 [P] Run `corepack pnpm build:website` from `package.json` and confirm homepage proof expectations in `specs/216-homepage-structure/quickstart.md`
|
|
- [X] T018 [P] Run `cd apps/website && corepack pnpm exec playwright test` against `apps/website/tests/smoke/home-product.spec.ts`, `apps/website/tests/smoke/changelog-core-ia.spec.ts`, and `apps/website/tests/smoke/contact-legal.spec.ts`
|
|
- [X] T019 Record the homepage smoke-coverage close-out and verification notes in `specs/216-homepage-structure/plan.md` and `specs/216-homepage-structure/quickstart.md`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: Starts immediately.
|
|
- **Foundational (Phase 2)**: Depends on Setup and blocks all user stories.
|
|
- **User Stories (Phases 3-5)**: Depend on Foundational. They remain independently testable, but shared homepage assembly in `apps/website/src/pages/index.astro` should land sequentially in story order.
|
|
- **Polish (Phase 6)**: Depends on all desired user stories being complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Starts after Foundational and is the MVP slice.
|
|
- **User Story 2 (P2)**: Starts after Foundational for content and helper work, and remains independently valuable because it upgrades the homepage product-model and proof layer. Its shared `index.astro` assembly should follow US1.
|
|
- **User Story 3 (P3)**: Starts after Foundational for routing and shell work, and remains independently valuable because it sharpens onward routing and CTA clarity from the homepage. Its shared `index.astro` assembly should follow US2.
|
|
|
|
### Within Each User Story
|
|
|
|
- Write the story-specific browser smoke assertions first and confirm they fail.
|
|
- Update content modules and supporting helpers before final route composition in `apps/website/src/pages/index.astro`.
|
|
- Treat `apps/website/src/pages/index.astro` as a shared assembly point: content/helper work may branch, but homepage route composition should land sequentially.
|
|
- Finish the homepage route wiring before running the story proof commands.
|
|
|
|
---
|
|
|
|
## Parallel Opportunities
|
|
|
|
- `T002`, `T003`, and `T004` can run in parallel after `T001`.
|
|
- In US1, `T005` and `T006` can run in parallel before `T007`.
|
|
- In US2, `T008` and `T009` can run in parallel before `T010`; `T011` follows the shared homepage assembly work.
|
|
- In US3, `T013` and `T014` can run in parallel before `T015`.
|
|
- `T016`, `T017`, and `T018` can run in parallel during polish before `T019`.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# After the foundations are complete, split the first slice into test + content work:
|
|
Task: "T005 [US1] Write failing homepage smoke assertions for hero clarity, outcome framing, and one dominant CTA hierarchy"
|
|
Task: "T006 [US1] Add Spec 216 hero and outcome content blocks"
|
|
|
|
# Then assemble the homepage route:
|
|
Task: "T007 [US1] Implement the hero-to-outcome homepage flow"
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Safe split inside US2 is limited to assertions plus content prep before homepage assembly:
|
|
Task: "T008 [US2] Write failing homepage smoke assertions for grouped capability clusters, explicit trust visibility, and pre-CTA progress signaling"
|
|
Task: "T009 [US2] Replace route-job homepage cards with grouped capability and trust/progress content data"
|
|
|
|
# Then complete the shared homepage assembly sequentially:
|
|
Task: "T010 [US2] Render the grouped capability model and explicit trust block on the homepage"
|
|
Task: "T011 [US2] Use the shared changelog helper to wire a dated homepage progress teaser"
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Split route-target and shell-discoverability work once the routing assertions exist:
|
|
Task: "T013 [US3] Align homepage CTA targets, secondary deep links, and optional-route suppression"
|
|
Task: "T014 [US3] Tighten header and footer route discoverability for the homepage journey"
|
|
|
|
# Then finish the homepage route wiring:
|
|
Task: "T015 [US3] Finalize homepage onward routing to /product, /trust, /changelog, and /contact"
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First
|
|
|
|
1. Complete Phase 1: Setup.
|
|
2. Complete Phase 2: Foundational.
|
|
3. Complete Phase 3: User Story 1.
|
|
4. Run the homepage build proof and US1 browser smoke coverage.
|
|
5. Demo the homepage MVP with clear product explanation and one dominant next step.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Foundations create the reusable homepage scaffolds, changelog helper, and smoke assertions.
|
|
2. US1 establishes immediate product clarity and CTA discipline.
|
|
3. US2 upgrades the homepage middle narrative into grouped product model, trust, and progress proof.
|
|
4. US3 sharpens onward routing and discoverability for Product, Trust, Changelog, Contact, and legal follow-through.
|
|
5. Polish runs both proof commands, validates wording, and records close-out notes before merge.
|
|
|
|
### Suggested MVP Scope
|
|
|
|
- Deliver through **User Story 1** for the smallest independently valuable slice.
|
|
- Add **User Story 2** next for stronger product-model and trust proof.
|
|
- Finish with **User Story 3** for fully deliberate onward routing from the homepage. |