This week, a quiet format proposal started circulating through developer chat rooms and AI agent Discord servers. It's called DESIGN.md, and it comes from Google Labs' Stitch project. The idea is deceptively simple: represent an entire design system in a single markdown file. Colors, typography, spacing, border radius, component tokens — all live in YAML frontmatter, machine-readable by design. Below that, in plain markdown, you write the reasoning: why this shade of blue, when to use that button style, which patterns to avoid. The token values are the answer; the markdown is the justification. And when the two conflict, the format forces teams to decide which one wins, ahead of time.
YAML for Machines, Markdown for Humans and AI
DESIGN.md is built as two layers stacked in one file. The YAML frontmatter holds token values that any tool can parse directly — hex codes, font sizes, spacing units, radius values. The markdown body below it carries the design rationale: the context, the edge cases, the rules of thumb that a human designer would explain in a handoff meeting. The format prescribes exactly eight sections in a fixed order: colors, typography, spacing, components, and so on. Each section functions as a mental model for the design system itself. A CLI tool ships alongside the spec, offering four commands: `lint`, `diff`, `export`, and `spec`. It automatically checks for broken references, insufficient contrast ratios, orphaned tokens, and section order violations. The spec also documents interoperability policies with DTCG (Design Token Community Group), Tailwind, and Figma variables.
The Old Question vs. The New Question
A year ago, the question teams asked was: "How do we organize our design system inside Figma?" Today, the question has shifted: "How do we make sure AI coding tools read our design system correctly?" When Claude Code, Cursor, or Codex generates a new page, it needs to follow the brand's colors, spacing, and component rules. That requires a reference point that lives in the codebase, not in a Figma file or a PDF. The rise of Claude Design, Figma MCP (Model Context Protocol), and AI-driven PR reviews means design systems are no longer static artifacts. They become continuous context that AI agents carry from session to session. DESIGN.md is a practical attempt to anchor that context in a single, version-controlled file.
The most immediate change developers will feel is where the design system lives. It moves out of Notion docs and PDF exports and into the repository itself. That also means a designer's output becomes reviewable at the PR level — a shift in workflow that has implications for how teams collaborate. As AI generates more UI, the design system paradoxically becomes more important. The bottleneck is no longer "Can AI design well?" but "How clearly has the team documented the rules the AI must follow?"
A 28-Chapter Curriculum in Seven Modules
A full 28-chapter curriculum has been published in Korean, organized into seven modules. M1 (3 chapters) covers the format philosophy: the problem it solves, the dual structure, and the priority rules between tokens and prose. M2 (5 chapters) dives into the token schema: the full schema, colors, lengths and units, fonts, and token references. M3 (6 chapters) explains the eight-section structure and the design principles behind each section. M4 (3 chapters) walks through three real-world case studies: Atmospheric Glass, Paws & Paths, and Totality Festival. M5 (4 chapters) covers CLI usage for `lint`, `diff`, `export`, and `spec`. M6 (4 chapters) details eight lint rules: broken-ref, contrast, orphaned, section-order, and others. M7 (2 chapters) addresses unknown content handling policies and the relationship with DTCG and Tailwind. A final chapter summarizes all 27 preceding chapters and distills ten principles for practical adoption.
If DESIGN.md becomes the single reference point that AI coding tools read, then UI consistency stops being a technical problem and becomes a documentation problem — one that any team can solve with a single file and a clear set of rules.
bash
Example: lint your design system
npx @google-stitch/design-md lint ./DESIGN.md
Example: diff two versions
design-md diff ./DESIGN.md ./DESIGN.md.v2
Example: export tokens to Tailwind config
design-md export ./DESIGN.md --format tailwind
yaml
Example DESIGN.md frontmatter
---
colors:
primary: "#1a73e8"
secondary: "#34a853"
background: "#ffffff"
typography:
font-family: "Inter, sans-serif"
font-size-base: "16px"
spacing:
unit: "8px"
scale: [4, 8, 12, 16, 24, 32, 48, 64]
radius:
sm: "4px"
md: "8px"
lg: "16px"
---
The format is open, the CLI is available, and the curriculum is free. The question now is whether teams will adopt it before their AI agents start guessing.
