# Designesy — /contracts Canonical page: https://www.designesy.org/contracts --- ## Contracts Design contracts turn principles into reusable operating rules for artifacts, interfaces, and review. Designesy Contracts are portable design agreements that let people and agents carry design judgment across tools, sessions, codebases, and artifacts. They make design judgment inspectable — not reliant on slogans or vibes. ## Published now - [Design system · v0.4.0 — Human overview, full tables below, machine JSON export](https://www.designesy.org/contracts/design-system) - [Tokens · v0.1.0 — W3C DTCG 2025.10 format conformance — color spaces, custom types, validation](https://www.designesy.org/contracts/tokens) - [Accessibility · v0.1.0 — WCAG 2.2 AA via axe-core 4.13.0 — 11 verification checks](https://www.designesy.org/contracts/a11y) - [Motion · v0.1.0 — Lottie spec v1.0.1 + Ten Non-Negotiable Motion Standards — 10 verification checks](https://www.designesy.org/contracts/motion) - [Poise adopted — Lab One interaction rules adopted in contract v0.1.1](https://www.designesy.org/labs/poise) - [Takt adopted — Lab Two interface-feel rules adopted in contract v0.1.2](https://www.designesy.org/labs/takt) - [Cadence adopted — Lab Three typography rules adopted in contract v0.1.3](https://www.designesy.org/labs/cadence) - [Acoustics adopted — Lab Four acoustic mapping rules adopted in contract v0.3.0](https://www.designesy.org/labs/acoustics) - [Copywriting adopted — UX copy principles adopted in v0.4.0 — NN/g, Polaris, Carbon, Fluent, HIG](https://www.designesy.org/contracts#09e-copywriting) - [Agent skill export — SKILL.md format for AI coding agents — same source as JSON](https://www.designesy.org/contracts/skill) - [Field check — Live site reviewed against this contract](https://www.designesy.org/review/designesy-org) - [Drift · v0.1.0 — AI-generated UI drift detection — 12 checks for token fabrication, value variance, off-contract patterns](https://www.designesy.org/contracts/drift) - [AI Readiness · v0.1.0 — The 6th maturity axis — 10 checks probe for machine-readable tokens, llms.txt, agent.json, MCP, DESIGN.md](https://www.designesy.org/contracts/readiness) - [Guardrails · v0.1.0 — The product layer — emit a frozen build contract (DTCG tokens, Stylelint, AGENTS.md) for AI coding agents](https://www.designesy.org/contracts/guardrails) - [Monitor · v0.1.0 — The continuous-governance layer — re-score on a cadence, store snapshots, compute drift deltas, surface regressions before they compound](https://www.designesy.org/contracts/monitor) - [Compare · v0.1.0 — The diff engine — fetch two URLs, extract their token systems, and surface what actually changed across 8 dimensions: added, removed, renamed, value-changed, scale drift, contrast drift, structure delta, score delta](https://www.designesy.org/contracts/compare) - [Report · v0.1.0 — The synthesis capstone — fetch one URL, fire score + drift + readiness in parallel, and produce a unified design-intelligence report with a single composite grade. One input, one output, one grade](https://www.designesy.org/contracts/report) ## Why contracts matter What exact value should I use? Why does this value exist? Where may this value be applied? What behavior does this component need? What should I avoid? How do I know if I broke the system? A useful contract helps a future agent or team member answer all of these without relearning the design system from scratch. Contracts are the operational bridge between philosophy and execution. ## Contract contents A Designesy Contract should include all of the following — structured values for machines, rationale for humans, and verification criteria for both. ## Contract discipline Keep upstream-compatible schema names visible when compatibility matters: `colors`, `typography`, `rounded`, `spacing`, `components`. Use local extensions for doctrine, review, provenance, agent instructions, and verification — but do not hide the standard contract from tools. ### Anti-patterns ## Published contract Public design contract for designesy.org. Derived from the live site token foundation, with Lab One · Poise, Lab Two · Takt, Lab Three · Cadence, and Lab Four · Acoustics rules adopted. Provisional, doctrine-referenced, and meant to be verified against the running site — not a frozen brand bible. Contract home · [/contracts/design-system](/contracts/design-system) · Machine export · [/contracts/design-system.json](/contracts/design-system.json) · Public review · [/review/designesy-org](/review/designesy-org) ## 01 · Source and provenance ## 02 · Primitive tokens Colors (exact values) Surfaces and lines Shape, shell, motion primitives Shadows (supporting elevation, borders lead): `--shadow-sm` 0 1px 3px rgba(0,0,0,0.4) · `--shadow-md` 0 8px 30px rgba(0,0,0,0.35) · `--shadow-lg` 0 24px 80px rgba(0,0,0,0.5) ## 03 · Semantic tokens paper = page void · surface = default panel · surface-raised = hover/emphasis panel · surface-soft = quiet note fill · surface-hover = interactive wash line = default structure · line-strong = active/emphasis edge · line-faint = quiet subdivision signal = brand action and wordmark dot · signal-light = hover and focus lift · signal-dim = badge/wash · activation = reserved highlight, not general chrome ink = primary claim · muted = supporting body · muted-dim = eyebrows, meta, footers ## 04 · Typography rules - 01 Body: 16px / 1.55, system stack (-apple-system, BlinkMacSystemFont, Inter, Segoe UI, Arial, Helvetica, sans-serif) - 02 Headings: weight 700, line-height 1.08, letter-spacing -0.02em - 03 Hero wordmark: clamp(3.2rem, 9vw, 5.5rem), weight 800, tracking -0.04em - 04 Eyebrows: 0.72–0.75rem, weight 600, uppercase, letter-spacing 0.18em, muted-dim - 05 Lede: 1.1–1.5rem, weight 500, ink — one clear claim, not a paragraph stack - 06 Supporting note: 0.85–0.95rem, muted, max-width ~520–580px - 07 Never invent decorative display fonts for public UI; system stack is the contract ## 05 · Spacing and layout rules Layout doctrine: one max-width shell, editorial vertical rhythm, grids collapse before type becomes unreadable. Prefer fewer columns over cramped four-up layouts on mid widths. ## 06 · Shape and surface rules ## 07 · Component behavior and states ### Primary button default signal fill · hover signal-light · active scale(0.97) · focus-visible 2px signal-light ### Ghost button transparent + line-strong · hover surface-hover · active scale(0.97) ### Nav link muted · hover ink + surface-hover · sticky topbar blur when scrolled ### Card / pillar surface + line · hover raised + line-strong · active scale(0.985); lift only on fine pointer hover ### Sound toggle aria-pressed sync · pressed shows signal-light · Cuelume setEnabled(true|false) ### Definition block bordered surface · hover line-strong · label uppercase muted-dim ## 08 · Accessibility requirements ## 09 · Motion and reduced-motion ## 09a · Ten non-negotiable motion standards The positive form of the motion anti-patterns below. Every motion-bearing artifact must pass all ten. Easing is deliberate — use contract cubicBezier tokens, not bare CSS keywords Properties are explicit — never transition:all; name the exact properties Entrances have opacity — animate from scale(0.9–0.97) + opacity, never scale(0) Keyboard is still — no motion on keyboard-initiated or 100+/day actions Layout is not animated — never animate width, height, margin, padding, top, left Touch is gated — :hover motion on touch-visible surfaces requires explicit gating Duration is bounded — UI animation stays ≤ 300ms unless justified Reduced-motion is handled — every movement has a prefers-reduced-motion path Press is asymmetric — press and release use asymmetric timing Easing is never ease-in — deceleration (ease-out) or custom curves only ## 09b · Motion anti-patterns ### Block on sight ### Caution ## 09c · Spring physics Custom `$type: spring` via `$extensions.designesy`. Net-new relative to W3C DTCG 2025.10. ## 09d · Acoustic tokens Custom `$type: sound` via `$extensions.designesy`. Net-new relative to W3C DTCG 2025.10. Full cue table at [/acoustic-tokens](/acoustic-tokens). ## 09e · Copywriting (v0.4.0) UX copy principles adopted in v0.4.0 from NN/g, Polaris, IBM Carbon, Microsoft Fluent, Apple HIG, and Atlassian. Gap signal: [detail.design](https://detail.design) Copywriting discipline. 4 principles are codified as verification checks (v38–v41); 12 are governance. **Principles** **Verification checks (automated)** **Governance (human review)** **Tooling** ## 10 · Anti-patterns ## 11 · Implementation notes ## 12 · Verification criteria ## 13 · Open tensions