TenantAtlas/specs/218-homepage-hero/tasks.md

Tasks: Website Homepage Hero

Input: Design documents from /specs/218-homepage-hero/
Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/homepage-hero.openapi.yaml

Tests: Browser smoke coverage and the root website build proof are required for this runtime-changing website feature.

Test Governance Checklist

• Lane assignment stays Browser in fast-feedback, which is the narrowest sufficient proof for this homepage-hero-only change.
• New or changed tests stay in the existing website smoke suite instead of widening into a heavier family.
• Shared helpers stay cheap by default; no backend, auth, database, or provider fixtures are introduced.
• Planned validation commands remain the feature-local website build proof and focused Playwright smoke coverage.
• No additional budget, baseline, or escalation path is required beyond document-in-feature for this slice.

Phase 1: Setup (Shared Infrastructure)

Purpose: Establish stable hero-specific render hooks before story work begins.

• T001 Add stable homepage-hero element markers and an explicit hero root hook in apps/website/src/components/sections/PageHero.astro

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the shared hero contract and smoke helpers that every story slice depends on.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T002 [P] Extend reusable hero smoke assertions for semantic structure, CTA hierarchy, product-near visual presence, and mobile ordering in apps/website/tests/smoke/smoke-helpers.ts
• T003 [P] Tighten the shared hero content object for CTA pair, product visual metadata, and trust-subclaim availability in apps/website/src/content/pages/home.ts

Checkpoint: Homepage-hero foundations are ready. User-story work can proceed.

---

Phase 3: User Story 1 - Understand the Product from the First Screen (Priority: P1) 🎯 MVP

Goal: Make the homepage hero explain what TenantAtlas is, why it matters, and what the next step is in the first reading pass.

Independent Test: Visit / and confirm the hero shows category context, a precise headline, supporting copy, and exactly one dominant primary CTA plus one lower-emphasis secondary CTA without opening any other route.

Tests for User Story 1

Note

: Write this test first and confirm it fails before implementing the story.

• T004 [P] [US1] Write failing hero-clarity smoke assertions for category context, headline and supporting-copy separation, and one CTA pair in apps/website/tests/smoke/home-product.spec.ts

Implementation for User Story 1

• T005 [P] [US1] Refine the hero eyebrow, headline, supporting copy, and CTA labels to meet Spec 218 positioning rules in apps/website/src/content/pages/home.ts
• T006 [US1] Render the explicit hero text core and CTA cluster in apps/website/src/components/sections/PageHero.astro

Checkpoint: The homepage hero delivers the MVP story of product clarity, buyer relevance, and one clear next step.

---

Phase 4: User Story 2 - Establish Credibility Without Overclaiming (Priority: P2)

Goal: Show product reality and bounded early trust inside the hero without collapsing into badge theater or generic SaaS visuals.

Independent Test: Visit / and confirm the hero visual reads as product-near, trust cues stay concise and supportable, and the hero feels credible without requiring the full Trust page.

Tests for User Story 2

Note

: Write this test first and confirm it fails before implementing the story.

• T007 [P] [US2] Write failing hero smoke assertions for product-near visual truth and bounded trust subclaims in apps/website/tests/smoke/home-product.spec.ts

Implementation for User Story 2

• T008 [P] [US2] Tighten the hero visual asset, alt text, and bounded trust-subclaim copy in apps/website/public/images/hero-product-visual.svg and apps/website/src/content/pages/home.ts
• T009 [US2] Refine hero visual and trust-subclaim presentation so credibility cues stay secondary and supportable in apps/website/src/components/sections/PageHero.astro

Checkpoint: The hero shows believable product reality and early trust without fake proof systems or inflated claims.

---

Phase 5: User Story 3 - Preserve Correct Next-Step Routing on Desktop and Mobile (Priority: P3)

Goal: Keep the hero meaning order, CTA visibility, and route intent intact across narrow and wide screens.

Independent Test: Visit / on a narrow viewport and confirm the hero preserves headline and copy first, keeps the CTA pair visible, keeps the product-near visual visible, and routes into the intended hero destinations.

Tests for User Story 3

Note

: Write this test first and confirm it fails before implementing the story.

• T010 [P] [US3] Write failing hero smoke assertions for narrow-screen meaning order and hero route reachability in apps/website/tests/smoke/home-product.spec.ts

Implementation for User Story 3

