# 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, with evidence in place of slogans or vibes. ## Published now - [Design system — Human overview, full tables below, machine JSON export](https://www.designesy.org/contracts/design-system) - [Tokens — W3C DTCG 2025.10 format conformance: color spaces, custom types, validation](https://www.designesy.org/contracts/tokens) - [Accessibility — WCAG 2.2 AA via axe-core 4.13.0](https://www.designesy.org/contracts/a11y) - [Motion — Lottie spec v1.0.1 and the Ten Non-Negotiable Motion Standards](https://www.designesy.org/contracts/motion) - [Poise adopted — Lab One interaction rules](https://www.designesy.org/labs/poise) - [Takt adopted — Lab Two interface-feel rules](https://www.designesy.org/labs/takt) - [Cadence adopted — Lab Three typography rules](https://www.designesy.org/labs/cadence) - [Acoustics adopted — Lab Four acoustic mapping rules](https://www.designesy.org/labs/acoustics) - [Copywriting adopted — UX copy principles from NN/g, Polaris, Carbon, Fluent, and HIG](https://www.designesy.org/contracts#09e-copywriting) - [Agent skill export — SKILL.md format for AI coding agents, built from the same source as the JSON](https://www.designesy.org/contracts/skill) - [Field check — Live site reviewed against this contract](https://www.designesy.org/review/designesy-org) - [Drift — AI-generated UI drift detection: token fabrication, value variance, and off-contract patterns](https://www.designesy.org/contracts/drift) - [AI Readiness — The 6th maturity axis: probes for machine-readable tokens, llms.txt, agent.json, MCP, and DESIGN.md](https://www.designesy.org/contracts/readiness) - [Guardrails — The product layer: emit a frozen build contract (DTCG tokens, Stylelint, AGENTS.md) for AI coding agents](https://www.designesy.org/contracts/guardrails) - [Monitor — 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 — 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 — 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. Each part opens its section of the published contract below. ## 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, and keep the standard contract visible to 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 and revised as the site changes. 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 ### Material and depth Depth comes from surface lightness first, then one top-lit rim and one light straight down. `--shadow-sm`, `--shadow-md` and `--shadow-lg` keep their published values in the token export; no surface on this site paints with them. ## 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 = highlights only ink = primary claim · muted = supporting body · muted-dim = eyebrows, meta, footers ## 04 · Typography rules - 01 Body: Schibsted Grotesk (--sans), 16 to 17px fluid, line-height 1.55; the system sans covers other scripts - 02 Headings h1 to h4: Fraunces (--display), weight 700, line-height 1.08, letter-spacing -0.02em; section headings and subheads set in --sans at weight 600 - 03 Hero wordmark: clamp(3.2rem, 9vw, 5.5rem), weight 800, tracking -0.04em - 04 Eyebrows: --text-label (0.8rem), weight 600, uppercase, letter-spacing 0.18em, muted-dim - 05 Lede: 1.1 to 1.5rem, weight 500, ink (one clear claim in a single paragraph) - 06 Supporting note: --text-body (1rem), muted, max-width ~520 to 580px - 07 Three faces and no more: Fraunces for headlines, Schibsted Grotesk for interface and reading, Atkinson Hyperlegible Mono for data and token names - 08 Type scale: a Major Third (x1.25) on a 16px root, no two adjacent steps closer than 25%: --text-label 0.8rem (the floor for all text, mono uppercase included), --text-body 1rem, --text-lead 1.25rem, --text-h3 1.563rem, --text-h2 1.953rem, --text-h1 2.441rem; display titles keep their clamp() sizes ## 05 · Spacing and layout rules Layout doctrine: one shell, one 16px gutter, and the 7|5 seam that notes, definitions and row lists hang on. Grids switch on their own width before type becomes unreadable; fewer columns beat cramped four-up layouts at mid widths. ## 06 · Shape and surface rules ## 07 · Component 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 reading material (--mat-reading) + top-lit rim + elev-1 · fine-pointer hover heats the rim and adds contact light, no lift · active scale(0.99) ### Sound toggle switch with a visible Sound label and an On/Off state word · aria-pressed sync · Cuelume setEnabled(true|false) ### Definition block reading material + top-lit rim + elev-1 · a copyable one heats its rim and draws a 3px signal edge on hover, focus or copy · label 12px uppercase muted ## 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. ## 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). ## 10 · 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 source: [detail.design](https://detail.design) Copywriting discipline. 4 principles are codified as verification checks (v38 to v41); 12 are governance. ### Principles ### Verification checks (automated) ### Governance (human review) ### Tooling ## 11 · Anti-patterns ## 12 · Implementation notes ## 13 · Verification criteria ## 14 · Open tensions