TenantAtlas/specs/214-website-visual-foundation/tasks.md

Tasks: Website Visual Foundation

Input: Design documents from /specs/214-website-visual-foundation/ Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/website-visual-foundation.contract.yaml

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

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and the browser coverage remains explicit.
• Shared helpers and context defaults stay cheap by default; no backend, auth, or fixture-heavy setup is introduced.
• Planned validation commands cover the website change without pulling in unrelated platform lane cost.
• Any runtime-cost or escalation note stays documented in this feature rather than being deferred implicitly.
• Explicit governance outcome is recorded as document-in-feature for this feature-local fast-feedback validation scope.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare the shared types, metadata hooks, and smoke-test helpers that the visual-foundation refactor will rely on.

• T001 Add page-family and visual-foundation contract types in apps/website/src/types/site.ts
• T002 [P] Add foundation-aware site metadata and CTA/footer configuration hooks in apps/website/src/lib/site.ts and apps/website/src/lib/seo.ts
• T003 [P] Extend shell, CTA-hierarchy, accessibility-baseline, navigation-vs-CTA differentiation, and mobile-navigation smoke helpers in apps/website/tests/smoke/smoke-helpers.ts

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the semantic token layer, shared shell, and reusable layout scaffolds that every user story depends on.

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

• T004 Implement semantic color, typography, spacing, surface, border, radius, shadow, and accessibility-baseline roles in apps/website/src/styles/tokens.css and apps/website/src/styles/global.css
• T005 [P] Refactor the shared document and navigation shell to use foundation surfaces in apps/website/src/layouts/BaseLayout.astro, apps/website/src/components/layout/PageShell.astro, apps/website/src/components/layout/Navbar.astro, and apps/website/src/components/layout/Footer.astro
• T006 [P] Refactor shared width and spacing primitives in apps/website/src/components/primitives/Container.astro, apps/website/src/components/primitives/Section.astro, apps/website/src/components/primitives/SectionHeader.astro, apps/website/src/components/primitives/Stack.astro, apps/website/src/components/primitives/Cluster.astro, and apps/website/src/components/primitives/Grid.astro
• T007 [P] Align reusable section scaffolds to the foundation contract, including progressive-disclosure and CTA-emphasis layering, in apps/website/src/components/sections/PageHero.astro, apps/website/src/components/sections/CTASection.astro, apps/website/src/components/sections/FeatureGrid.astro, apps/website/src/components/sections/TrustGrid.astro, and apps/website/src/components/sections/LogoStrip.astro

Checkpoint: Semantic tokens, shared shell, and section scaffolds are in place. User-story work can now proceed.

---

Phase 3: User Story 1 - Build New Pages From a Stable Foundation (Priority: P1) 🎯 MVP

Goal: Make Home and Product the proof that new website pages can be assembled from the shared foundation instead of page-local design decisions.

Independent Test: Visit Home and Product and verify the smoke suite proves a shared heading hierarchy, consistent section rhythm, clear CTA weighting, focus visibility, readable contrast, non-color-only semantics, and navigation-vs-CTA differentiation without bespoke foundational styling.

Tests for User Story 1

Note

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

• T008 [US1] Update landing/product smoke coverage for heading hierarchy, CTA emphasis, focus visibility, readable contrast, non-color-only semantics, and navigation-vs-CTA differentiation in apps/website/tests/smoke/home-product.spec.ts

Implementation for User Story 1

• T009 [P] [US1] Align core content primitives to the shared foundation in apps/website/src/components/content/Eyebrow.astro, apps/website/src/components/content/Headline.astro, apps/website/src/components/content/Lead.astro, apps/website/src/components/content/FeatureItem.astro, apps/website/src/components/content/Callout.astro, and apps/website/src/components/content/Metric.astro
• T010 [P] [US1] Update landing and product content modules for semantic sections and CTA rhythm in apps/website/src/content/pages/home.ts and apps/website/src/content/pages/product.ts
• T011 [US1] Apply the stable foundation to apps/website/src/pages/index.astro and apps/website/src/pages/product.astro

