What Is DESIGN.md?

That is the short answer. The rest of this page covers where the format came from, how the two-layer file actually works, which tools read it today (and which need to be pointed at it), what it fixes, where it falls short, and how to ship your first file. For field-by-field syntax, see the full DESIGN.md spec guide.

What is a DESIGN.md file?#

A DESIGN.md file is a plain Markdown document, usually placed at the root of a repository, that acts as an agentic design system:

An agentic design system is a design system structured so that AI agents can read, interpret, and apply it autonomously: design tokens, component specs, and usage rules exposed as machine-readable context (via files like DESIGN.md or an MCP server) rather than as documentation written only for humans.

Here is a minimal, spec-valid example, YAML tokens on top, prose below:

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  md: 8px
---

## Overview

Architectural minimalism meets journalistic gravitas, a premium matte
finish, like a high-end broadsheet. The tertiary "Boston Clay" red is
the sole driver of interaction: buttons, links, critical highlights.
Everything else stays quiet.

An agent that reads this file knows the exact hex value of every color and the reasoning behind it: that red is reserved for interaction, so it will not paint a page header with it. Values without intent produce technically-correct-but-off UI; intent without values produces drift. DESIGN.md carries both.

The token layer isn't proprietary, either. It is inspired by the W3C Design Token Format, and the reference CLI exports it to Tailwind theme configs or DTCG tokens.json. The full syntax lives in our design.md spec reference.

Who created DESIGN.md?#

DESIGN.md comes from Google. It was reportedly introduced with the Stitch 2.0 "Vibe Design" update around March 19, 2026, as the persistence format for Stitch's generated design systems.

On April 21, 2026, Google open-sourced the format: the spec and a companion CLI landed in the google-labs-code/design.md repository under the Apache 2.0 license, with the CLI published to npm as @google/design.md. The format's declared version is alpha, and the spec, token schema, and CLI are explicitly "under active development."

The release cadence since open-sourcing (npm timestamps):

1. v0.1.0 / v0.1.1 (April 21, 2026): initial public release of spec + CLI
2. v0.2.0 (May 26, 2026): added the json-tailwind and css-tailwind export formats
3. v0.3.0 (June 15, 2026, current): added the unknown-key lint rule and slightly extended color parsing

Adoption is measurable outside Google, too: the community-run awesome-design-md collection lists 74 DESIGN.md files from real products as of July 8, 2026.

How does DESIGN.md work?#

The format is a deliberate two-layer model:

The spec itself puts it in one line: "The tokens are the normative values; the prose provides context for how to apply them." Put simply, clearly described intent shapes a generated design more than exact values do. In other words: the YAML keeps agents honest, the prose keeps them on-brand.

That division of labor tells you what belongs where. Exact values, every hex code, every font size, go in the YAML, because agents left to guess will fabricate plausible ones. Intent goes in the prose, and specific beats adjectival: a specific reference constrains an agent more usefully than a vague adjective, because it carries its own negative constraints for free. A design described as a 1970s university lecture handout constrains an agent far more usefully than "modern, clean, trustworthy, premium" (the specific reference rules out gradients and glow without needing to say so). The closing Do's and Don'ts section then adds explicit guardrails; 63 of the 74 community files include one.

The YAML supports a fixed set of top-level keys (version, name, description, colors, typography, rounded, spacing, components), where token groups are flat maps of names to values, and components can reference tokens with {colors.primary}-style paths. The Markdown body follows a canonical section order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Sections are optional, but the order is fixed. The full field-by-field reference lives in the spec guide.

Two practical conventions matter:

• Location: by convention the file lives at the repository root, next to README.md, AGENTS.md, or CLAUDE.md, where agents look for project-level context.
• Size: in our July 2026 analysis of all 74 files in the awesome-design-md collection, the median DESIGN.md is 546 lines, about 7,050 tokens. That fits comfortably into an agent's context window, which is the entire point of the single-file design. Full numbers are in our State of DESIGN.md study.

Which AI tools read DESIGN.md?#

