ContractsDesign system
Designesy design system
A reference format for AI-readable design contracts, version 0.4.5.
design.md (Google Labs, 26k+ stars) is the input layer: tokens and prose an agent reads to generate UI. This contract is input plus verification: 44 checks (41 automated) that test whether the generated output passes. Acoustic cues, takt interface-feel, copywriting principles, anti-generic tells, and provenance tracking have no design.md equivalent.
What this contract is
Operating agreement
A Designesy contract answers exact value, role, application, behavior, avoidance, and verification. It is public artifact discipline. It is not legal advice or a client service agreement.
Beyond design.md: the verification layer
Google Labs’ design.md (alpha, Apache-2.0, 26k+ stars) is a strong input format: YAML tokens + markdown prose that an agent reads to generate UI. Designesy extends that model with layers design.md does not carry. They are complementary: design.md is the brief; this contract is the brief and the proof.
TokensYAML frontmatterDTCG 2025.10 JSON + CORS endpointRationale prose9 markdown sectionsAdoption narratives + lab provenanceVerificationCLI linter + WCAG contrast44 checks (41 automated), live score engineAnti-generic detectionNot covered12 anti-generic tells (AI sameness)Acoustic cuesNot covered10 named cue tokens + mapping rulesInterface-feel (takt)Not coveredPress scale, hit area, stagger rhythmCopywritingNot covered16 UX copy principles, 4 as checks (v38 to v41)MotionDuration + easingSpring physics + 3-tier reduced-motionProvenanceNot coveredSource labs, adopted_in versions, external ingestsLive proofNot covereddesignesy.org/score: any URL, live gradeAgent skillReads the markdownSKILL.md format + MCP contract endpointThe gap design.md leaves open is the same gap every AI coding agent leaves open: generation is not verification. An agent can read a token file and still ship hardcoded hex, broken contrast, or the AI-default look. The 44-check engine closes that gap. Developers report that 42% of the code they commit is now AI-generated or assisted (Sonar, State of Code Developer Survey, January 2026), so the score is the compliance layer: it checks the shipped design against the rules the agent was given.
Contents
Token preview
Core color roles from the live foundation. Full tables live on the contracts surface and in the machine export.
--ink#f5f5f7Primary text / foreground--paper#010102Page background--surface#0a0a0cCard / panel base--signal#0A94FFBrand accent (internal token name; public products avoid this vocabulary)--signal-light#36A7FFAccent hover / focus lift--activation#F56B00Activated Orange, the exact RGB inverse of --signal: live moments only (a scan running, the live monitor, the activated mark). Selection is blueSurfaces
Poise adopted in v0.1.1
Lab One portable rules are contract material: wordmark breath, press settle, sound preference ownership, reduced motion, hover media discipline, and human public naming. Motion philosophy cross-referenced against Kowalski /emil-design-eng (Linear, ex-Vercel): frequency gate and unseen-details-compound principle. Spring physics and interruptibility cross-referenced against Kowalski /apple-design (Apple WWDC). Anti-over-animation Gate (Frequency, Purpose, Speed, Function) cross-referenced against Kowalski /find-animation-opportunities. Animation authoring (7-step build sequence and Never Ship table) cross-referenced against Kowalski /animate. Silence was not adoption; that version was the explicit order.
Takt adopted in v0.1.2
Lab Two portable rules are contract material: concentric radii, press scale (0.96 for cells, 0.985 for cards), image outlines, hit area floor, stagger rhythm, no transition:all, and spare will-change. Rules compiled from external design intelligence (Amicro, Krehel /better-ui, /better-accessibility for hit area floors) and verified on live CSS. Silence was not adoption; this version is the explicit order.
Cadence adopted in v0.1.3
Lab Three portable rules are contract material: font smoothing on root, rem-based scale, line-height by role, tracking by size, measure cap, text-wrap balance and pretty, tabular numbers, ::selection with --signal, user-select on UI chrome, and 16px input floor. Rules compiled from external typography intelligence (Krehel /better-typography, /better-layout for reading order and measure) and verified on live CSS. Three open tensions were documented at adoption: font-synthesis and underline-from-font have since closed, and logical properties stays open. Silence was not adoption; this version is the explicit order.
Acoustics adopted in v0.3.0
Lab Four portable rules are contract material: ten named cue tokens (--cue:brand through --cue:contact), one primary cue family per role, opt-in sound with localStorage preference, fine-pointer hover discipline, no focus sounds, no ambient audio, silent fallback when Web Audio is blocked, and reduced-motion as an acoustic-reduction proxy. Engine: Cuelume v0.2.2 (MIT). Silence was not adoption; this version is the explicit order.
Copywriting adopted in v0.4.0
UX copy principles from NN/g, Polaris, IBM Carbon, Microsoft Fluent, Apple HIG, and Atlassian. Gap source: detail.design Copywriting discipline. 16 principles across button text, error messages, empty states, link text, general microcopy, and voice & tone. 4 codifiable principles are verification checks (v38 to v41); 12 are governance. Verb-first buttons, descriptive links, and one capitalization policy cross-referenced against Krehel /better-writing. Empty states, placeholder-as-example, and toggle ON-state labeling from Krehel /better-writing. Tooling: Vale, textlint, alex.