## what-is-design-md
One file that teaches your agent the design system.
DESIGN.md is an open format introduced by Google Labs (spec version alpha, Apache-2.0). It puts a design system's machine-readable tokens — colors, typography, spacing, radii, component defaults — in YAML front matter, and the human-readable rationale in markdown sections below. One plain-text file, readable by people, parseable by tools, and followed by any coding agent.
Agents are excellent at writing components and terrible at inventing visual language. Without a system they produce "AI-default" UI: generic indigo gradients, arbitrary spacing, inconsistent radii. With a DESIGN.md in the repo, the agent references real token values instead of guessing.
---
version: alpha
name: Example
colors:
primary: "#1A1C1E"
accent: "#B8422E"
typography:
body-md:
fontFamily: Public Sans
fontSize: 1rem
fontWeight: 400
---
## Overview
Calm, editorial, precise.
## Colors
- **Primary (#1A1C1E):** ink for text and actions.
- **Accent (#B8422E):** the single interactive voice.The format ships with an official linter and exporter (npx @google/design.md lint) that checks structure, WCAG AA contrast, and broken token references, and exports W3C DTCG tokens.json or a Tailwind v4 theme. Every file in the AgentDS catalog passes that linter with zero errors before it ships.
AgentDS gives you two kinds of DESIGN.md: Official Systems extracted from real open-source token packages with pinned provenance, and Brand Looks — independent, clearly-disclaimed analyses of the publicly observable visual language of famous product sites.