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

# Feature Specification: Website Visual Foundation

**Feature Branch**: `214-website-visual-foundation`  
**Created**: 2026-04-18  
**Status**: Draft  
**Input**: User description: "Create a website-only design foundation and visual language for apps/website, covering visual direction, design tokens, typography, spacing, surface rules, shadcn/ui usage, semantic website components, and explicit boundaries that exclude apps/platform."

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: `apps/website` risks drifting into page-by-page styling decisions that weaken enterprise trust, reduce consistency, and make later page work slower and harder to review.
- **Today's failure**: New website sections currently invite ad hoc choices for typography, spacing, surfaces, CTA weight, and default shadcn/ui styling, which can produce a polished page in isolation but an inconsistent website overall.
- **User-visible improvement**: Website pages present a calmer, more consistent, and more trustworthy enterprise SaaS visual language across landing, trust, legal, and content-heavy surfaces.
- **Smallest enterprise-capable version**: Define a website-local visual foundation that covers tone, token roles, typography, spacing, surface behavior, interaction semantics, semantic page primitives, and shadcn/ui usage constraints.
- **Explicit non-goals**: Filament theming, any visual contract for `apps/platform`, a shared cross-surface design system, detailed page IA, final website copy, full implementation of every component, and logo or brand redesign.
- **Permanent complexity imported**: A website-local token vocabulary, typography hierarchy, spacing model, surface taxonomy, interaction semantics, component primitive set, and review rules for shadcn/ui usage.
- **Why now**: The website is early enough that a foundation can still prevent drift before more pages and components normalize inconsistent patterns.
- **Why not local**: Local page fixes or isolated component tweaks cannot solve cross-page consistency, cannot stop template-driven styling drift, and do not give reviewers a stable baseline for future work.
- **Approval class**: Core Enterprise
- **Red flags triggered**: New semantic UI layer; risk of overspecifying aesthetics; risk of accidental bleed into platform visual decisions.
- **Score**: Nutzen: 3 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 11/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace
- **Primary Routes**: All public-facing pages in `apps/website`, with immediate relevance to landing, trust, legal/privacy, content-heavy, and CTA/contact surfaces.
- **Data Ownership**: Website-owned visual rules, semantic primitives, and review criteria only; no tenant-owned records, platform data, or shared persistence.
- **RBAC**: None. This feature applies to public website surfaces and introduces no authorization model.

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: yes
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: yes, but only within `apps/website`
- **Current operator problem**: Website builders and reviewers do not have a shared enterprise-grade baseline for visual decisions, so every new page risks re-litigating foundational styling choices.
- **Existing structure is insufficient because**: Default component libraries and page-local styling do not encode the intended product tone, do not constrain cross-page consistency, and do not protect `apps/platform` from accidental visual coupling.
- **Narrowest correct implementation**: A website-only foundation spec that defines rules and semantics without creating a shared design system, platform obligations, or a full component implementation backlog.
- **Ownership cost**: Future website work must stay aligned with the foundation, and reviewers must enforce the token and primitive model instead of allowing page-local exceptions to accumulate.
- **Alternative intentionally rejected**: Styling pages one by one or accepting default shadcn/ui aesthetics was rejected because both approaches optimize local speed at the cost of long-term coherence and trust.
- **Release truth**: Current-release truth for `apps/website`; this is not future-platform preparation and must not be used to imply a cross-surface contract.

## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Runtime website rendering, styling, and composition change inside `apps/website` with browser smoke coverage and static build proof.
- **Validation lane(s)**: fast-feedback
- **Why this classification and these lanes are sufficient**: This feature changes executable website presentation, shared primitives, and route composition, but it remains a static Astro surface with no backend writes, no auth, no database setup, and no platform runtime coupling. Root build proof plus focused Playwright smoke coverage is the narrowest honest proof.
- **New or expanded test families**: Focused Playwright browser smoke coverage in `apps/website/tests/smoke` for representative landing, trust/legal, content-heavy, and component-guardrail flows.
- **Fixture / helper cost impact**: low; smoke helpers may expand slightly, but no database, auth, tenant, or provider setup is required.
- **Heavy-family visibility / justification**: none; validation remains in fast-feedback only.
- **Reviewer handoff**: Reviewers should confirm that representative public routes still load cleanly, shell/navigation/footer behavior remains stable, CTA hierarchy and progressive disclosure stay readable, accessibility-baseline rules remain visible, and no unnecessary client-framework or platform coupling is introduced.
- **Budget / baseline / trend impact**: none beyond the small existing website smoke-suite cost.
- **Escalation needed**: document-in-feature
- **Planned validation commands**: `corepack pnpm build:website` and `cd apps/website && corepack pnpm exec playwright test`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Build new website pages from a stable foundation (Priority: P1)

A website contributor can create a new public page without inventing baseline rules for hierarchy, spacing, surfaces, and CTA emphasis.

**Why this priority**: Preventing visual drift at the point of creation is the core value of the feature and the fastest way to improve long-term quality.