Checkpoint: Home and Product work as the MVP proof that new pages can be built from the shared foundation.

---

Phase 4: User Story 2 - Review Multiple Page Types Against One Visual Language (Priority: P1)

Goal: Make trust, legal, audience-fit, and long-form routes read as the same website rather than as separate visual modes.

Independent Test: Visit representative landing, trust/legal, and content-heavy routes and verify the smoke suite proves consistent shell behavior, section rhythm, progressive-disclosure layering, and CTA placement across those page families.

Tests for User Story 2

Note

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

• T012 [US2] Update landing, trust/legal, and content-heavy smoke coverage for heading hierarchy, section rhythm, surface consistency, shell/navigation stability, progressive-disclosure layering, CTA placement, and mobile-navigation usability in apps/website/tests/smoke/home-product.spec.ts, apps/website/tests/smoke/solutions-trust-integrations.spec.ts, and apps/website/tests/smoke/contact-legal.spec.ts

Implementation for User Story 2

• T013 [P] [US2] Align audience, trust, and long-form content primitives in apps/website/src/components/content/AudienceRow.astro, apps/website/src/components/content/TrustPrincipleCard.astro, apps/website/src/components/content/IntegrationBadge.astro, apps/website/src/components/content/ContactPanel.astro, apps/website/src/components/content/DemoPrompt.astro, and apps/website/src/components/content/RichText.astro
• T014 [P] [US2] Normalize trust/legal/content-heavy page content modules for semantic structure, disclosure layers, and CTA rhythm without changing final copy or IA in apps/website/src/content/pages/solutions.ts, apps/website/src/content/pages/security-trust.ts, apps/website/src/content/pages/integrations.ts, apps/website/src/content/pages/contact.ts, apps/website/src/content/pages/legal.ts, apps/website/src/content/pages/privacy.ts, and apps/website/src/content/pages/terms.ts
• T015 [US2] Apply page-family consistency rules and route-composition changes needed to prove the foundation, without redefining final IA or copy, in apps/website/src/pages/solutions.astro, apps/website/src/pages/security-trust.astro, apps/website/src/pages/integrations.astro, apps/website/src/pages/contact.astro, apps/website/src/pages/legal.astro, apps/website/src/pages/privacy.astro, and apps/website/src/pages/terms.astro

Checkpoint: Landing, trust/legal, and long-form routes can be reviewed against the same visual language.

---

Phase 5: User Story 3 - Use shadcn/ui Without Inheriting a Template Look (Priority: P2)

Goal: Encode the website-local component contract so future shadcn/ui-inspired work routes through local primitives instead of uncontrolled library defaults.

Independent Test: Run a dedicated smoke check that proves representative pages still expose consistent CTA hierarchy, shared input/button behavior, and mobile navigation while relying on local foundation-backed primitives.

Tests for User Story 3

Note

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

• T016 [US3] Write component-guardrail smoke coverage for focus states, input semantics, non-color-only semantics, navigation-vs-CTA differentiation, CTA hierarchy, and consistent rendered component behavior in apps/website/tests/smoke/visual-foundation-guardrails.spec.ts

Implementation for User Story 3

• T017 [P] [US3] Encode local foundation-backed component variants in apps/website/src/components/primitives/Button.astro, apps/website/src/components/primitives/Badge.astro, apps/website/src/components/primitives/Card.astro, apps/website/src/components/primitives/Input.astro, and apps/website/src/components/primitives/Textarea.astro
• T018 [P] [US3] Route CTA and low-emphasis action patterns through shared wrappers in apps/website/src/components/content/PrimaryCTA.astro, apps/website/src/components/content/SecondaryCTA.astro, apps/website/src/components/layout/Navbar.astro, and apps/website/src/components/layout/Footer.astro
• T019 [US3] Remove remaining page-local template-style escapes from apps/website/src/components/sections/PageHero.astro, apps/website/src/components/sections/CTASection.astro, apps/website/src/pages/index.astro, apps/website/src/pages/product.astro, apps/website/src/pages/security-trust.astro, and apps/website/src/pages/contact.astro

