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

Implementation Plan: Website Visual Foundation

Branch: 214-website-visual-foundation | Date: 2026-04-18 | Spec: specs/214-website-visual-foundation/spec.md Input: Feature specification from specs/214-website-visual-foundation/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

• Keep apps/website fully local to the website track and preserve the existing workspace contracts defined by the website working contract.
• Build the visual foundation on the current Astro 6 + Tailwind CSS v4 stack by formalizing semantic token roles, typography hierarchy, spacing rules, surface logic, interaction semantics, and page-level consistency rules.
• Keep Astro-native primitives as the canonical implementation surface and treat shadcn/ui as an adaptation/reference contract rather than introducing React plus official shadcn/ui as a new required runtime layer.
• Apply the foundation across representative page families already present in apps/website so landing, trust/legal, and content-heavy surfaces read as one controlled enterprise website instead of locally styled variants.

Technical Context

Language/Version: Astro 6.0.0 templates + TypeScript 5.9 strict
Primary Dependencies: Astro 6, Tailwind CSS v4 via @tailwindcss/vite, Astro content collections, local Astro component primitives, Playwright browser smoke tests
Storage: Static filesystem content, styles, assets, and content collections under apps/website/src and apps/website/public; no database
Testing: Root build proof via corepack pnpm build:website plus Playwright browser smoke coverage in apps/website/tests/smoke
Validation Lanes: fast-feedback Target Platform: Static public website for modern desktop and mobile browsers
Project Type: Web (standalone Astro app inside the monorepo)
Performance Goals: Preserve static HTML output for public routes, keep reading/navigation flows zero-hydration by default, and keep UI refinements within a low-JS, accessibility-first posture
Constraints: Preserve @tenantatlas/website, WEBSITE_PORT, and root dev:website / build:website workflows; do not introduce platform runtime coupling; do not promote website semantics into a shared cross-surface design system; keep any shadcn/ui usage adapted to website-owned tokens and primitives
Scale/Scope: 9 published public routes, existing layout/primitives/sections/content directories, and one website-local visual foundation spanning landing, trust/legal, and content-heavy page families

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first / Graph contract / deterministic capabilities / RBAC-UX / Filament surface rules: N/A for this feature because all planned work stays inside apps/website and introduces no /admin, /admin/t/{tenant}/..., or /system runtime behavior.
• Read/write separation: Pass. The feature changes public presentation and component composition only; it introduces no website write workflow, backend form handler, queue, or remote call path.
• Workspace isolation: Pass. The website remains runtime-independent from apps/platform, and the plan preserves the explicit website working contract boundaries.
• Data minimization: Pass. The feature only reorganizes or extends public styles, content composition, and component semantics; it introduces no tenant data, secrets, auth state, or operational records.
• Test governance (TEST-GOV-001): Pass. Validation remains in fast-feedback using the existing website build and local Playwright smoke suite, with no database, auth, provider, or heavy-suite defaults.
• Proportionality / no premature abstraction: Pass. The plan extends the current Astro/Tailwind foundation with a narrow website-local semantic layer instead of introducing React, a CMS, or a shared website-platform design system.
• Persisted truth / new state: Pass. No database schema, persisted entity, queue lifecycle, or new application state family is introduced.
• UI semantics / few layers: Pass. The added semantics stay limited to design tokens, primitive contracts, and page-composition rules for the website, not a reusable cross-app interpretation framework.
• Website working contract: Pass. The plan keeps changes local to apps/website except for preserving existing root workflow compatibility, and it introduces no new API, auth, DTO, or shared-package coupling to apps/platform.

Status: ✅ No constitution violations for this feature. The implementation remains website-only, static-first, and scoped to the existing Astro website track.

Test Governance Check

Fill for any runtime-changing or test-affecting feature. Docs-only or template-only work may state concise N/A or none.

