198 lines
14 KiB
Markdown
198 lines
14 KiB
Markdown
# 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.
|