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 — not reliant on 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.
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
Designesy design system · v0.4.0
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 · Machine export · /contracts/design-system.json · Public review · /review/designesy-org
01 · Source and provenance
02 · Primitive tokens
Colors (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#0133cbBrand signal accent--signal-light#3358e8Signal hover / focus lift--signal-access#5d7bffAccessible signal (AA on dark)--paper-on-signal#ffffffText on signal fill--activation#fecc34Activation 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(1, 51, 203, 0.14)Signal wash / badge fillShape, shell, motion primitives
--radius6pxDefault corner radius--radius-sm4pxCompact controls / nav chips--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 slideShadows (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
Surface 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 = reserved highlight, not general chrome
Type roles
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
Shell horizontal1.5rem (1rem ≤560px).site-shell / .surface-pageSection vertical3.5rem / 3rem doctrine.section / .doctrine-sectionCard padding1.25–1.5rempillars, surfaces, itemsGrid gap0.75–1rempillar / surface gridsControl min height42px buttons, 32px sound toggletouch-friendly targetsBreakpoints860px · 720px · 560pxgrids · topbar · single-columnLayout 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.
spring.defaultdamping 1.0 · response 0.4Default spring physics for natural motionspring.momentumdamping 0.8 · response 0.3Momentum spring for continued motion09d · Acoustic tokens
Custom $type: sound via $extensions.designesy. Net-new relative to W3C DTCG 2025.10. Full cue table at /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 Copywriting discipline. 4 principles are codified as verification checks (v38–v41); 12 are governance.
Principles
Verification checks (automated)
Governance (human review)
Tooling