Quickstart: Website Visual Foundation

Purpose

This quickstart describes the local workflow for implementing the website-only visual foundation in apps/website.

Start the website from the repo root:

corepack pnpm dev:website

The website must continue to honor the existing WEBSITE_PORT contract.

Implement the feature in this order:

Audit the current token and foundation layer in apps/website/src/styles/tokens.css and apps/website/src/styles/global.css.
Formalize semantic token roles for color, typography, spacing, surfaces, radius, borders, and shadows.
Update the current Astro primitives so shared rules are enforced through component APIs rather than page-local class decisions.
Apply the foundation across representative page families: landing/product, trust/legal, and content-heavy routes.
Encode shadcn/ui usage constraints through local primitives and implementation review rules, without introducing a new required React runtime.
Re-run build and smoke validation.

The implementation must preserve all existing website working-contract guarantees:

keep @tenantatlas/website unchanged
keep WEBSITE_PORT unchanged
keep root dev:website and build:website workflows working
keep all changes local to apps/website unless a deliberate new contract is explicitly introduced
do not introduce platform runtime coupling, shared auth, or shared DTO/API assumptions

Run the website build proof from the repo root:

corepack pnpm build:website

Run the browser smoke suite from the website app:

cd apps/website
corepack pnpm exec playwright test

Reviewers should confirm that:

representative landing, trust/legal, and content-heavy routes still load correctly
heading hierarchy, section rhythm, and CTA weight are visibly consistent across those page families
navigation and footer links remain reachable
focus states and mobile readability remain intact
no uncontrolled local override bypasses the shared token and primitive model
no React, Radix, or platform coupling is introduced without a separate explicit decision