TenantAtlas/specs/214-website-visual-foundation/data-model.md

# Data Model: Website Visual Foundation

## Overview

This feature introduces no database schema. The model is a website-local design contract expressed through tokens, primitive semantics, and page-family consistency rules inside `apps/website`.

## Entities

### Website Visual Foundation

- **Purpose**: The canonical visual contract for `apps/website`.
- **Key fields**:
  - `scope` (`apps/website` only)
  - `toneKeywords`
  - `disallowedTraits`
  - `pageFamilies`
  - `accessibilityBaseline`
  - `shadcnUsageMode`
- **Relationships**:
  - Owns many `Token Role` entries
  - Owns many `Typography Role` entries
  - Owns many `Spacing Rule` entries
  - Owns many `Surface Rule` entries
  - Owns many `Interaction Contract` entries
  - Owns many `Primitive Contract` entries
  - Owns many `Page Consistency Rule` entries
- **Validation rules**:
  - Must remain explicitly local to `apps/website`
  - Must explicitly exclude `apps/platform`, Filament theming, and shared cross-surface obligations
  - Must define both desired tone and disallowed visual patterns

### Token Role

- **Purpose**: A semantic token used to express color, surface, border, radius, or shadow meaning.
- **Key fields**:
  - `name`
  - `category` (`color`, `surface`, `border`, `radius`, `shadow`)
  - `semanticPurpose`
  - `defaultValueSource`
  - `allowedContexts`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - May be referenced by many `Primitive Contract` entries
  - May be referenced by many `Page Consistency Rule` entries
- **Validation rules**:
  - Required color roles include `background`, `foreground`, `muted`, `muted-foreground`, `card`, `card-foreground`, `border`, `input`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `accent`, `accent-foreground`, `success`, `warning`, `destructive`, and `info`
  - Primaries must be used intentionally and not as the dominant surface color
  - Status roles must remain semantic rather than decorative

### Typography Role

- **Purpose**: A named text role that governs hierarchy and readability.
- **Key fields**:
  - `name`
  - `intent` (`display`, `page`, `section`, `card`, `body`, `small`, `eyebrow`, `helper`)
  - `fontFamily`
  - `weight`
  - `tracking`
  - `lineHeight`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - May be referenced by many `Primitive Contract` entries
  - May be referenced by many `Page Consistency Rule` entries
- **Validation rules**:
  - Required roles include display or hero, page, section, card, body, small, eyebrow or label, and UI label or helper text
  - Body and small text must stay readable on long-form pages
  - Headlines must read as calm and precise rather than aggressive or novelty-first

### Spacing Rule

- **Purpose**: A repeatable spacing decision at page, section, or component level.
- **Key fields**:
  - `level` (`page`, `section`, `component`)
  - `density`
  - `gapStrategy`
  - `maxWidthBehavior`
  - `rhythmIntent`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - May constrain many `Primitive Contract` entries
  - May constrain many `Page Consistency Rule` entries
- **Validation rules**:
  - Must define page spacing, section spacing, and component spacing
  - Must support density shifts between hero-led and text-heavy layouts without abandoning the system
  - Must avoid page-by-page optical tweaking as the default mechanism

### Surface Rule

- **Purpose**: Defines one level of content containment or emphasis.
- **Key fields**:
  - `name` (`page-background`, `default-content`, `card`, `elevated`, `muted-inset`, `highlighted`)
  - `emphasisLevel`
  - `borderBehavior`
  - `shadowBehavior`
  - `intendedUse`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - May be used by many `Primitive Contract` entries
  - May be referenced by many `Page Consistency Rule` entries
- **Validation rules**:
  - Surface differences must communicate structure rather than decoration alone
  - Cards must group meaningful content, not appear arbitrarily as style wrappers
  - Shadows must remain restrained and border-led clarity must stay primary

### Interaction Contract

- **Purpose**: Governs semantic behavior for interactive elements.
- **Key fields**:
  - `elementType` (`button`, `link`, `input`)
  - `variantSet`
  - `focusBehavior`
  - `errorBehavior`
  - `emphasisRules`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - May be used by many `Primitive Contract` entries
- **Validation rules**:
  - Button hierarchy must at least cover `primary`, `secondary`, and low-emphasis or `ghost`
  - Links must distinguish navigation intent from inline/supportive CTA behavior
  - Inputs must share height, border, focus, and error-state logic across the website

### Primitive Contract

- **Purpose**: A reusable website building block that carries semantic and visual rules.
- **Key fields**:
  - `name`
  - `category` (`navigation`, `hero`, `section`, `grouping`, `cta`, `trust`)
  - `backingComponent`
  - `allowedVariants`
  - `requiredTokenRoles`
  - `defaultSpacingRule`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - May reference many `Token Role`, `Typography Role`, `Spacing Rule`, and `Surface Rule` entries
  - May be evaluated by many `Page Consistency Rule` entries
- **Validation rules**:
  - Required primitive groups include navigation, hero, section, content grouping, CTA, and trust primitives
  - Primitive APIs must reinforce the foundation instead of allowing unrestricted local overrides
  - Existing Astro primitives remain the primary implementation targets

### shadcn Usage Policy

- **Purpose**: Defines how `shadcn/ui` concepts may enter the website codebase.
- **Key fields**:
  - `mode` (`adapted-locally`)
  - `allowedUses`
  - `forbiddenUses`
  - `reviewExpectations`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - Constrains many `Primitive Contract` entries
- **Validation rules**:
  - Library patterns must be adapted to website-owned tokens and primitives
  - Uncontrolled default styling must not become the website’s visual language
  - The policy must not implicitly require React or a second component runtime

### Page Consistency Rule

- **Purpose**: A cross-page rule that keeps the website coherent across route types.
- **Key fields**:
  - `pageFamily`
  - `contentWidthStrategy`
  - `headingHierarchy`
  - `sectionRhythm`
  - `ctaPlacementLogic`
  - `footerExpectation`
- **Relationships**:
  - Belongs to `Website Visual Foundation`
  - Applies to many routes in `apps/website/src/pages`
  - References many `Primitive Contract` entries
- **Validation rules**:
  - Must cover at least landing/product, trust/legal, and content-heavy page families
  - Must enforce one recognizable website rhythm across those page families
  - Must prevent pages from inventing competing CTA or surface hierarchies

## Relationship Summary

- `Website Visual Foundation` owns many `Token Role`
- `Website Visual Foundation` owns many `Typography Role`
- `Website Visual Foundation` owns many `Spacing Rule`
- `Website Visual Foundation` owns many `Surface Rule`
- `Website Visual Foundation` owns many `Interaction Contract`
- `Website Visual Foundation` owns many `Primitive Contract`
- `Website Visual Foundation` owns many `Page Consistency Rule`
- `Primitive Contract` references `Token Role`, `Typography Role`, `Spacing Rule`, and `Surface Rule`
- `Page Consistency Rule` evaluates routes through the required `Primitive Contract` set
- `shadcn Usage Policy` constrains how future primitives are authored or adapted

## State / Lifecycle Notes

- No persisted runtime states are introduced.
- The foundation is repo-owned truth: it is expressed through shared styles, primitive APIs, and representative page composition rather than a database or application state machine.
- A primitive or page is compliant when it maps to the defined foundation entities without inventing a competing local visual rule.