Here is the part most explainers get wrong, so let's be precise: as of July 2026, only Google Stitch is reported to read DESIGN.md natively. Every other agent needs to be told the file exists, typically one line in the instruction file it does read automatically.

The wiring is one sentence. In CLAUDE.md or AGENTS.md, for example:

Before generating or modifying any UI, read DESIGN.md at the repo root
and follow its tokens and Do's and Don'ts exactly.

Because DESIGN.md is plain Markdown, any agent that can read a file can use it: there is no SDK, no plugin, no vendor lock-in. The trade-off is equally plain: nothing enforces it unless you add the reference and lint in CI.

What problems does DESIGN.md solve?#

Ask an agent to "build a settings page matching our brand" without persistent design context, and you get one or more of four failure modes:

1. Token fabrication: the agent invents plausible-looking values (#3B82F6, 8px radius) that aren't in your system.
2. Within-session drift: button styles mutate between the first and fifth screen of the same session.
3. Between-session amnesia: tomorrow's session re-derives the design from scratch and lands somewhere else.
4. Silent breaking changes: a regenerated component quietly drops your focus ring or swaps a font weight, and no diff catches it because the design was never written down.

DESIGN.md attacks all four with one mechanism: a canonical, versioned, diffable source of truth that travels with the code. Exact tokens prevent fabrication; the file's presence in context anchors a session; git history plus npx @google/design.md diff makes design changes reviewable like code changes. The diff command even exits nonzero when a change increases lint errors or warnings, a CI tripwire that silent breaking changes never had before.

Does it work? Atlassian's published test, after evaluating design context formats against their own design system, found that DESIGN.md produced strong one-shot prototypes, taking generated output "from generic 'slop' to something recognizably Atlassian" (Atlassian's post).

What are the limits of DESIGN.md?#

An honest explainer has to include this section, because the format is genuinely early:

• Coverage is shallow. In Atlassian's published test, DESIGN.md captured only about 30% of their design system, while their MCP server reached roughly 80% coverage. Using DESIGN.md as the sole context source also cost more, not less: it needed roughly 92% more tokens than the MCP approach for the same task. A single Markdown file cannot express a mature system's full component logic; it excels at one-shot visual fidelity, not completeness.
• It costs context. The median file is about 7,050 LLM tokens, and the largest community files run 10,000 to 11,000, paid on every request that includes the file.
• Nothing reads it automatically except Stitch (reported). Adoption depends on the one-line wiring shown above, and on your team keeping the file current.
• The format is alpha. Three versions shipped in the first eight weeks; the components section of the spec is explicitly still evolving.
• Quality in the wild is uneven. In our July 2026 analysis of all 74 files in the awesome-design-md collection, not a single file was lint-warning-free. Real-world usage patterns are covered in DESIGN.md examples.

If your main question is how DESIGN.md relates to the general-purpose agent instruction file, see DESIGN.md vs AGENTS.md: short version, they answer different questions and belong side by side.

How do I get started with DESIGN.md?#

Three steps, about fifteen minutes:

1. Start from a real example. Copy a file from a product with a similar aesthetic, our annotated DESIGN.md examples collection is sorted by style and stack.
2. Adapt or generate. Replace the tokens with your own values (your Tailwind config or CSS variables are the fastest source), then rewrite the Overview and Do's and Don'ts in your own voice, the prose is where the design lives. The step-by-step process is in how to write a DESIGN.md.
3. Validate before you commit. Run npx @google/design.md lint DESIGN.md to catch broken references and WCAG contrast failures, and paste the file into our free DESIGN.md viewer to see the design system rendered the way an agent parses it.

A shortcut for step 2: have the agent write the file itself, but teach it the format first. npx @google/design.md spec prints the specification precisely so you can inject it into an agent prompt.

Then add the one-line reference to your CLAUDE.md or AGENTS.md, and every UI task your agent runs starts from your design system instead of its imagination.

Next step: grab a starting point from our DESIGN.md examples, or paste any file into the viewer to see it the way an agent does. When syntax questions come up, the spec guide has the field-by-field answers.