**Independent Test**: Review a proposed new page and confirm that its headings, section rhythm, surfaces, CTAs, and content groupings can all be mapped to named foundation rules without adding bespoke foundational decisions.

**Acceptance Scenarios**:

1. **Given** a contributor starts a new page in `apps/website`, **When** they choose typography, spacing, surface treatment, and CTA hierarchy, **Then** each choice can be traced to a defined token role or semantic primitive.
2. **Given** a contributor proposes a new section or card treatment, **When** an existing foundation primitive already covers the need, **Then** no new foundational visual rule is required.

---

### User Story 2 - Review multiple page types against one visual language (Priority: P1)

A product or design reviewer can judge consistency across multiple website page types using one shared website-only standard.

**Why this priority**: The foundation only creates leverage if it works across more than one hero page and remains stable on trust, legal, and content-heavy surfaces.

**Independent Test**: Compare representative landing, trust/legal, and content-heavy page concepts and verify that they share the same heading logic, spacing rhythm, surface model, and CTA weighting rules.

**Acceptance Scenarios**:

1. **Given** a landing page and a trust-oriented page, **When** they are reviewed together, **Then** both can be evaluated against the same typography, surface, and CTA rules without page-specific exceptions.
2. **Given** a content-heavy page such as privacy, terms, or integrations, **When** it is reviewed against the foundation, **Then** the page still reads as part of the same website rather than as a separate visual mode.

---

### User Story 3 - Use shadcn/ui without inheriting a template look (Priority: P2)

A website component builder can use shadcn/ui as a building block while keeping the website's own visual language and semantic constraints in control.

**Why this priority**: shadcn/ui is useful for speed, but uncontrolled defaults would quickly reintroduce inconsistency and generic template aesthetics.

**Independent Test**: Evaluate a proposed shadcn/ui-based component and confirm that its tokens, emphasis, borders, radius, and interaction states are governed by the website foundation rather than by library defaults.

**Acceptance Scenarios**:

1. **Given** a builder selects a shadcn/ui primitive for website use, **When** they adapt it, **Then** the component must inherit website-defined tokens and semantics instead of preserving its default look unmodified.
2. **Given** a local override bypasses shared token or primitive rules, **When** the component is reviewed, **Then** the override is rejected as non-compliant with the foundation.

### Edge Cases

- A page is text-heavy rather than hero-led and still needs the same visual language to feel deliberate and trustworthy.
- A page contains multiple potential CTAs and must still maintain one clear action hierarchy rather than several equally loud buttons.
- Status or accent colors are available but must not become decorative shortcuts that dilute semantic clarity.
- Cards and elevated surfaces must stay useful on long-form content pages instead of turning every block into a visually noisy container.
- Future website work must not interpret this foundation as approval to theme Filament or create a shared design contract with `apps/platform`.
- Early website forms, if introduced, must use the same input height, border, focus, and error-state logic instead of one-off marketing styling.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no Microsoft Graph calls, no queueing, no long-running operations, no authorization changes, and no Filament surface changes. Its contract is explicitly local to `apps/website` and must not create obligations for `apps/platform`.

**Constitution alignment (UI-SEM-001 / LAYER-001 / BLOAT-001):** This feature intentionally introduces a website-local semantic visual layer because page-local styling and default library decisions are insufficient to create a coherent enterprise website. The layer is scoped narrowly to public website semantics, replaces ad hoc page-by-page foundation decisions, and must not expand into a platform-wide design system without a separate spec.

**Implementation boundary:** Any implementation under this specification MUST preserve the existing website working contract by keeping `@tenantatlas/website`, `WEBSITE_PORT`, and the root `dev:website` / `build:website` workflows intact, and it MUST NOT introduce runtime or package coupling to `apps/platform`.

### Functional Requirements

