Design Contract

The design contract is automatically activated for any project with a web platform. It specifies the design system, typography, color architecture, component library, spacing rules, and animation standards. The Discovery Agent writes artifacts/discovery/design-contract.md. The Verifier measures conformance in Phase 7.

Default Design System

Unless the project brief specifies otherwise, web projects use this default stack:

Color Architecture

All colors are defined as CSS custom properties. The Builder never hardcodes hex values in components — always uses semantic tokens:

/* globals.css */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --border: 214.3 31.8% 91.4%;
  --radius: 0.5rem;
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... dark mode tokens */
}

Typography Scale

Spacing System

All spacing uses the Tailwind 4-unit (16px base) scale. The Builder never uses arbitrary pixel values in layout components:

• Section padding: py-16 px-6 (mobile) → py-24 px-8 (desktop)
• Card padding: p-4 (compact) | p-6 (standard) | p-8 (spacious)
• Stack gap: gap-2 (tight) | gap-4 (standard) | gap-8 (loose)
• Max content width: max-w-6xl mx-auto

shadcn/ui Component Usage Rules

The Builder uses shadcn/ui primitives before building custom components. New custom components must not duplicate shadcn functionality.

Animation Rules

• Micro-interactions: 150–200ms, ease-out. Used for hover states, focus rings, button presses.
• Page transitions: 300–400ms, spring physics. Used for route changes and modal opens.
• Content reveals: 500–600ms, staggered when multiple elements. Used for list items, cards appearing on scroll.
• Loading states: Skeleton placeholders (not spinners) for content loading >300ms.
• Reduced motion: All animations must respect prefers-reduced-motion. Use Framer Motion's useReducedMotion() hook.

Responsive Breakpoints

Visual regression baselines are captured at: 390px (mobile), 768px (tablet), 1024px (laptop), 1440px (desktop).

Verifier Design Contract Score

Phase 7 of the Verifier measures design contract conformance. Score is 0–100. Below 80 is a CONDITIONAL flag; below 60 is a RESTYLE recommendation to the Critic.