• Test purpose / classification by changed surface: Browser smoke coverage for representative public page families plus root static build proof
• Affected validation lanes: fast-feedback
• Why this lane mix is the narrowest sufficient proof: The feature changes runtime website rendering, styling, and composition but stays within a static Astro site. Build proof catches asset and route breakage; a focused Playwright smoke suite catches browser-visible regressions in navigation, CTA visibility, representative content surfaces, and mobile usability without introducing backend or heavy end-to-end cost.
• Narrowest proving command(s): corepack pnpm build:website and cd apps/website && corepack pnpm exec playwright test
• Fixture / helper / factory / seed / context cost risks: none; public website pages require no database, auth, tenant, or provider setup
• Expensive defaults or shared helper growth introduced?: no; any browser assertions remain local to apps/website/tests/smoke
• Heavy-family additions, promotions, or visibility changes: none
• Closing validation and reviewer handoff: Re-run the website build and smoke suite after token, primitive, or page-family changes. Reviewers should verify that Home, trust/legal, and another content-heavy route still load cleanly, navigation and footer links remain reachable, CTA hierarchy stays visible, and no unnecessary client framework hydration is introduced.
• Budget / baseline / trend follow-up: none beyond the existing small website smoke-suite runtime
• Review-stop questions: Does validation remain fast-feedback only? Did any change introduce hidden React/runtime coupling, broaden the smoke suite beyond representative website flows, or create new platform-facing contracts?
• Escalation path: document-in-feature
• Why no dedicated follow-up spec is needed: This feature’s validation scope is tightly bounded to the website’s local rendering and navigation behavior. A separate test-governance spec is only needed if the website later gains interactive workflows, API-backed forms, or broader browser coverage.

Project Structure

Documentation (this feature)

specs/214-website-visual-foundation/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── website-visual-foundation.contract.yaml
└── tasks.md

Source Code (repository root)

apps/website/
├── astro.config.mjs
├── package.json
├── playwright.config.ts
├── public/
├── src/
│   ├── components/
│   │   ├── layout/              # Navbar, Footer, PageShell
│   │   ├── primitives/          # Container, Section, Button, Badge, Card, Input, Textarea, Grid, Stack
│   │   ├── sections/            # PageHero, FeatureGrid, TrustGrid, CTASection, LogoStrip
│   │   └── content/             # Eyebrow, Headline, Lead, Callout, Metric, audience/trust helpers
│   ├── content/                 # Route content and future content collections
│   ├── layouts/
│   │   └── BaseLayout.astro
│   ├── lib/                     # Site metadata, SEO, and helper config
│   ├── pages/                   # Published public routes
│   ├── styles/
│   │   ├── global.css
│   │   └── tokens.css
│   └── types/
└── tests/
    └── smoke/

Structure Decision: Keep the existing website structure and formalize the design foundation inside the current styles, primitives, sections, content, and layout layers. The implementation should encode semantic design rules in the Astro-native foundation already present instead of introducing a second component stack.

Complexity Tracking

None.

Proportionality Review

• Current operator problem: Website contributors and reviewers lack a canonical, website-local visual contract, so styling decisions drift across pages and primitives and dilute enterprise trust.
• Existing structure is insufficient because: The current site already has tokens, gradients, rounded cards, and reusable primitives, but those choices are only partially codified. They do not yet define the semantic token roles, page-family rules, or shadcn/ui usage boundaries needed to prevent future drift.
• Narrowest correct implementation: Extend the current Astro/Tailwind foundation with explicit semantic token mapping, primitive contracts, and page-consistency rules, then apply those rules to representative routes. Do not add a new client framework, platform coupling, or shared website-platform design system.
• Ownership cost created: Ongoing maintenance of token semantics, shared primitives, and a small browser smoke suite that protects representative public routes.
• Alternative intentionally rejected: Continuing page-local styling was rejected because it preserves drift; full React plus official shadcn/ui was rejected because it adds unnecessary runtime and maintenance cost; a shared cross-surface design system was rejected because the feature is intentionally website-only.
• Release truth: Current-release truth for apps/website

