design-spec

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.

---

1. File structure

---
<YAML token front matter>
---

# Project Name (optional title)

## Overview
## Colors
## Typography
## Layout
## Elevation & Depth
## Shapes
## Components
## Do's and Don'ts

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            # optional
name: Daylight Prestige
description: ...          # optional
colors:
  <token-name>: "#RRGGBB"
typography:
  <token-name>:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: -0.02em
rounded:
  <scale>: 8px
spacing:
  <scale>: 16px           # Dimension or unitless number
components:
  <component-name>:
    backgroundColor: "{colors.primary}"
    rounded: "{rounded.md}"
    padding: 12px