TenantAtlas/specs/213-website-foundation-v0/plan.md

# Implementation Plan: Initial Website Foundation & v0 Product Site

**Branch**: `213-website-foundation-v0` | **Date**: 2026-04-18 | **Spec**: `specs/213-website-foundation-v0/spec.md`
**Input**: Feature specification from `specs/213-website-foundation-v0/spec.md`

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

## Summary

- Keep `apps/website` as a fully static Astro 6 app and preserve its runtime separation from `apps/platform`.
- Introduce explicit TypeScript and Tailwind CSS v4, but implement the UI layer as custom shadcn-inspired Astro primitives instead of adding React plus official shadcn/ui.
- Ship a reusable public-site foundation with global layout, navigation, footer, seven core surfaces plus Privacy and Terms, SEO basics, and a lightweight browser-smoke validation path.

## Technical Context

**Language/Version**: Astro 6.0.0 templates + TypeScript 5.x (explicit setup in `apps/website`)  
**Primary Dependencies**: Astro 6, Tailwind CSS v4, custom Astro component primitives (shadcn-inspired), lightweight Playwright browser smoke tests  
**Storage**: Static filesystem content, styles, and assets under `apps/website/src` and `apps/website/public`; no database  
**Testing**: Root build proof via `corepack pnpm build:website` plus Playwright browser smoke coverage for public routes  
**Validation Lanes**: fast-feedback
**Target Platform**: Static public website for modern desktop/mobile browsers
**Project Type**: Web (standalone Astro app in a pnpm monorepo)  
**Performance Goals**: Static HTML for all core routes, zero required framework hydration for reading/navigation flows, minimal client JS reserved for purposeful interactions only  
**Constraints**: Preserve `@tenantatlas/website`, `WEBSITE_PORT`, root workspace scripts, and `apps/*` contracts; avoid platform auth/session/API coupling; ship one polished primary theme; publish only substantiated trust and integration claims  
**Scale/Scope**: 7 core public surfaces plus Privacy and Terms as published legal routes, shared layout/content/conversion/trust primitives, and a future-ready structure for blog/docs/changelog without live rollout in v0

## 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 implementation stays inside `apps/website` and introduces no `/admin`, `/admin/t/{tenant}/...`, or `/system` runtime changes.
- Read/write separation: Pass. The feature is a public, static product site. Contact / Demo remains a static conversion surface in v0 and does not introduce a product-app write workflow.
- Workspace isolation: Pass. The website remains runtime-independent from `apps/platform`; no shared auth, session, tenant data, or implicit API dependency is introduced.
- Data minimization: Pass. Only public content, styles, metadata, and assets are authored; no tenant payloads, credentials, or operational records are stored.
- Test governance (TEST-GOV-001): Pass. Validation stays in `fast-feedback` with static build proof and lightweight browser smoke coverage; no DB/auth/provider fixtures or heavy-suite defaults are added.
- Proportionality / no premature abstraction: Pass. The plan adopts a small Astro/Tailwind primitive set instead of React + official shadcn/ui, a CMS, or a broader front-end framework.
- Persisted truth / new state: Pass. No database entities, queued work, run lifecycle, or new status families are introduced.
- UI semantics / few layers: Pass. Shared layout/content/conversion/trust primitives map directly to the website narrative without a presentation meta-framework.

Status: ✅ No constitution violations for this feature. The website remains public, static, repo-owned, and separate from platform runtime concerns.

## 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 public routes, navigation reachability, and layout stability; static build proof for artifact generation
- **Affected validation lanes**: fast-feedback
- **Why this lane mix is the narrowest sufficient proof**: The feature changes only a static Astro site. Build proof alone verifies output generation, while a tiny browser smoke suite is the smallest layer that can catch broken routes, broken navigation, and browser-visible regressions 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 pages do not require database, auth, provider, tenant, or workspace setup
- **Expensive defaults or shared helper growth introduced?**: no; any Playwright setup stays local to `apps/website`
- **Heavy-family additions, promotions, or visibility changes**: none
- **Closing validation and reviewer handoff**: Re-run the website build and smoke suite after page or layout changes. Reviewers should verify that core routes load, primary/footer navigation has no dead ends, the site stays mobile-usable, and no framework hydration is introduced without explicit justification.
- **Budget / baseline / trend follow-up**: none beyond tracking the small runtime cost of the website smoke suite inside this feature
- **Review-stop questions**: Does the proof stay in fast-feedback? Did any change introduce backend fixtures or hidden framework coupling? Is the smoke suite still small and route-focused?
- **Escalation path**: document-in-feature
- **Why no dedicated follow-up spec is needed**: The validation surface is tightly bounded to this feature’s public pages. A follow-up spec is only needed if the website later grows interactive workflows, broader content tooling, or cross-app coupling.

## Project Structure

### Documentation (this feature)

```text
specs/213-website-foundation-v0/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```

### Source Code (repository root)

```text
apps/website/
├── astro.config.mjs
├── package.json
├── public/
├── src/
│   ├── components/
│   │   ├── layout/              # Navbar, Footer, page shell wrappers
│   │   ├── primitives/          # Container, Section, Button, Badge, Card, Input, Textarea
│   │   ├── sections/            # PageHero, FeatureGrid, TrustGrid, CTASection, LogoStrip
│   │   └── content/             # Audience rows, evidence callouts, legal prose helpers
│   ├── layouts/
│   │   └── BaseLayout.astro
│   ├── lib/                     # Navigation, SEO, metadata, content helpers
│   ├── pages/
│   │   ├── index.astro
│   │   ├── product.astro
│   │   ├── solutions.astro
│   │   ├── security-trust.astro
│   │   ├── integrations.astro
│   │   ├── contact.astro
│   │   ├── legal.astro
│   │   ├── privacy.astro
│   │   ├── sitemap.xml.ts
│   │   └── terms.astro
│   ├── styles/
│   │   ├── global.css
│   │   └── tokens.css           # Tailwind v4 theme tokens / bridge layer
│   ├── content/                 # Future-ready content collections for docs/blog/changelog
│   └── types/                   # Content and component prop types
└── tests/
    └── smoke/                   # Lightweight Playwright browser smoke coverage
```