• T011 [P] [US3] Tighten the hero responsive composition so the CTA pair and product-near visual remain visible on narrow screens in apps/website/src/components/sections/PageHero.astro
• T012 [US3] Finalize the hero CTA routing and secondary deepening intent in apps/website/src/content/pages/home.ts

Checkpoint: The hero preserves correct mobile meaning order and intentional next-step routing without hiding the CTA or product reality.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Validate proof commands, tighten anti-pattern compliance, and capture close-out notes.

• T013 [P] Review hero copy, trust wording, and anti-pattern compliance in apps/website/src/content/pages/home.ts, apps/website/src/content/pages/trust.ts, and apps/website/public/images/hero-product-visual.svg
• T014 [P] Run corepack pnpm build:website from package.json and verify hero proof steps in specs/218-homepage-hero/quickstart.md
• T015 [P] Run cd apps/website && corepack pnpm exec playwright test tests/smoke/home-product.spec.ts against the hero smoke coverage in apps/website/tests/smoke/home-product.spec.ts
• T016 Record the focused hero smoke-coverage close-out and any helper-growth notes in specs/218-homepage-hero/plan.md and specs/218-homepage-hero/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 edits to apps/website/src/components/sections/PageHero.astro, apps/website/src/content/pages/home.ts, and apps/website/tests/smoke/home-product.spec.ts 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 test and content work, and remains independently valuable because it upgrades credibility and product-near truth inside the hero. Shared PageHero.astro work should follow US1.
• User Story 3 (P3): Starts after Foundational for responsive and routing work, and remains independently valuable because it hardens mobile meaning order and hero route intent. Shared PageHero.astro and home.ts work should follow US2.

Within Each User Story

• Write the story-specific browser smoke assertions first and confirm they fail.
• Update content and supporting truth sources before final hero render adjustments in apps/website/src/components/sections/PageHero.astro.
• Treat apps/website/src/components/sections/PageHero.astro, apps/website/src/content/pages/home.ts, and apps/website/tests/smoke/home-product.spec.ts as shared assembly points: helper or asset work may branch, but shared file edits should land sequentially.
• Finish the hero render or content wiring before running the story proof commands.

---

Parallel Opportunities

• T002 and T003 can run in parallel after T001.
• In US1, T004 and T005 can run in parallel before T006.
• In US2, T007 and T008 can run in parallel before T009.
• In US3, T010 and T011 can run in parallel before T012.
• In polish, T013, T014, and T015 can run in parallel before T016.

---

Parallel Example: User Story 1

# After the hero foundations are complete, split the first slice into test + content work:
Task: "T004 [US1] Write failing hero-clarity smoke assertions for category context, headline and supporting-copy separation, and one CTA pair"
Task: "T005 [US1] Refine the hero eyebrow, headline, supporting copy, and CTA labels"

# Then finish the shared hero render:
Task: "T006 [US1] Render the explicit hero text core and CTA cluster"

Parallel Example: User Story 2

# Safe split inside US2 is limited to assertions plus content and asset prep before shared hero render work:
Task: "T007 [US2] Write failing hero smoke assertions for product-near visual truth and bounded trust subclaims"
Task: "T008 [US2] Tighten the hero visual asset, alt text, and bounded trust-subclaim copy"

# Then finish the shared hero presentation work:
Task: "T009 [US2] Refine hero visual and trust-subclaim presentation"

Parallel Example: User Story 3

# Split mobile assertions from responsive render work first:
Task: "T010 [US3] Write failing hero smoke assertions for narrow-screen meaning order and hero route reachability"
Task: "T011 [US3] Tighten the hero responsive composition so the CTA pair and product-near visual remain visible on narrow screens"

# Then finalize route intent in the shared hero content:
Task: "T012 [US3] Finalize the hero CTA routing and secondary deepening intent"

---

Implementation Strategy

MVP First

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Run the website build proof and the homepage hero smoke coverage.
5. Demo the homepage hero MVP with clear product explanation and one dominant next step.

Incremental Delivery

1. Foundations establish stable render hooks, the shared hero data contract, and smoke helpers.
2. US1 locks in immediate product clarity and CTA discipline.
3. US2 upgrades hero credibility through truthful product-near media and bounded trust cues.
4. US3 hardens mobile meaning order and route intent without changing the broader homepage section model.
5. Polish runs the proof commands, validates anti-pattern compliance, 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 visual truth and bounded credibility cues.
• Finish with User Story 3 for deliberate narrow-screen behavior and route integrity.