DESIGN.md
lastmod 2026-04-28created 2026-04-273 edits
I found the DESIGN.md format that Google Labs proposed in its Stitch project interesting, so I spent a few days digging through the spec, and since it felt like a waste to keep it to myself, I wrote it up in Korean as a 28-chapter curriculum. I worked on it with the idea that people studying the same topic wouldn't have to dig through the English spec from scratch, and that people who, like me, have the question "how do I get AI to read a design system?" could skim through it all at once.
DESIGN.md is a format that aims to express a design system in a single Markdown file. Values such as colors, typography, spacing, radius, and component tokens go in the YAML frontmatter in machine-readable form, and the Markdown below records design judgment criteria such as "why we use this color", "in what situations this button style is used", and "which patterns to avoid". In other words, it is not just a style guide but closer to a "source file of the design system" that AI coding agents such as Claude Code, Cursor, and Codex refer to every time.
Background
- Old question: "How do we organize our design system well in Figma?"
- Current question: "How do we get AI coding tools to read our design system?", "What is needed so that when building a new page, the AI follows our brand's color, spacing, and component rules?"
- Along with trends such as Claude Design, Claude Code, and Figma MCP, a shift in which the design system no longer stays only inside Figma but enters the codebase, gets reviewed in PRs, and becomes "persistent context" for AI agents
Core of the DESIGN.md format
- Dual structure of YAML (for machines) + Markdown (for people and AI) — tokens are parsed by machines, and the body is the layer where people leave the rationale for decisions
- Tokens are the answer, the body is the reason — it is neat that the priority of which one to trust when the two disagree is decided in advance
- Fixed order of 8 sections — the sections themselves, such as colors, typography, spacing, and components, serve as the mental model of the design system
- lint / diff / export / spec CLI — automatically checks items such as broken references, insufficient contrast ratio, orphaned tokens, and section order violations
- Interoperability policies with DTCG, Tailwind, and Figma variables are specified separately
Curriculum structure
- M1 Format philosophy · 3 chapters — the problem this format tries to solve, the dual structure, token/body priority
- M2 Token schema · 5 chapters — the whole schema / colors / lengths and units / fonts / token references
- M3 Section structure · 6 chapters — the order of the 8 sections and the design principles of each section
- M4 Reading real examples · 3 chapters — the Atmospheric Glass, Paws & Paths, and Totality Festival cases
- M5 CLI · 4 chapters — lint, diff, export, spec
- M6 Lint rules · 4 chapters — 8 rules including broken-ref, contrast, orphaned, and section-order
- M7 Extensibility · 2 chapters — policy for handling unknown content, relationship with DTCG and Tailwind
- Final summary · 1 chapter — summary of the 27 chapters + 10 principles to take into practice
Thoughts while writing it up
- I get the feeling that the more UI AI builds, the more important design systems will become, not less. The question seems to be shifting from "is AI good at design?" to "how clearly has the team left the criteria the AI should follow?"
- DESIGN.md is a practical attempt to keep those criteria inside the codebase rather than in Notion or PDFs. It also means that designers' deliverables become subject to review at the PR level
- I'm sharing this because I think it would be useful for people who are building a design system, or who have felt "why does the output come out different every time?" while building UI with AI coding tools. If there are parts I misunderstood or summarized wrongly, please let me know in the comments and I'll reflect them.