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

- [X] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
- [X] New or changed tests stay in the smallest honest family, and the browser coverage remains explicit.
- [X] Shared helpers and context defaults stay cheap by default; no backend, auth, or fixture-heavy setup is introduced.
- [X] Planned validation commands cover the website change without pulling in unrelated platform lane cost.
- [X] Any runtime-cost or escalation note stays documented in this feature rather than being deferred implicitly.
- [X] 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.

- [X] T001 Add page-family and visual-foundation contract types in `apps/website/src/types/site.ts`
- [X] 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`
- [X] 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.

- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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.

- [X] 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

- [X] 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`
- [X] 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`
- [X] 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.

- [X] 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

- [X] 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`
- [X] 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`
- [X] 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.

- [X] 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

- [X] 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`
- [X] 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`
- [X] 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.

- [X] 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`
- [X] 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

```bash
# 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.