---
name: designesy-design-system
version: 0.1.4
description: Design intelligence rules for building interfaces that match the Designesy contract. Use when building UI for Designesy, reviewing against the contract, or proposing design changes that must cite contract tokens.
---

# Designesy Design System — v0.1.4

> Designesy design doctrine — public surface carries operational values only

This is the portable SKILL.md export of the Designesy design system contract.
It encodes the same rules as the [human contract](https://www.designesy.org/contracts/design-system) and the
[machine JSON](https://www.designesy.org/contracts/design-system.json), reformatted as behavioral instructions for
AI coding agents. Updated 2026-07-13.

**Canonical source:** https://www.designesy.org/contracts/design-system
**Machine JSON:** https://www.designesy.org/contracts/design-system.json
**License:** https://creativecommons.org/licenses/by/4.0/

## When to Use

- When building or modifying UI for designesy.org or any Designesy surface
- When reviewing an interface against the Designesy contract
- When proposing design changes that must cite contract tokens or name open tensions
- When an agent needs to know which colors, radii, motion timings, or interaction rules Designesy uses

## Tokens

### Colors

| Token | Value | Role |
|---|---|---|
| `--ink` | #ffffff | Primary text / foreground |
| `--muted` | #a0a0a0 | Secondary text |
| `--muted-dim` | #6b6b6b | Tertiary / meta text |
| `--paper` | #000000 | Page background |
| `--surface` | #0a0a0a | Card / panel base |
| `--surface-raised` | #111111 | Elevated surface |
| `--signal` | #0133cb | Brand accent (internal token name; public products avoid this vocabulary) |
| `--signal-light` | #3358e8 | Accent hover / focus lift |
| `--activation` | #fecc34 | Activation highlight (reserved) |

### Surfaces and lines

| Token | Value | Role |
|---|---|---|
| `--surface-soft` | rgba(255, 255, 255, 0.03) | Soft fill / note background |
| `--surface-hover` | rgba(255, 255, 255, 0.06) | Hover wash |
| `--line` | rgba(255, 255, 255, 0.12) | Default border |
| `--line-strong` | rgba(255, 255, 255, 0.22) | Emphasized border |
| `--line-faint` | rgba(255, 255, 255, 0.06) | Subtle divider |
| `--signal-dim` | rgba(1, 51, 203, 0.14) | Accent wash / badge fill |

### Shadows

| Token | Value |
|---|---|
| `--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) |

### Radius

| Token | Value | Role |
|---|---|---|
| `--radius` | 6px | Default corner radius |
| `--radius-sm` | 4px | Compact controls / nav chips |

### Layout

- Max width: 1080px (Content shell max width)
- Shell horizontal padding: 1.5rem (1rem at ≤560px)
- Section vertical rhythm: 3.5rem / 3rem doctrine
- Card padding: 1.25–1.5rem
- Grid gap: 0.75–1rem
- Control min height: 42px buttons, 32px sound toggle
- Breakpoints: grids 860px, topbar 720px, single column 560px

### Motion

| Token | Value | Role |
|---|---|---|
| `--duration` | 0.6s | Primary entrance duration |
| `--ease` | cubic-bezier(0.22, 0.61, 0.36, 1) | Default ease |
| `--ease-out` | cubic-bezier(0.23, 1, 0.32, 1) | Exit / settle |
| `--ease-in-out` | cubic-bezier(0.77, 0, 0.175, 1) | Symmetric motion |
| `--ease-drawer` | cubic-bezier(0.32, 0.72, 0, 1) | Drawer / panel slide |

### Typography

- Body: 16px / 1.55, system stack (-apple-system, BlinkMacSystemFont, Inter, Segoe UI, Arial, Helvetica, sans-serif)
- Headings: weight 700, line-height 1.08, letter-spacing -0.02em
- Hero wordmark: clamp(3.2rem, 9vw, 5.5rem), weight 800, tracking -0.04em
- Eyebrows: 0.72–0.75rem, weight 600, uppercase, letter-spacing 0.18em, muted-dim
- Lede: 1.1–1.5rem, weight 500, ink — one clear claim
- Supporting note: 0.85–0.95rem, muted, max-width ~520–580px
- Rule: Never invent decorative display fonts for public UI; system stack is the contract

## Rules — Interaction (Poise, adopted v0.1.1)

- Wordmark mark may use opacity breath only; never blur, glow, or gradient decoration
- Interactive press settle: scale(0.97) at ~160ms with --ease-out
- Sound preference key designesy:sound; Designesy owns preference; audio engine only applies it
- Reduced motion disables non-essential animation and defaults sound off
- Hover translation only under fine pointer + hover-capable media
- Public product names stay human and premium; internal token names may differ
- If the response is louder than the action, it fails

## Rules — Interface Feel (Takt, adopted v0.1.2)

- Concentric border radius: outerRadius = innerRadius + padding on every nested pair
- Press scale 0.96 on cells and buttons; 0.985 on cards and rows — never below 0.95
- Image outlines: 1px at 0.1 opacity, pure black in light mode, pure white in dark mode — never tinted neutrals
- Minimum hit area: 44px for touch, 40px for desktop — extend with pseudo-element when needed
- Stagger enter animations: ~80–100ms per semantic chunk; skip animation on page load
- Soften exits: small fixed translateY, softer than enter — no full-height collapse
- Never use transition: all — every transition names its specific properties
- Spare will-change: only transform, opacity, or filter — only when a stutter was observed

## Rules — Typography (Cadence, adopted v0.1.3)

- Font smoothing on root: -webkit-font-smoothing: antialiased + -moz-osx-font-smoothing: grayscale
- Rem-based scale: every text size is a rem multiple of the 16px root — never px
- Line-height by role: headings 1.05–1.1, body 1.5–1.6, display 1 — never a single global line-height
- Tracking by size: negative for headings (-0.02 to -0.04em), positive for labels (0.03–0.18em), zero for body
- Cap the measure: body text 520–580px max, layout shell 1080px — text wider than 75ch loses readers
- Wrap deliberately: text-wrap: balance on headings, text-wrap: pretty on body
- Tabular numbers: font-variant-numeric: tabular-nums for all data, stats, and numerical tables
- Selection: ::selection styled with a token color — never default browser blue
- user-select: none on UI chrome (buttons, labels, meta) — body text stays selectable
- 16px input floor on mobile — inputs never below 16px to avoid iOS auto-zoom
- No decorative display fonts: system stack is the contract for public UI

## Rules — Motion

- Entrance: fadeUp 0.6s --ease with staggered delays (0.08s steps)
- Interactive settle: scale(0.97) at ~160ms --ease-out (Poise · adopted v0.1.1)
- Hover lift only under (hover: hover) and (pointer: fine) (Poise · adopted v0.1.1)
- Wordmark mark: opacity breath only (~3.2s --ease-in-out); no blur, glow, or gradient decoration (Poise · adopted v0.1.1)
- prefers-reduced-motion: reduce collapses non-essential motion; sound defaults off (Poise · adopted v0.1.1)

## 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**: 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

## Accessibility

- html lang="en"; meaningful page titles via metadata template
- Focus-visible: 2px solid --signal-light, offset 2px
- Sound control exposes aria-label, aria-pressed, and title
- Decorative glyphs use aria-hidden where text is already labeled
- Prefer semantic landmarks: sticky header, main, footer
- Do not rely on color alone for state
- Respect prefers-reduced-motion
- Scroll padding-top 4rem for sticky topbar anchors

## Anti-patterns — do not

- Glowing blobs, random gradients, or sparkle decoration
- Hard-coded hex in components when a role token exists
- Using --activation as general decoration
- Publishing taste language without operational rules
- Multiple simultaneous accent colors competing with --signal
- Touch targets under ~32px
- Animation that cannot be reduced
- Public product names that sound like research demos or AI jargon

## Implementation notes

- Single live token source of truth — no secondary theme framework
- Server-rendered by default; client only for sound, bind, and preference controls
- metadataBase is https://www.designesy.org (apex redirects); public label is Designesy
- Interaction audio via Cuelume with middle-click guard
- Sitemap and robots follow standard site conventions
- Production deploys from the main branch
- Drift rule: every new public UI change cites a contract token or open tension

## Verification — evidence requirements

Before shipping, verify:

- Token values match the live site :root foundation
- Routes render without horizontal overflow at 375px, 720px, 860px, 1080px+
- Primary interactive elements show focus-visible rings
- Sound toggle flips aria-pressed and applies the audio preference
- prefers-reduced-motion disables entrance and wordmark breath
- Contrast remains readable for ink, muted, and accent on paper
- No public surface displays internal control-plane naming
- Poise interaction rules match live /labs/poise and contract.interaction
- Poise keyboard-path verification remains published and current
- Takt interface-feel rules match live CSS and contract.takt
- No transition:all in the live stylesheet
- will-change restricted to transform and opacity only
- Press scale 0.96 on cells, 0.985 on cards/rows — both above 0.95 floor
- Cadence typography rules match live CSS and contract.cadence
- Font smoothing: antialiased + grayscale on :root confirmed
- Rem-based scale: all text sizes in rem, root at 16px confirmed
- Line-height by role: headings 1.08, body 1.55 confirmed
- text-wrap: balance + pretty both present in live CSS
- tabular-nums: 8 instances across the live CSS
- ::selection styled with var(--signal) — not browser default
- Core Web Vitals plausible: LCP < 2.5s, INP < 200ms, CLS < 0.1 (Taste Skill pre-flight)
- Primary button text passes WCAG AA 4.5:1 contrast against --signal fill (Taste Skill pre-flight)
- Duration tokens --duration-quick through --duration-slow present in :root (transitions.dev cross-ref)

## Open tensions — unresolved

These are known gaps. If you encounter them, name the tension instead of inventing policy:

- Light theme is not contracted — dark technical foundation is provisional
- --activation exists but has limited public surface usage
- Inter is named in the stack but not self-hosted; system fallback is intentional
- Shadow tokens exist; elevation language is still light-touch (borders lead)
- Human contract page and machine export remain dual sources until a single generator owns both
- Keyboard-path verification packets are published for Poise only — not every public route
- font-synthesis: none set on :root — prevents fake browser weights (Cadence v0.1.3 fix applied)
- Inline-axis logical properties (margin-inline, padding-inline) applied — block-axis and border-inline remain physical (Cadence partial migration)
- text-underline-position: from-font and text-decoration-skip-ink: auto set on :root (Cadence v0.1.3 fix applied)

## Semantic roles

- **Surfaces:** paper = page void · surface = default panel · surface-raised = hover/emphasis · surface-soft = quiet note · surface-hover = interactive wash
- **Lines:** line = default structure · line-strong = active/emphasis · line-faint = quiet subdivision
- **Accents:** signal = brand action and wordmark mark · signal-light = hover/focus · signal-dim = badge/wash · activation = reserved highlight
- **Types:** ink = primary claim · muted = supporting body · muted-dim = eyebrows, meta, footers

## Provenance

- Implementation: designesy.org (Next.js App Router)
- Token source: Live site design tokens (:root)
- Interaction audio: Cuelume v0.1.0; preference owned by Designesy
- Motion references: Short settle and easing language adapted into --ease-out, --ease-in-out, --ease-drawer

### Source labs

- [Lab One · Poise](https://www.designesy.org/labs/poise) — Source lab for interaction rules adopted in v0.1.1
- [Lab Two · Takt](https://www.designesy.org/labs/takt) — Source lab for interface-feel rules adopted in v0.1.2
- [Lab Three · Cadence](https://www.designesy.org/labs/cadence) — Source lab for typography rules adopted in v0.1.3

### Field checks

- https://www.designesy.org/labs/poise
- https://www.designesy.org/review/poise
- https://www.designesy.org/review/poise/keyboard
- https://www.designesy.org/labs/takt
- https://www.designesy.org/review/takt
- https://www.designesy.org/labs/cadence
- https://www.designesy.org/review/cadence

### External ingests

- [Amicro](https://amicro.vercel.app) by Kiyotaka (@SubhanHQ) — Micro-transitions library — informed Takt stagger and press rules
- [better-ui skill](https://github.com/jakubkrehel/skills) by Jakub Krehel (@jakubkrehel) — 13 interface polish principles — source for concentric radii, press scale, image outlines, hit areas (MIT)
- [better-typography skill](https://github.com/jakubkrehel/skills) by Jakub Krehel (@jakubkrehel) — 18 typography principles — source for font smoothing, scale, leading, tracking, measure, wrapping, numbers, selection (MIT)
- [agent-skills](https://github.com/addyosmani/agent-skills) by Addy Osmani (@addyosmani) — Anti-rationalization table pattern + verification checklist methodology — informed Design Review kit rationalization section (MIT)
- [Taste Skill](https://github.com/Leonxlnx/taste-skill) by Leon (@Leonxlnx) — Pre-flight checklist methodology — gap audit against our 8-dimension review; Core Web Vitals and button contrast checks adopted (MIT)
- [transitions.dev](https://transitions.dev) by Jakub Antalik (@Jakubantalik) — Motion token library — duration scale cross-referenced; press scale values validated (0.96/0.97 match); easing curves confirmed compatible

### Adoption history

- **v0.1.0** (2026-07-12): First public design system contract — tokens, motion, components, verification
- **v0.1.1** (2026-07-12): Adopted Lab One · Poise interaction rules: wordmark breath, press settle, sound preference, reduced motion, hover media, naming discipline — from Lab Poise
  Evidence: https://www.designesy.org/labs/poise, https://www.designesy.org/review/poise, https://www.designesy.org/review/poise/keyboard
- **v0.1.2** (2026-07-13): Adopted Lab Two · Takt interface-feel rules: concentric radii, press scale (0.96/0.985), image outlines, hit area floor, stagger rhythm, no transition:all, spare will-change. Rules compiled from external design intelligence (Amicro, Krehel /better-ui) and verified on live CSS. — from Lab Takt
  Evidence: https://www.designesy.org/labs/takt, https://www.designesy.org/review/takt
- **v0.1.3** (2026-07-13): Adopted Lab Three · Cadence typography rules: font smoothing on root, rem-based scale, line-height by role, tracking by size, measure cap, text-wrap balance+pretty, tabular numbers, ::selection with --signal, user-select on UI chrome, 16px input floor. Rules compiled from external typography intelligence (Krehel /better-typography) and verified on live CSS. Three open tensions documented: font-synthesis, logical properties, underline-from-font. — from Lab Cadence
  Evidence: https://www.designesy.org/labs/cadence, https://www.designesy.org/review/cadence
- **v0.1.4** (2026-07-13): Adopted duration scale (transitions.dev cross-ref), Core Web Vitals + button contrast verification (Taste Skill gap audit), anti-rationalization methodology (agent-skills pattern). Duration tokens --duration-quick (150ms) through --duration-slow (400ms) added to :root. Three external ingests added to provenance: agent-skills (Osmani), Taste Skill (Leon), transitions.dev (Antalik). No lab source — this is a direct contract refinement from external source ingests.
  Evidence: https://www.designesy.org/contracts/design-system.json, https://www.designesy.org/contracts/skill