version: 0.1.0
type: design-foundation
feature: 214-website-visual-foundation
title: Website Visual Foundation Contract
summary: >-
  Website-local visual contract for apps/website. This feature does not add or
  change HTTP/API surfaces; the contract defines the semantic design rules that
  implementation must satisfy.
scope:
  app: apps/website
  includes:
    - visual direction
    - design tokens
    - typography roles
    - spacing rules
    - surface rules
    - interaction semantics
    - semantic website primitives
    - shadcn usage constraints
    - page consistency rules
  excludes:
    - apps/platform
    - Filament theming
    - shared cross-surface design system
    - API contracts
    - logo or brand redesign
visual_direction:
  target_tone:
    - clear
    - calm
    - precise
    - trustworthy
    - modern
    - high-quality
    - operationally serious
  disallowed_traits:
    - playful
    - neon-heavy
    - glass-heavy-by-default
    - over-animated
    - loud
    - generic-startup-template
token_roles:
  color:
    required:
      - background
      - foreground
      - muted
      - muted-foreground
      - card
      - card-foreground
      - border
      - input
      - primary
      - primary-foreground
      - secondary
      - secondary-foreground
      - accent
      - accent-foreground
      - success
      - warning
      - destructive
      - info
    rules:
      - neutrals-carry-most-of-the-surface
      - primary-used-sparingly
      - status-colors-semantic-only
  typography:
    required:
      - display
      - page-heading
      - section-heading
      - card-heading
      - body
      - small
      - eyebrow
      - helper
  spacing:
    required_levels:
      - page
      - section
      - component
  surface:
    required:
      - page-background
      - default-content
      - card
      - elevated
      - muted-inset
      - highlighted
  radius:
    preferred_scale:
      - small
      - medium
      - large
interaction:
  buttons:
    required:
      - primary
      - secondary
      - ghost
    rules:
      - no-multiple-equally-loud-ctas-by-default
      - primary-not-inflationary
  links:
    rules:
      - navigation-vs-inline-intent-must-be-clear
  inputs:
    rules:
      - shared-height-logic
      - shared-border-logic
      - shared-focus-logic
      - clear-error-states
primitives:
  navigation:
    - header
    - nav-links
    - cta-slot
    - mobile-nav
  hero:
    - eyebrow
    - main-headline
    - supporting-copy
    - primary-cta
    - secondary-cta
    - trust-supporting-area
  section:
    - section-wrapper
    - section-intro
    - section-title
    - section-body
    - optional-aside
  grouping:
    - card
    - feature-row
    - comparison-block
    - callout
    - quote-frame
    - logos-bar
    - stat-block
  trust:
    - compliance-callout
    - evidence-block
    - changelog-news-block
    - contact-request-demo-block
shadcn_usage:
  mode: adapted-locally
  allowed:
    - use-as-pattern-reference
    - adapt-into-local-astro-primitives
    - reduce-or-normalize-default-behavior
  forbidden:
    - unreviewed-default-styling-adoption
    - component-library-driven-page-design
    - local-token-bypass-overrides
    - implicit-react-runtime-requirement
page_consistency:
  applies_to:
    - landing-product
    - trust-legal
    - content-heavy
  rules:
    - shared-content-width-strategy
    - shared-heading-hierarchy
    - shared-section-rhythm
    - shared-cta-placement-logic
    - shared-card-and-callout-behavior
    - shared-footer-structure
    - shared-link-emphasis-rules
validation:
  required_commands:
    - corepack pnpm build:website
    - cd apps/website && corepack pnpm exec playwright test
  review_checks:
    - representative-pages-use-shared-foundation
    - no-platform-coupling-introduced
    - no-react-or-radix-required-by-default
    - navigation-and-cta-hierarchy-remain-clear