Phase 0 — Outline & Research (complete)

• Output: specs/214-website-visual-foundation/research.md
• Key decisions captured:
  • Preserve the website working contract and keep all visual-language work local to apps/website.
  • Build the foundation on semantic token layering in Tailwind CSS v4 and CSS custom properties rather than page-local utility drift.
  • Keep Astro-native primitives as the canonical implementation surface and adapt any shadcn/ui usage to that layer instead of adding React as a new runtime dependency.
  • Use representative page families already in the repo to drive the foundation: landing, trust/legal, and content-heavy surfaces.
  • Validate with root build proof plus the existing Playwright smoke suite for representative public routes.

Phase 1 — Design & Contracts (complete)

Data model

• Output: specs/214-website-visual-foundation/data-model.md
• No database schema changes are required; the model is a website-local design contract expressed through token roles, primitive contracts, and page-family consistency rules.

Design contract

• Output: specs/214-website-visual-foundation/contracts/website-visual-foundation.contract.yaml
• This feature has no HTTP or API contract changes. The contract artifact captures the website-local visual foundation rules that implementation must satisfy.

Quickstart

• Output: specs/214-website-visual-foundation/quickstart.md
• Quickstart covers local development, representative implementation order, and the required validation commands.

Agent context update

• Completed via .specify/scripts/bash/update-agent-context.sh copilot so the Copilot context reflects the current website stack and this feature’s planning artifacts.

Constitution re-check (post-design)

• ✅ The design remains fully local to apps/website and preserves the website working contract.
• ✅ No database truth, backend form handling, queueing, or platform-side runtime concern is introduced.
• ✅ The semantic layer remains narrow: tokens, primitives, and page-family rules only.
• ✅ Validation remains cheap, representative, and website-specific.

Phase 2 — Implementation Plan (next)

Story 1 (P1): Semantic token and rule foundation

• Normalize the existing palette and CSS variables into an explicit semantic role model for colors, surfaces, borders, shadows, radius, and typography.
• Encode the spacing model and section rhythm into the current Astro foundation so Container, Section, SectionHeader, Card, Button, Input, and Textarea expose one canonical visual language.
• Keep the site static and light-first, with focus states, contrast, and mobile readability treated as foundation rules rather than page-local cleanup.
• Tests / validation:
  • Confirm the website still builds via corepack pnpm build:website.
  • Re-run smoke coverage for Home and Product, explicitly proving focus visibility, readable contrast, non-color-only semantics, and clear navigation-vs-CTA differentiation.

Story 2 (P1): Representative page-family alignment

• Apply the foundation consistently across representative page families already present in the app: landing (/ or /product), trust/legal (/security-trust, /privacy, /terms), and other content-heavy routes.
• Reduce style drift in hero, section intro, callout, stat, and card usage so CTA emphasis, section spacing, surface elevation, and progressive-disclosure layering behave consistently across routes.
• Ensure the footer, navigation shell, and CTA placement logic match the foundation’s page-level rules.
• Tests / validation:
  • Extend or adjust browser smoke coverage to assert representative headings, CTA visibility, shell/navigation stability, and progressive-disclosure layering across at least three page families.
  • Verify mobile navigation remains usable.

Story 3 (P2): shadcn/ui usage contract in code

• Encode shadcn/ui usage constraints through local primitives and variant APIs so future component work is forced back through website-owned tokens, surfaces, and interaction semantics.
• Keep Astro-native wrappers as the primary authoring path; any borrowed shadcn/ui pattern must be translated into local primitives instead of exposing uncontrolled library defaults.
• Avoid introducing React, Radix, or extra framework/runtime weight unless a later explicit spec proves a concrete need.
• Tests / validation:
  • Re-run build and smoke coverage after primitive API changes.
  • Review representative components to ensure no page-local style override bypasses the shared token and primitive model.