Your Brand Guidelines Were Written for a Reader Who No Longer Shows Up

You paid for brand guidelines. Somebody spent weeks on them. There is a grid, a type scale, a set of hexes with names, and three pages explaining when the logo gets clear space.

The agent building your screens has never opened that document and never will.

What changed

On 21 April 2026, Google Labs open-sourced the draft specification for DESIGN.md — a plain-markdown document that lives in your project and describes your design system in a form a coding agent reads before it generates anything.

Not a Figma export. Not a token JSON with a build step. A markdown file, in the repo, next to the code.

That is the whole idea, and the plainness is the point. Anything that requires tooling to consume is a thing the agent has to be taught to consume. Anything sitting in the project root as text is already in context.

There is a companion to it: VoltAgent/awesome-design-md (MIT, created 31 March 2026) collects ready-made DESIGN.md files extracted from real websites. The repo's own badge reports 73 of them. That number is the project's own count, not an audited figure — but the files are there to read, which makes the format copyable rather than something you have to invent from a spec.

Why it matters

Here is the mental model worth replacing.

Brand guidelines were written to be interpreted. A designer reads "confident but approachable," looks at the examples, absorbs the intent, and makes a hundred small judgment calls that were never written down. That works because a human carries the document's spirit into decisions the document never anticipated.

Agents do not interpret. They pattern-match against whatever is in context. Supply nothing and they fall back on the average of their training data, which is a real aesthetic — it is just everyone else's.

So the failure mode isn't that your screens look bad. It's that they look plausible and slightly wrong, and differently wrong each time.

Drift is the tell. Generate one screen. Generate another. The button radius is 8px, then 6px. The section spacing is 64, then 48. The blue is close to your blue. Ten screens in, nothing lines up, and no single generation was obviously broken — which is exactly why nobody caught it at screen three.

That drift has a cause: nothing in the loop is authoritative about what "correct" looks like. Each generation re-decides.

Two files, two readers

The clean way to hold this:

• AGENTS.md governs how the thing gets built — commands, conventions, structure, what not to touch.
• DESIGN.md governs how it should look — palette, type, spacing, component behaviour, tone.

Different questions, different documents, both consumed by the same agent at the same moment.

Most projects have neither. Plenty of teams have adopted AGENTS.md over the past year and stopped there, which leaves the build governed and the appearance improvised.

Proof and limits

What is solid: Google Labs published the draft spec on 21 April 2026, on Google's own blog. The spec calls for validating colour choices against WCAG AA/AAA contrast — worth flagging because it means the file is not purely descriptive; it carries an accessibility check into the generation step, which is earlier than most teams run one.

What is softer: it is a draft specification, not a ratified standard, and it is roughly four months old. The 73-file count in awesome-design-md is self-reported by that repo. And nobody has published evidence on how much a DESIGN.md actually reduces drift in practice — the argument for it is mechanical, not measured.

That is enough to act on, and not enough to treat as settled.

What to actually do

1. Write a DESIGN.md and commit it to the repo root. Next to AGENTS.md. Start with what you already have written down somewhere else.
2. Pull one from awesome-design-md first and read it before writing yours. The value is seeing the shape — what gets specified, at what granularity, in what order.
3. Write it for a reader with no taste and no memory. Not "clean and modern." A number, a hex, a rule, an example of the wrong thing. Every place you would have relied on a designer's judgment is a place the file has to be explicit.
4. Check the contrast pairs while you write it, since the spec asks for it and it is cheaper here than in review.
5. Then run the drift test. Generate five screens off it. If the radius still wanders, the file is underspecified in exactly the place it wandered — which is useful information, and the loop you want.

Four questions, honestly answered

What is confirmed. Google Labs open-sourced the DESIGN.md draft spec on 21 April 2026. The spec includes WCAG AA/AAA contrast validation. awesome-design-md exists, is MIT-licensed, and holds a collection of extracted DESIGN.md files.

What is still unknown. Whether the format converges on a standard or fragments the way early config formats usually do. Whether major agent harnesses read it by convention or need to be pointed at it. How much drift it actually eliminates, measured rather than argued.

Why it is worth watching. This is the moment brand assets stop being human deliverables and start being machine inputs. If that holds, the agency deliverable changes shape — the PDF stops being the artifact and the repo file becomes it.

How it fits the larger ecosystem. It sits in the same lineage as AGENTS.md and llms.txt: plain text in a known location, aimed at a machine reader, no tooling required. That pattern keeps winning, and it keeps winning for the same reason — zero adoption cost.

The part that stays true

A brand that only exists in a document nobody in the build loop reads is a brand that will be approximated.

The test is short. Does your brand exist in a file an agent can read? If the answer is a PDF, the answer is no.

---

Sources

• Google Labs — Stitch and the DESIGN.md specification
• VoltAgent/awesome-design-md