google-labs-code / design.md

# DESIGN.md
A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.
## The Format
A DESIGN.md file combines machine-readable design tokens (YAML front matter or interleaved YAML code blocks) with human-readable design rationale (markdown prose). Tokens give agents exact values. Prose tells them *why* those values exist and how to apply them.
 [code] 
An agent that reads this file will produce a UI with deep ink headlines in Public Sans, a warm limestone background, and Boston Clay call-to-action buttons.
## Getting Started
Validate a DESIGN.md against the spec, catch broken token references, check WCAG contrast ratios, and surface structural findings — all as structured JSON that agents can act on.
 [code] 
 [code] 
Compare two versions of a design system to detect token-level and prose regressions:
 [code] 
 [code] 
## The Specification
The full DESIGN.md spec lives at `docs/spec.md`. What follows is a condensed reference.
### File Structure
A DESIGN.md file has two layers:
1. **YAML Design tokens** — Machine-readable design tokens, delimited by `---` fences at the top of the file or interleaved as fenced ` [code] yaml
version: # optional, current: "alpha"
name: 
description: # optional
omitted: # optional, list of sections to intentionally omit
colors:
 : 
typography:
 : 
rounded:
 : 
spacing:
 : 
components:
 :
 : 
 [code] yaml
components:
 button-primary:
 backgroundColor: "{colors.tertiary}"
 textColor: "{colors.on-tertiary}"
 rounded: "{rounded.sm}"
 padding: 12px
 button-primary-hover:
 backgroundColor: "{colors.tertiary-container}"
 [code] bash
npm install @google/design.md
 [code] bash
npm install "@google/design.md"
 [code] bash
npx @google/design.md lint DESIGN.md
 [code] bash
npx -p @google/design.md designmd lint DESIGN.md
 [code] bash
npm config get registry
 [code] jsonc
> // package.json
> {
> "scripts": {
> "design:lint": "designmd lint DESIGN.md"
> }
> }
> [code] bash
npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md
cat DESIGN.md | npx @google/design.md lint -
 [code] bash
npx @google/design.md diff DESIGN.md DESIGN-v2.md
 [code] bash
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
 [code] bash
npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json
 [code] typescript
import { lint } from '@google/design.md/linter';
const report = lint(markdownString);
console.log(report.findings); // Finding[]
console.log(report.summary); // { errors, warnings, info }
console.log(report.designSystem); // Parsed DesignSystemState
```
## Design Token Interoperability
DESIGN.md tokens are inspired by the W3C Design Token Format. The `export` command converts tokens to other forma