DESIGN.md, studied properly: the markdown file that keeps AI-built screens on-brand

Read time: ~5 minutes.

The two tools we have studied so far, Figma Make and Claude Design, share a failure mode: left to themselves, they produce the same template-flavored layout every prompt tool produces. This week we study the countermeasure that has quietly become a convention, a plain markdown file that tells the agent what your brand looks like before it draws a single box.

📐 The Study: DESIGN.md

What it actually is. DESIGN.md is a text file, kept in a project's repository next to README.md, that describes a visual identity in a form a coding agent can read: hard tokens (hex colors, type scale, spacing units, radii, shadows) and prose rules (what each color is for, what the brand never does). Google Labs introduced it inside Stitch, its AI UI-design tool, then on April 21 open-sourced the draft specification so the file could travel to any tool. The spec repository lays out eight sections (Overview, Colors, Typography, Layout, Elevation and Depth, Shapes, Components, Do's and Don'ts), mixes YAML tokens with markdown rationale, and states plainly that the format is at version "alpha" with the schema and CLI still moving. Google's own one-line pitch is the honest one: "instead of guessing intent, AI agents can know exactly what a color is for."

Where it fits in a real workflow. Picture a two-person studio building a client's dashboard with Claude Code or Cursor. Without guidance, every generated screen arrives in default-indigo with 8px radii on everything. With a DESIGN.md in the repo, the prompt becomes short ("build the pricing page, use @DESIGN.md for all styling decisions," in the example Banani's guide uses) and the output lands closer to the brand on the first pass, because the palette and type decisions were made once, in writing, by a human. Better Stack's guide shows the effect directly: the same generic dashboard, then restyled through a Stripe-flavored file and a Ferrari-flavored one. Their framing of why markdown works is worth keeping: it "sits at the intersection of what humans can comfortably write and what LLMs parse well." The file is also a portable artifact. Stitch exports it, Claude Design imports design systems from repositories, and awesome-design-md, a community collection of 73 files reverse-engineered from brand websites (Stripe, Linear, Vercel and others), sat at roughly 109,000 GitHub stars when we checked the API this week, created only at the end of March. That growth curve is the clearest signal that working teams wanted this.

Where it falls short. Four limits, one of them structural:

• It describes; it does not enforce. A DESIGN.md is an instruction, not a linter. Nothing in the format checks the generated CSS against the tokens, so drift is still possible on long sessions, and the designer remains the reviewer. Last week's AI in Design report named inconsistent output as the top complaint for 62% of designers; this file narrows that problem, it does not close it.
• The spec is alpha, and the "standard" is mostly convention. Google says so in its own README. A hands-on review on DEV put it more bluntly: "It's Google's convention and other tools happen to work with it because markdown is universal. No formal spec." Expect breaking changes.
• Borrowed brand files are CSS, not design systems. The awesome-design-md license is careful: the files "represent publicly visible CSS values" and the authors claim no ownership of any site's identity. A scraped Stripe palette gives you Stripe's colors, not Stripe's judgment, and shipping a client product in another company's exact identity is a different problem entirely.
• It cannot express the hard part. Tokens and do-not lists cover the surface. Information architecture, hierarchy across a multi-screen flow, when to break the grid: none of that fits in a table of hex values. Same conclusion as the last two studies, from the other side.

Who should care. Non-designer founders using coding agents: yes, today, it is the cheapest quality upgrade available, an afternoon's writing that pays on every future prompt. Product designers: yes, and write it yourselves rather than letting an extractor do it; the prose sections are where your taste survives the handoff. Brand builders: useful as a portable brand-kit format, with the caveat that the spec may shift under you before it stabilizes.

🗞️ The Digest

• Figma turns the agent into a skills marketplace. Figma's August release notes add more than 50 community-published "skills" for the Figma agent (Aug 13), let admins set per-user AI credit limits (Aug 5), and let external agents such as Claude, ChatGPT and Cursor run Weave tools over MCP (Aug 11). The credit-limit feature is the quiet admission that the meter we flagged in our first issue is now a management problem.
• Paper funds the code-native canvas. Paper raised $34M from Accel and ICONIQ (July 22), and its August build log ships comments addressed to teammates and agents, unlimited free editors for teams, desktop tabs, and tokens created in-app. Paper remains a recurring subject here; a full study is due once the token workflow settles.
• Firefly Image 3 leaves the building. Adobe's retirement notice confirms the model is "fully removed from service across all versions and plans" this month, with Image 4 and 4 Ultra as the defaults. If a studio's Photoshop actions depended on it, this is the week to find out.
• The role is widening, measured. Foundation Capital's essay on the AI in Design data (Aug 20) adds detail to the headline numbers we ran last week: 20% of respondents now call themselves "design engineers," 43% of companies expect working prototypes from designers, and 65% report taking on more PM and engineering work. The design-system-as-text trend in this week's Study is how a lot of that extra scope gets managed.

Have you written a DESIGN.md for a real project, or dropped a borrowed one in and regretted it? Reply with what the agent still got wrong. We are collecting the misses for a follow-up.

— The Editorial Team