Operating rules
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
Why contracts matter
The question a contract answers
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
Designesy design system · v0.4.6
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 · Machine export · /contracts/design-system.json · Public review · /review/designesy-org
01 · Source and provenance
↑ Contents02 · Primitive tokens
↑ ContentsColors (exact values)
--ink#f5f5f7Primary text / foreground--muted#a0a0a0Secondary text--muted-dim#7d7d7dTertiary / meta text--paper#010102Page background--surface#0a0a0cCard / panel base--surface-raised#121216Elevated surface--surface-lifted#16161bLifted / hover panel--signal#0A94FFBrand signal accent--signal-light#36A7FFSignal hover / focus lift--signal-access#0A94FF · light: #016ABBAccessible signal (AA on dark)--paper-on-signal#010102Text on signal fill--activation#F56B00Activation highlight (reserved)Surfaces and lines
--surface-softrgba(255, 255, 255, 0.03)Soft fill / note background--surface-hoverrgba(255, 255, 255, 0.06)Hover wash--linergba(255, 255, 255, 0.12)Default border--line-strongrgba(255, 255, 255, 0.22)Emphasized border--line-faintrgba(255, 255, 255, 0.06)Subtle divider--signal-dimrgba(10, 148, 255, 0.14)Signal wash / badge fillShape, shell, motion primitives
--radius-sm4pxCompact controls / nav chips--radius6pxDefault corner radius--radius-md8pxIntermediate corner radius (a documented 8px tier outside the 4-step public scale)--radius-lg12pxCards / panels / large surfaces--radius-xl16pxHero / modal / flagship surfaces--maxw1080pxContent shell max width--duration0.6sPrimary entrance duration--duration-quick150msClose, swap, tooltip--duration-fast250msOpen, hover transition, icon swap--duration-medium350msPanel close, toast--duration-slow400msPanel open, skeleton reveal--easecubic-bezier(0.22, 0.61, 0.36, 1)Default ease--ease-outcubic-bezier(0.23, 1, 0.32, 1)Exit / settle--ease-in-outcubic-bezier(0.77, 0, 0.175, 1)Symmetric motion--ease-drawercubic-bezier(0.32, 0.72, 0, 1)Drawer / panel slideMaterial and depth
Depth comes from surface lightness first, then one top-lit rim and one light straight down.
--mat-readingvar(--surface)Tier 1, opaque reading surface: principle cells, pillars, surface cards, history and state panels--mat-instrumentlinear-gradient(180deg, var(--surface-lifted), var(--surface-raised))Tier 2, opaque instrument body: the score console, the Drift instrument, the health panel, the inspection window--mat-floatvar(--surface-lifted)Tier 3, opaque floating element over static content; also the reduced-transparency fallback for all glass--rimlinear-gradient(180deg, rgb(255 255 255 / 0.14), rgb(255 255 255 / 0.05) 38%, rgb(255 255 255 / 0.03))The 1px top-lit edge on every tier-1+ surface, painted on a masked ::before--rim-hotlinear-gradient(180deg, rgb(255 255 255 / 0.24), rgb(255 255 255 / 0.08) 38%, rgb(255 255 255 / 0.05))Rim on hover and focus-visible, on a second pre-rendered layer whose opacity crossfades--elev-10 1px 1px rgb(0 0 0 / 0.3), 0 2px 4px rgb(0 0 0 / 0.22)Elevation 1: reading cards. Every x offset is 0 (one light, straight down)--elev-20 1px 1px rgb(0 0 0 / 0.28), 0 4px 8px -2px rgb(0 0 0 / 0.3), 0 12px 24px -8px rgb(0 0 0 / 0.36)Elevation 2: instruments and paired panels--elev-30 2px 2px rgb(0 0 0 / 0.26), 0 8px 16px -4px rgb(0 0 0 / 0.32), 0 24px 48px -12px rgb(0 0 0 / 0.42), 0 48px 96px -32px rgb(0 0 0 / 0.55)Elevation 3: floating controls and objects (command slab, popovers, verdict HUD)--elev-40 2px 4px rgb(0 0 0 / 0.3), 0 16px 32px -8px rgb(0 0 0 / 0.4), 0 40px 80px -16px rgb(0 0 0 / 0.5), 0 80px 140px -40px rgb(0 0 0 / 0.6)Elevation 4: transient overlays only (find palette, mobile drawer)--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
↑ ContentsSurface roles
paper = page void · surface = default panel · surface-raised = hover/emphasis panel · surface-soft = quiet note fill · surface-hover = interactive wash
Line roles
line = default structure · line-strong = active/emphasis edge · line-faint = quiet subdivision
Signal roles
signal = brand action and wordmark dot · signal-light = hover and focus lift · signal-dim = badge/wash · activation = highlights only
Type roles
ink = primary claim · muted = supporting body · muted-dim = eyebrows, meta, footers
04 · Typography rules
↑ Contents- 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
↑ ContentsShell horizontalclamp(1rem, 4vw, 1.5rem)--shell-gutter, outside the content boxLayout grid12 columns, 1rem gutter, 7|5 split.g12; bars end on the instrument dividerSection verticalclamp(2.5rem, 5vw, 3.5rem) doctrine · clamp(3.5rem, 8vw, 6.5rem) bands.doctrine-section / .sectionCard padding1 to 1.5remstatus notes 1rem, definitions and cards 1.25 to 1.5remGrid gap1rem (--grid-gutter), one gutterthe 12-column grid and the card grids it holdsControl min height44px buttons, sense toggles and preference switchestouch and pointer targetsLayout switch@container 64rem (mid tiers 34 to 48rem; 57rem for the inspection demo)grids, row lists and panels query their own widthViewport queries720px chrome · 860px and 560px older blocksheader and drawer; demo racks, pricing, home heroLayout 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
↑ Contents07 · Component states
↑ ContentsPrimary 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
↑ Contents09 · Motion and reduced-motion
↑ Contents09a · Ten non-negotiable motion standards
↑ ContentsThe positive form of the motion anti-patterns below. Every motion-bearing artifact must pass all ten.
09b · Motion anti-patterns
↑ ContentsBlock on sight
Caution
09c · Spring physics
↑ ContentsCustom $type: spring via $extensions.designesy. Net-new relative to W3C DTCG 2025.10.
spring.defaultdamping 1.0 · response 0.4Default spring physics for natural motionspring.momentumdamping 0.8 · response 0.3Momentum spring for continued motion09d · Acoustic tokens
↑ ContentsCustom $type: sound via $extensions.designesy. Net-new relative to W3C DTCG 2025.10. Full cue table at /acoustic-tokens.
10 · Copywriting (v0.4.0)
↑ ContentsUX copy principles adopted in v0.4.0 from NN/g, Polaris, IBM Carbon, Microsoft Fluent, Apple HIG, and Atlassian. Gap source: detail.design Copywriting discipline. 4 principles are codified as verification checks (v38 to v41); 12 are governance.