---
schema: "https://creativeintelligencecompany.com/schemas/design-contract-family.v1.schema.json"
version: "0.2.0"
name: "Voet Design Contract"
description: "Beautiful football truth on a never-lie data floor."
colors:
  posture: "monochrome+semantic"
  light:
    background: "oklch(0.9702 0 0)"
    foreground: "oklch(0.145 0 0)"
    card: "oklch(0.9911 0 0)"
    raised: "oklch(0.145 0 0 / 5.5%)"
    hairline: "oklch(0.145 0 0 / 8%)"
  dark:
    background: "oklch(0.13 0 0)"
    foreground: "oklch(0.93 0 0)"
    card: "oklch(0.175 0 0)"
    raised: "oklch(1 0 0 / 6%)"
    hairline: "oklch(1 0 0 / 9%)"
  semantic:
    liveLight: "oklch(0.55 0.23 25)"
    liveDark: "oklch(0.66 0.22 25)"
    winLight: "oklch(0.55 0.15 150)"
    winDark: "oklch(0.74 0.16 150)"
    drawLight: "oklch(0.55 0 0)"
    drawDark: "oklch(0.7 0 0)"
    lossLight: "oklch(0.6 0.13 27)"
    lossDark: "oklch(0.68 0.16 27)"
    homeLight: "oklch(0.45 0 0)"
    homeDark: "oklch(0.62 0 0)"
    awayLight: "oklch(0.6 0 0)"
    awayDark: "oklch(0.5 0 0)"
typography:
  body:
    fontFamily: "Geist Sans, system-ui, sans-serif"
    fontWeight: 350
    letterSpacing: "-0.01em"
  displayH1:
    fontFamily: "Geist Sans, system-ui, sans-serif"
    fontWeight: 900
    fontSize: "clamp(1.75rem, 1.3rem + 1.8vw, 2.5rem)"
    lineHeight: 1.02
    letterSpacing: "-0.04em"
  technical:
    fontFamily: "Iosevka Term, monospace"
  score:
    fontFamily: "Geist Sans, system-ui, sans-serif"
    fontWeight: 900
    letterSpacing: "-0.04em"
    fontVariantNumeric: "tabular-nums lining-nums"
  pixel:
    fontFamily: "Geist Pixel Square or Geist Pixel Circle, monospace"
    usage: "Voet-owned hand-pixel moments only"
layout:
  dense:
    rowY: "0.4375rem"
    padding: "0.625rem"
    gap: "0.5rem"
  spacious:
    rowY: "0.875rem"
    padding: "1.25rem"
    gap: "1rem"
  hierarchy: "score and fixture state before supporting context before ornament"
  emptyState: "hide an unsupported section instead of inventing content"
elevation:
  posture: "tonal+hairline"
  card:
    background: "var(--card)"
    border: "1px solid var(--hairline)"
    shadow: "none"
  raised:
    background: "var(--raised)"
    border: "1px solid var(--hairline)"
    shadow: "none"
motion:
  entry: "0ms-in"
  durationInstant: "0ms"
  durationFast: "140ms"
  durationNormal: "200ms"
  durationSlow: "300ms"
  durationSlower: "500ms"
  easeOut: "cubic-bezier(0.16, 1, 0.3, 1)"
  easeSpring: "cubic-bezier(0.3, -0.04, 0, 1.1)"
  livePulsePeriod: "1.6s"
  reducedMotion: "collapse nonessential animation"
shapes:
  small: "8px"
  medium: "10px"
  default: "12px"
  large: "16px"
  full: "9999px"
components:
  ScoreBlock: "inline and hero score anatomy"
  ScoreTick: "weighted score-change feedback"
  LiveDot: "semantic live-state signal"
  TeamCrest: "club and national-team identity"
  EntityBadge: "typed football entity label"
  PlayerAvatar: "player identity with stable fallback"
  PitchChemistryLinks: "squad relationship overlay"
  SectionHeader: "compact section hierarchy"
voice:
  summary: "Weekend football energy with operator-grade tables: scoreboard-driven, fixture-aware, and restrained between matchdays."
  guidelines:
    - "Never fabricate football data."
    - "Name football reality rather than backend, diagnostic, or agent machinery."
    - "State uncertainty and missing data instead of converting either into confident prose."
    - "Count the cold stranger on the open web in every product decision."
dos:
  - "Publish only football claims supported by real source data."
  - "Keep zero personalized surfaces inside voet.app; personalization belongs to Copa and native widgets or notifications."
  - "Use monochrome hierarchy and semantic color for state."
  - "Use tonal surfaces and structural hairlines for primary data elevation."
  - "Render first paint at 0ms-in and reserve motion for user-triggered state."
  - "Compose L1 behavior through the @repo/design L2 facade."
