# DESIGN.md Specification
DESIGN.md is an open Apache-2.0 format specification from [Google Labs](https://github.com/google-labs-code/design.md) for describing a design system to [[AI Agents|coding agents]] in a single, version-controllable file. It pairs **machine-readable design tokens in YAML front matter** with **human-readable design rationale in markdown prose** — so an [[Large Language Models (LLMs)|LLM]] can apply visual identity correctly instead of defaulting to generic UI.
It plays the same role for *design context* that `CLAUDE.md` / `AGENTS.md` plays for *engineering context*: a persistent, structured contract that survives sessions and follows the repo. Currently in **alpha**; the format, schema, and CLI are still moving.
Spec home: https://stitch.withgoogle.com/docs/design-md/specification — [[Google Stitch]] (Google's AI design tool) is the reference consumer.
## File anatomy
```
---
# YAML front matter — design tokens (machine-readable)
colors:
primary: "#1a3a52"
background: "#f7f3ec"
typography:
headline:
fontFamily: "Inter"
fontSize: 48
fontWeight: 700
spacing:
scale: [4, 8, 16, 24, 32]
---
## Overview <- markdown body — design rationale
## Colors
## Typography
## Layout
## Elevation & Depth
## Shapes
## Components
## Do's and Don'ts
```
The `##` headings are prescribed and ordered. Tokens cover colors (hex), typography (family/size/weight/lineHeight/letterSpacing), spacing, rounded-corner scales, and component-property mappings.
## Token categories
| Category | What it captures |
| ---------------------- | ---------------------------------------------------- |
| **Colors** | Hex palettes, semantic roles |
| **Typography** | Family, size, weight, line height, letter spacing |
| **Spacing** | Scale tokens for padding/margin/gap |
| **Rounded corners** | Radius scale |
| **Components** | Named components with property mappings |
## Why it matters
- **AI-native by design.** Like [[Tolaria]] for PKM or `CLAUDE.md` for engineering, DESIGN.md is part of the *plain-text-as-AI-contract* pattern: human-and-machine-readable, version-controlled, follows the repo.
- **Tokens + rationale together.** Pure tokens (Tailwind config, DTCG JSON) give *what*; markdown body gives *why*. Agents need both to make non-trivial design decisions.
- **Closes the design-to-code gap for agents.** Without it, agents fall back to generic Material/shadcn defaults regardless of brand. With it, "deep ink headlines, warm limestone background, Boston Clay CTAs" is reproducible.
- **Exportable.** Designed to feed downstream toolchains: Tailwind config, DTCG (W3C Design Tokens Community Group) format, etc.
## Audience
| Role | How they use DESIGN.md |
| --------------------- | ----------------------------------------------------------------- |
| **AI / coding agents** | Primary consumer — read tokens + rationale to generate UI |
| **Designers** | Author and own the file as the design system source of truth |
| **Developers** | Consume exported tokens (Tailwind, DTCG) and the components map |
## Status
- **Alpha.** Spec, schema, and CLI are under active development; format changes expected.
- **Apache-2.0** licensed.
- Backed by Google Labs / Stitch.
## Relation to other "AI-readable" specs
| Spec / file | Role |
| ------------------ | --------------------------------------------------- |
| **DESIGN.md** | Design system context for coding agents |
| **CLAUDE.md / AGENTS.md** | Engineering / project context for coding agents |
| **MCP servers** | Live, queryable context for any agent |
| **DTCG tokens** | Standardized design token interchange format |
DESIGN.md sits with CLAUDE.md / AGENTS.md in the *static, repo-resident, plain-text* context layer — complementary to [[Model Context Protocol (MCP)|MCP]]'s *dynamic, server-mediated* context layer.
## References
- https://github.com/google-labs-code/design.md
- https://stitch.withgoogle.com/docs/design-md/specification
## Related
- [[AI Agents]]
- [[Google Stitch]]
- [[Model Context Protocol (MCP)]]
- [[Large Language Models (LLMs)]]
- [[Tolaria]] — same plain-text-as-AI-contract pattern, applied to PKM
- [[Apache 2.0 License]]
- [[Yet Another Markup Language (YAML)]]