**Structure Decision**: Keep the website fully isolated in `apps/website`. Use Astro pages plus a small internal design-system layer (`layout`, `primitives`, `sections`, `content`) and local browser smoke tests. Prepare a future `src/content/` and helper layer for later docs/blog/changelog expansion without shipping those sections in v0.

## Complexity Tracking

> **Fill when Constitution Check has violations that must be justified OR when BLOAT-001 is triggered by new persistence, abstractions, states, or semantic frameworks.**

None.

## Proportionality Review

> **Fill when the feature introduces a new enum/status family, DTO/presenter/envelope, persisted entity/table/artifact, interface/contract/registry/resolver, taxonomy/classification system, or cross-domain UI framework.**

- **Current operator problem**: Prospects and internal teams lack a credible public site that explains the product, trust model, and contact path without depending on the platform UI or ad hoc landing-page copy.
- **Existing structure is insufficient because**: The current Astro app only contains a single placeholder-style page, handwritten global CSS, and no reusable page system for navigation, legal pages, audience storytelling, or future content expansion.
- **Narrowest correct implementation**: A small Astro-native design-system layer backed by Tailwind CSS v4 and explicit TypeScript, with no React requirement and no CMS or runtime platform coupling.
- **Ownership cost created**: Ongoing maintenance of public copy, shared website primitives, Tailwind tokens, and a tiny local browser smoke suite.
- **Alternative intentionally rejected**: React + official shadcn/ui was rejected because it adds unnecessary client framework weight and maintenance cost for a static trust-first site; a single-page copy refresh was rejected because it would not establish a reusable v0 foundation.
- **Release truth**: Current-release truth

## Phase 0 — Outline & Research (complete)

- Output: `specs/213-website-foundation-v0/research.md`
- Key decisions captured:
  - Keep Astro 6 static and runtime-independent from `apps/platform`.
  - Add explicit TypeScript and Tailwind CSS v4 using the CSS-first Tailwind v4 model.
  - Use custom shadcn-inspired Astro primitives instead of React + official shadcn/ui.
  - Keep the Contact / Demo surface static in v0 and avoid introducing an Astro API/contact backend in this feature.
  - Validate with root build proof plus a small Playwright browser smoke suite.

## Phase 1 — Design & Contracts (complete)

### Data model

- Output: `specs/213-website-foundation-v0/data-model.md`
- No database schema changes are required; the model is file- and route-based.

### Public site contracts

- Output: `specs/213-website-foundation-v0/contracts/public-site.openapi.yaml`
- Contract captures the required public GET routes and their HTML response expectations.

### Quickstart

- Output: `specs/213-website-foundation-v0/quickstart.md`
- Quickstart covers local development, build validation, and browser smoke execution.

### Agent context update

- Completed via `.specify/scripts/bash/update-agent-context.sh copilot` so the Copilot context reflects the website stack additions.

### Constitution re-check (post-design)

- ✅ Runtime separation remains intact: no platform auth/session/API coupling is introduced.
- ✅ No new persisted truth, state machines, or background operations are introduced.
- ✅ The chosen UI layer is the narrowest correct implementation for v0 and avoids premature React/framework abstraction.
- ✅ Validation remains cheap, local, and website-specific.

## Phase 2 — Implementation Plan (next)

### Story 1 (P1): Foundation and shared shell

- Add explicit TypeScript setup to `apps/website` and install Tailwind CSS v4 using the CSS-first configuration model.
- Introduce site metadata, navigation, footer configuration, and shared layout primitives (`Container`, `Section`, `SectionHeader`, `Button`, `Badge`, `Card`, `Input`, `Textarea`, `Navbar`, `Footer`, `PageHero`).
- Preserve the existing calm, enterprise-appropriate visual direction while shifting styling from page-local CSS toward reusable tokens and utilities.
- Tests / validation:
  - Confirm the site still builds via `corepack pnpm build:website`.
  - Add browser smoke coverage for Home plus one interior route.

### Story 2 (P1/P2): Core page shells and narrative system

- Build Home, Product, Solutions, Security & Trust, Integrations, Contact, Legal, Privacy, and Terms using shared `sections/` components (`FeatureGrid`, `TrustGrid`, `CTASection`, `LogoStrip`, audience-specific rows, evidence callouts).
- Ensure each core page exposes page purpose, clear hierarchy, semantic metadata, and visible next-step CTA.
- Keep Solutions separate from Product capabilities and keep Security & Trust limited to substantiated claims.
- Tests / validation:
  - Extend browser smoke coverage to all published core routes.
  - Assert primary and footer navigation reachability.

### Story 3 (P3): Delivery hardening and future-ready structure

- Add SEO and discovery basics (page titles, descriptions, Open Graph baseline, robots, explicit sitemap output, canonical metadata).
- Add a future-ready content helper layer and route organization for later docs/blog/changelog expansion without publishing those sections in v0.
- Ensure the Legal surface carries any required jurisdiction-specific public legal notice through the Legal hub or a linked dedicated notice page before launch.
- Keep contact handling static and repo-owned in this feature; document any later external form or scheduling integration as a follow-up decision rather than coupling it into the website foundation.
- Tests / validation:
  - Finish Playwright smoke checks for mobile navigation, CTA reachability, and absence of dead-end routes.
  - Re-verify root workspace scripts and package contracts remain intact.