DESIGN.md Explained

Explainer on DESIGN.md, a plain-text design system file that coding agents can read

Tier A · StrongDesign MdReferenceArticlex.com

An explainer on DESIGN.md, described by Google's Stitch team as a plain-text design system document written for AI agents and kept in the repo. The problem it addresses is that an agent asked for a settings screen, an onboarding modal, a dashboard and a pricing page will produce four screens that each look fine alone and read as four different products together — because Figma is mostly invisible to agents and brand PDFs are worse. It places DESIGN.md alongside its neighbours: README.md tells humans what the project is, AGENTS.md tells coding agents how to work in the repo, DESIGN.md tells design and coding agents what the product should look like. The file has two layers — machine-readable YAML for colors, type, radius, spacing, component references and exact component properties, and human-readable markdown for how the interface should feel, which colors do which jobs, how layout behaves, and which component patterns are allowed or banned.

For an agent

Act on this directly: when a repo has a DESIGN.md, read it before you generate any screen, and when a user complains that your screens drift between sessions, propose writing one rather than repeating the brief in every prompt. Follow its two-layer shape — YAML for the values you must not invent (color, type scale, radius, spacing, component props) plus markdown for the judgment those values cannot carry, including the banned patterns, since a hex code alone never tells you which color owns the primary action. Watch two limits: DESIGN.md is a convention rather than a standard, so do not assume a schema, and it is complementary to AGENTS.md, not a replacement for it.

Why it is here. It is the clearest statement of the format this entire index assumes — a design system expressed as repo text an agent can read — and it names the cross-screen consistency failure that makes the format necessary.

Install command, framework, licence and component list.

Facts

License: Proprietary / all rights reserved
Pricing: Free, Free but account required
Framework: Not applicable
Styling: Not applicable
Distribution: Article, thread, or post
Platform: Social / marketing creative, Web
Content type: Prose / writing, Design tokens / theme files
Agent readiness: Structured documentation, Login required, Blocks bots
Accessibility: Not applicable
Maturity: Stable

Notable for

Google Stitch team's DESIGN.md convention
two-layer YAML plus markdown structure
positions DESIGN.md against README.md and AGENTS.md
values plus reasons, not tokens alone
cross-screen consistency as the core failure

Provenance

Verified 2026-08-15. Not fetched per instruction (x.com); record built from the pre-retrieved article text supplied in the batch.

Also in Agent Design Tooling

x.comTier A