How to author a DESIGN.md file — the machine-readable design-token + human-rationale format that must exist before any UI is built. YAML front-matter token schema (colors, typography, spacing, rounded, components), type system, token references, and canonical section order.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
How to author a DESIGN.md file — the machine-readable design-token + human-rationale format that must exist before any UI is built. YAML front-matter token schema (colors, typography, spacing, rounded, components), type system, token references, and canonical section order.
when_to_use
BEFORE writing any UI code (web or mobile). Read when creating or updating a project's DESIGN.md, defining design tokens, or when a UI task needs a design source-of-truth. Pair with frontend-design (web aesthetics) or mobile-design (mobile).
allowed-tools
Read, Write, Edit, Glob, Grep
version
1.0.0
DESIGN.md Specification
A DESIGN.md is the single source of truth for a project's visual language. Create it BEFORE building UI.
Two layers: machine-readable design tokens (YAML front matter) + human-readable rationale (markdown body).
Tokens are normative; prose gives context. Prose may use descriptive names ("Midnight Forest Green") that map to systematic token names (primary).
Format adapted from the DESIGN.md spec (Google Labs, Apache-2.0). A linter/exporter exists: npx @google/design.md.
📚 Reference library:collection.md — 70+ real-world DESIGN.md files (Airbnb, Stripe, Linear, Vercel, Apple…) to study or adapt as a starting point.
When to produce a DESIGN.md
This is a hard gate for UI work (see .agents/rules/design-rules.md): before writing components, pages, or styles, a DESIGN.md must exist at the project root. If absent, create it first from the brief; if present, read it and conform.
The token block converts cleanly to/from tokens.json, Figma variables, and Tailwind theme config — so it is the bridge between design intent and code.
Front matter MUST begin and end with a line containing exactly ---. Sections use ## headings, appear in the order above, and may be omitted if irrelevant. Domain-specific sections may be added.
2. Token schema (YAML front matter)
version:alpha# optionalname:DaylightPrestigedescription:...# optionalcolors:<token-name>:"#RRGGBB"typography:<token-name>:fontFamily:PublicSansfontSize:48pxfontWeight:600lineHeight:1.1letterSpacing:-0.02emrounded:<scale>:8pxspacing:<scale>:16px# Dimension or unitless numbercomponents:<component-name>:backgroundColor:"{colors.primary}"rounded:"{rounded.md}"padding:12px
<scale> is a named level: xs sm md lg xl full (any descriptive key is valid).
3. Type system
Type
Format
Example
Color
# + hex (sRGB)
"#1A1C1E"
Dimension
number + unit (px/em/rem)
48px, -0.02em
Token Reference
{path.to.token}
{colors.primary}
Typography
composite object
see §4
Typography properties:fontFamily (string), fontSize (Dimension), fontWeight (number — bare or quoted are equivalent in YAML), lineHeight (Dimension or unitless multiplier — unitless recommended), letterSpacing (Dimension), fontFeature (string), fontVariation (string).
Token references: wrapped in {} pointing to another value in the tree. Most groups must reference a primitive ({colors.primary-60}), not a group. Inside components, references to composite values are allowed ({typography.label-md}).
The spec is extensible. When encountering content it doesn't define:
Scenario
Behavior
Unknown section heading (## Iconography)
Preserve; do not error
Unknown color token name
Accept if value is valid
Unknown typography token name
Accept as valid typography
Unknown spacing value
Accept; store as string if not a valid dimension
Unknown component property
Accept with warning
Duplicate section heading (two ## Colors)
Error; reject the file
7. Minimal example
---
name: Calm Scheduler
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
neutral: "#F7F5F2"
typography:
h1: { fontFamily: Public Sans, fontSize: 48px, fontWeight: 600, lineHeight: 1.1 }
body-md: { fontFamily: Public Sans, fontSize: 16px, fontWeight: 400, lineHeight: 1.6 }
rounded: { sm: 4px, md: 8px }
spacing: { sm: 8px, md: 16px, lg: 32px }
components:
button-primary:
backgroundColor: "{colors.tertiary}"
rounded: "{rounded.md}"
padding: 12px
---
# Calm Scheduler## Overview
A calm, professional interface for a healthcare scheduling platform.
Accessibility-first: high contrast, generous touch targets.
## Colors-**Primary (#1A1C1E):** Deep ink for headlines and core text.
-**Tertiary (#B8422E):** The sole driver for interaction.
-**Neutral (#F7F5F2):** Warm limestone foundation.
## Do's and Don'ts- Do use the tertiary color only for the single most important action per screen.
- Don't mix rounded and sharp corners in the same view.
- Do maintain WCAG AA contrast (4.5:1 for normal text).
Workflow
Read the brief and infer the design direction (see frontend-design / mobile-design).
ALWAYS read collection.md first — 70+ real-world DESIGN.md files. Find the 1–2 closest in vibe/industry to the brief, open their DESIGN.md on GitHub, and study how they structure tokens. Adapt, never blindly copy.
Write DESIGN.md at the project root — tokens first, then rationale prose.
Build UI strictly against the tokens. Descriptive names in prose must map to token names.
Keep DESIGN.md in sync when the visual language changes — it stays the source of truth.
