google-labs-code /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.
★ 28,887⑂ 2,306👁 151⑃ 120● 66▤ 5
TA的项目
+12
日增长
+183
周增长
+536
月增长
28,887
stars
2,306
forks
151
watchers
120
prs
66
issues
5
releases
README
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.
md
---
name: Heritage
colors:
primary: "1A1C1E"
secondary: "6C7278"
tertiary: "B8422E"
neutral: "F7F5F2"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
body-md:
fontFamily: Public Sans
fontSize: 1rem
label-caps:
fontFamily: Space Grotesk
fontSize: 0.75rem
rounded:
sm: 4px
md: 8px
spacing:
sm: 8px
md: 16px
---
Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.
Colors
The palette is rooted in high-contrast neutrals and a single accent color.
- Primary (1A1C1E): Deep ink for headlines and core text.
- Secondary (6C7278): Sophisticated slate for borders, captions, metadata.
- Tertiary (B8422E): "Boston Clay" — the sole driver for interaction.
- Neutral (F7F5F2): Warm limestone foundation, softer than pure white.
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.
bash
npx @google/design.md lint DESIGN.md
json
{
"findings": [
{
"severity": "warning",
"path": "components.button-primary",
"message": "textColor (ffffff) on backgroundColor (1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
}
],
"summary": { "errors": 0, "warnings": 1, "infos": 1 }
}
Compare two versions of a design system to detect token-level and prose regressions:
bash
npx @google/design.md diff DESIGN.md DESIGN-v2.md
json
{
"tokens": {
"colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
"typography": { "added": [], "removed": [], "modified": [] },
"rounded": { "added": [], "removed": [], "modified": [] },
"spacing": { "added": [], "removed": [], "modified": [] },
"components": { "added": [], "removed": [], "modified": [] }
},
"findings": {
"before": { "errors": 0, "warnings": 1, "infos": 1 },
"after": { "errors": 0, "warnings": 1, "infos": 1 },
"delta": { "errors": 0, "warnings": 0 }
},
"regression": false
}
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 fenceTop issues
#13Support for different modes/themes?11 comments · 2026-04-21#47Feature: motion tokens (duration, easing) with prefers-reduced-motion fallback7 comments · 2026-04-24#17Feature: Add Support for Component Variations6 comments · 2026-04-22#16Duplicating design facts in front matter and markdown body5 comments · 2026-04-21#158(feat) wish list item - static parsing a DESIGN from website4 comments · 2026-07-18#116Accessibility considerations: DESIGN.md as infrastructure for AI-generated UI3 comments · 2026-06-25#63Single vs. multiple DESIGN.md files within a project, is the spec opinionated?3 comments · 2026-05-01#101spec: Iconography section2 comments · 2026-06-04
Latest release
0.4.0 0.4.0 2026-07-27Bumps version from 0.3.0 to 0.4.0. All changes since 0.3.0: Bug Fixes - Missing design files fail gracefully instead of throwing a stack trace. Reading a non-existent or unreadable file now outputs a clean error message and structured JSON with exit code 2. (123, 145, @rmyndharis, @Emp1500) Fixes 132. - Successful exports always return exit code 0. Export command exit codes are now decoupled from source document linter warnings or errors, ensuring valid serialized builds pass pipeline gates. (126, 152, @rmyndharis, @arpitjain099) - Tailwind CSS exports end with exactly one trailing newline.