donts:
  - "Fabricate football data."
  - "Ship a personalized surface inside voet.app."
  - "Expose an in-app chat agent inside voet.app; /chat stays dev-only and Copa is the explicit voice."
  - "Trade beauty for correctness, correctness for craft, or polish for speed."
  - "Use dark patterns, fake urgency, engagement bait, or launch theater."
  - "Upstream the Voet-owned hand-pixel football-universe visual soul."
---

# Voet Design Contract

## Overview

Voet is creative-int's public proof of football craft: the voet.app reference instrument and the Copa companion, built for public football fans, with every route held to the same bar. @creative-int/design owns this schema family; Voet fills it through @repo/design without defining a competing form. Product truth lives in docs/SOUL.md; the portable L2 catalog is docs/design/DESIGN.md; the catalog-token record is docs/decisions/2026-07-07-design/tokens.css; runtime tokens and motion live in packages/design/styles/globals.css and packages/design/lib/motion.ts. Runtime L2 code wins when a catalog snapshot differs. Source presence is not deployment proof, and live URL presence alone is not whole-product conformance; production truth requires both readbacks.

## Colors

The reference instrument posture is monochrome+semantic. Neutral light and dark surface steps carry hierarchy through tone and foreground weight. Semantic tokens communicate live, win, draw, loss, home, and away state; named tournament and hand-pixel brand moments may carry deliberate owned color.

## Typography

Geist Sans carries body and display. Display becomes heavy, tight, and tabular instead of changing to a decorative face. Iosevka Term is the technical register, score and stat primitives use tabular lining figures, and Geist Pixel is reserved for owned hand-pixel moments.

## Layout

Dense tables and lists use the compact register; editorial and match-hero surfaces use the spacious register. Score, fixture state, and source-backed football context precede ornament. Unsupported sections hide instead of fabricating placeholder content.

## Elevation & Depth

Primary data surfaces use the tonal+hairline posture: the light theme lifts cards toward near-white and the dark theme lifts panels above a near-black floor, with structural hairlines drawn from ink-alpha so one line composes on every surface. Drop shadow is not the elevation primitive for resting surfaces; only floating layers carry a hairline-scale micro-shade.

## Motion

The entry posture is 0ms-in: first paint is final, with no mount fade, lift, blur, or list stagger. User-triggered states draw from the shared weight, snap, glide, and breathe motion set. The live pulse uses a restrained 1.6-second rhythm and reduced-motion preference collapses nonessential animation.

## Shapes

The runtime default radius is 12px. Smaller control radii and full pills appear only where their component anatomy calls for them.

## Components

L1 behavior primitives are consumed through the @repo/design L2 facade. Voet-owned football primitives cover score anatomy, live state, team and player identity, squad chemistry, and compact section hierarchy; the hand-pixel universe remains product DNA rather than a fleet primitive.

## Voice & Content

Consumer copy is direct, football-literate, and honest about uncertainty. It never substitutes internal system language for the match, table, player, team, or source state a person came to understand.

Weekend football energy with operator-grade tables: scoreboard-driven, fixture-aware, and restrained between matchdays.

- Never fabricate football data.
- Name football reality rather than backend, diagnostic, or agent machinery.
- State uncertainty and missing data instead of converting either into confident prose.
- Count the cold stranger on the open web in every product decision.

## Do's and Don'ts

These rules bind beautiful truth to shipped behavior. They are constraints, not launch-copy adjectives, and each production claim must remain falsifiable against source, product, and live-URL evidence.
- Do: Publish only football claims supported by real source data.
- Do: Keep zero personalized surfaces inside voet.app; personalization belongs to Copa and native widgets or notifications.
- Do: Use monochrome hierarchy and semantic color for state.
- Do: Use tonal surfaces and structural hairlines for primary data elevation.
- Do: Render first paint at 0ms-in and reserve motion for user-triggered state.
- Do: Compose L1 behavior through the @repo/design L2 facade.
- Don't: Fabricate football data.
- Don't: Ship a personalized surface inside voet.app.
- Don't: Expose an in-app chat agent inside voet.app; /chat stays dev-only and Copa is the explicit voice.
- Don't: Trade beauty for correctness, correctness for craft, or polish for speed.
- Don't: Use dark patterns, fake urgency, engagement bait, or launch theater.
- Don't: Upstream the Voet-owned hand-pixel football-universe visual soul.