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.