Checkpoint: shadcn/ui-style patterns are now constrained by the local website foundation instead of shaping the website by default.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Run the narrowest validation proof and confirm website-working-contract compatibility after all stories land.

• T020 [P] Record fast-feedback lane validation, including contrast, focus visibility, non-color-only semantics, navigation-vs-CTA differentiation, and progressive-disclosure proof, and run the required proof commands from specs/214-website-visual-foundation/plan.md and specs/214-website-visual-foundation/quickstart.md
• T021 Verify website working-contract compatibility and static-first runtime constraints, including no new React/runtime coupling or unnecessary client hydration, in package.json, apps/website/package.json, apps/website/astro.config.mjs, and apps/website/playwright.config.ts

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): Starts immediately.
• Foundational (Phase 2): Depends on Setup and blocks all user stories.
• User Story 1 (Phase 3): Depends on Foundational only.
• User Story 2 (Phase 4): Depends on Foundational only.
• User Story 3 (Phase 5): Depends on Foundational only and can proceed in parallel with US1 or US2 once the shared shell and primitives are stable.
• Polish (Phase 6): Depends on all targeted user stories being complete.

User Story Dependencies

• US1: No dependency on other user stories; this is the MVP slice.
• US2: No dependency on US1, but it reuses the same shared shell, token, and primitive foundation.
• US3: No dependency on US1 or US2 for implementation, but its guardrail checks should run against representative routes after the shared foundation is stable.

Within Each User Story

• Write the browser smoke test first and verify it fails.
• Align shared content or primitive components before changing page content modules.
• Update page content modules before completing route composition.
• Finish route-level integration before moving to the next story’s polish or validation work.

---

Parallel Opportunities

• T002 and T003 can run in parallel after T001 is scoped.
• T005, T006, and T007 can run in parallel after T004 starts.
• In US1, T009 and T010 can run in parallel before T011.
• In US2, T013 and T014 can run in parallel before T015.
• In US3, T017 and T018 can run in parallel before T019.
• T020 and T021 can run in parallel during final polish.

---

Parallel Example: User Story 2

# Launch trust/legal/content-heavy preparation together:
Task: "T013 [US2] Align audience, trust, and long-form content primitives"
Task: "T014 [US2] Update trust/legal/content-heavy page content modules"

# Then complete route integration:
Task: "T015 [US2] Apply page-family consistency rules to the affected routes"

---

Implementation Strategy

MVP First

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Run corepack pnpm build:website and the updated home-product smoke proof.
5. Demo the MVP on Home and Product.

Incremental Delivery

1. Setup + Foundational establish the reusable website-local foundation.
2. US1 proves new page construction from the shared rules.
3. US2 aligns representative page families under one visual language.
4. US3 hardens the local primitive contract so future shadcn/ui-inspired work cannot drift back to template defaults.
5. Polish runs the narrowest proof commands and verifies website-working-contract compatibility.

Suggested MVP Scope

• Deliver through User Story 1 if the smallest initial release is needed.
• Add User Story 2 next for page-family consistency across trust/legal/content-heavy surfaces.
• Finish with User Story 3 to lock future component work behind the local foundation contract.

Validation Notes

• 2026-04-19: corepack pnpm build:website passed from repo root.
• 2026-04-19: corepack pnpm --filter @tenantatlas/website exec playwright test passed with 10 smoke tests.
• Focus visibility proof is covered by the updated landing-page smoke flow (Skip to content keyboard focus plus CTA hierarchy checks).
• Non-color-only semantics, navigation-vs-CTA differentiation, progressive-disclosure layers, badge/button/input hooks, and content-heavy route consistency are exercised through the updated smoke helpers and representative route specs.
• Website working-contract review confirmed @tenantatlas/website, WEBSITE_PORT, Astro static output, and Playwright web-server flow remain intact with no React, Radix, or platform runtime coupling introduced.