- **FR-001**: The specification MUST define a visual direction for `apps/website` that is explicitly local to the website and explicitly excludes `apps/platform`, Filament theming, and any shared cross-surface design contract.
- **FR-002**: The visual direction MUST describe the website as clear, calm, precise, trustworthy, modern, and high-quality, and MUST explicitly reject playful, neon-heavy, glass-heavy, over-animated, loud, or generic startup-template aesthetics.
- **FR-003**: The foundation MUST define a color-role model that includes, at minimum, `background`, `foreground`, `muted`, `muted-foreground`, `card`, `card-foreground`, `border`, `input`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `accent`, `accent-foreground`, `success`, `warning`, `destructive`, and `info`.
- **FR-004**: The color-role rules MUST state that neutrals carry most of the interface, that primary color is used sparingly, that status colors remain semantic rather than decorative, and that contrast supports readability on both short hero screens and longer content pages.
- **FR-005**: The foundation MUST define a typography hierarchy covering display or hero heading, page heading, section heading, card heading, body text, small text, eyebrow or label text, and UI label or helper text.
- **FR-006**: Typography rules MUST require calm, precise headings, readable body copy for long-form pages, and sufficient contrast for small UI text across landing, trust, and content-oriented page types.
- **FR-007**: The foundation MUST define a repeatable spacing model for page spacing, section spacing, and component spacing, including rules for section rhythm, content density shifts, and avoidance of page-by-page optical tweaking without a system reference.
- **FR-008**: The foundation MUST define a surface language covering page background, default content surface, card surface, elevated surface, muted or inset surface, and highlighted or emphasis surface, with rules that make surface levels structurally useful rather than decorative.
- **FR-009**: The foundation MUST define a small radius scale and clear border and shadow rules, including border-first clarity for cards and inputs, restrained shadow usage, and a rejection of decorative float effects.
- **FR-010**: The foundation MUST define semantic interaction rules for buttons, links, and inputs, including button hierarchy, CTA weighting, text-vs-button link behavior, shared focus logic, shared border logic, and clear error states for any website form surfaces.
- **FR-011**: The foundation MUST define a website semantic primitive model covering navigation primitives, hero primitives, section primitives, content-grouping primitives, CTA primitives, and trust primitives.
- **FR-012**: The foundation MUST define usage rules for shadcn/ui that allow it as an implementation building block, require adaptation to website tokens and semantics, and forbid uncontrolled use of default component styling or local overrides disconnected from shared tokens.
- **FR-013**: The foundation MUST define page-level consistency rules for content width, heading hierarchy, section rhythm, CTA placement logic, card behavior, callout behavior, footer structure, and link-emphasis rules across `apps/website`.
- **FR-014**: The foundation MUST include a tone-to-UI alignment statement that anchors the website in an enterprise and MSP-credible posture: precise instead of hype-driven, believable instead of flashy, structured instead of loud, and modern but controlled.
- **FR-015**: The foundation MUST include an accessibility baseline covering readable text sizing, sufficient contrast, distinct focus states, non-color-only semantics, durable mobile readability, and clear differentiation between navigation and CTA elements.
- **FR-016**: The foundation MUST define progressive-disclosure behavior so that information density, CTA emphasis, and surface emphasis reveal complexity in layers instead of presenting all signals at once.
- **FR-017**: The specification MUST state its required deliverables: design token set, typography hierarchy, color-role mapping, spacing principles, surface/border/radius/shadow rules, button/link/input semantics, section/card/callout primitives, shadcn/ui usage constraints, and page consistency rules.
- **FR-018**: The foundation MUST be reviewable against at least three page families: landing pages, trust or legal pages, and content-heavy pages.
- **FR-019**: No requirement in this specification MAY be interpreted as mandatory visual alignment work for `apps/platform`, Filament, or a shared website-platform design system.
- **FR-020**: Implementation work under this specification MUST preserve the website working contract by retaining `@tenantatlas/website`, `WEBSITE_PORT`, and the root `dev:website` / `build:website` workflows, and it MUST NOT introduce runtime coupling or shared-package obligations for `apps/platform`.

#### Out of Scope

- Filament theming
- `apps/platform`
- Cross-surface visual contracts
- A shared design system for website and platform
- Final page IA or page-by-page content architecture beyond route-level composition changes strictly required to apply and prove the foundation
- Final website copy or content inventory beyond semantic, hierarchy, disclosure, or CTA-weighting adjustments strictly required to apply and prove the foundation
- Full implementation of every component described by the foundation
- Logo or brand redesign

#### Assumptions

- `apps/website` continues to serve public marketing, trust, legal, and content-oriented page types rather than operator-facing product UI.
- The first implementation phase should prefer a small number of repeatable primitives over a wide component catalog.
- Enterprise trust and clarity matter more than maximal visual novelty for this website surface.

### Key Entities *(include if feature involves data)*

- **Visual Direction**: The high-level statement of intended tone, trust posture, and disallowed aesthetic patterns for the website.
- **Design Token Set**: The named color, spacing, radius, border, and shadow roles that anchor repeatable visual decisions.
- **Typography Hierarchy**: The ordered set of text roles that governs hero, page, section, card, body, and supporting text usage.
- **Surface Model**: The set of page and component surface levels used to organize content and emphasis without decorative overload.
- **Semantic Primitive Set**: The named website building blocks for navigation, hero, sections, groupings, CTAs, and trust-oriented content.
- **shadcn/ui Usage Contract**: The rules that determine when and how shadcn/ui primitives can be adapted for website use.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In review of representative landing, trust/legal, and content-heavy page exemplars, 100% of headings, CTAs, cards, callouts, and input states can be mapped to named foundation rules without inventing new foundational styling rules.
- **SC-002**: Reviewers can assess the same three representative page families without raising unresolved foundational questions about typography hierarchy, spacing rhythm, surface usage, or CTA weighting.
- **SC-003**: 100% of library-derived website components proposed for the initial implementation phase can be justified as adaptations of the defined token and primitive model rather than uncontrolled default styles.
- **SC-004**: The specification contains zero requirements that obligate visual changes to `apps/platform`, Filament, or a shared cross-surface design system.
- **SC-005**: At least one primary CTA hierarchy and one low-emphasis CTA pattern are defined clearly enough that reviewers can classify CTA weight consistently across representative website pages.