The State of DESIGN.md

Key findings#

1. 0 of 74 files have lint errors. The community has internalized the hard rules of the spec: no broken token references anywhere.
2. 0 of 74 files are warning-free. The linter raised 1,341 warnings in total, a median of 16 per file.
3. 41 of 74 files (55%) fail WCAG AA contrast (4.5:1) in at least one component: 179 violations in total.
4. 684 color tokens are orphaned across 61 files: defined in the frontmatter, referenced by no component.
5. The median file costs roughly 7,000 tokens of context (546 lines, ~28,200 characters). The largest files approach 11,000.
6. 10 of 74 files ship no YAML frontmatter at all: they are pure prose documents, which agents can still read but tools cannot parse.
7. All 74 files follow the canonical section order. Structure compliance is essentially solved; token hygiene is not.

Every number in this article is reproducible by cloning VoltAgent/awesome-design-md and linting each file with the official CLI: npx @google/design.md lint DESIGN.md --format=json.

How we ran the analysis#

We cloned the awesome-design-md collection on July 8, 2026 (74 brand files, from Airbnb to Zapier) and linted every file with the official CLI:

npx @google/design.md lint DESIGN.md --format=json
# emits per-finding severity, path, and message, plus a summary: { errors, warnings, infos }

On top of the linter output we measured file size (lines, characters, a token estimate at ~4 characters per token), frontmatter field usage, token counts per group, and section structure. Every number in this article traces back to that command's output, run once per file.

What does a typical DESIGN.md look like?#

Two observations stand out.

First, real files are bigger than the examples in the spec suggest. Google's own spec examples run a few dozen lines; the community's median file runs 546. At ~7,000 tokens, a DESIGN.md is an affordable but noticeable share of an agent's context window: exactly the trade-off Atlassian's published test explored when it measured Markdown-based design context against an MCP server (see DESIGN.md vs MCP).

Second, structure is a solved problem. Every single file presents its sections in the canonical order the spec defines. The community treats the section order as settled convention: the linter's section-order rule found nothing to complain about.

Where do files go wrong?#

The 1,341 warnings concentrate in three failure patterns:

1. Contrast violations (41 files, 179 findings)#

More than half the collection defines at least one component whose textColor/backgroundColor pair falls below the WCAG AA minimum of 4.5:1. The worst offenders in our run: the Mintlify file (18 violations), Airbnb (15), MiniMax (13), MongoDB (10), and Miro (8).

Many of these look like faithful transcriptions of real brand colors: a white label on a brand-red button is a classic case. The linter flags it anyway, and for good reason: an agent that reproduces the token pair verbatim ships an inaccessible button. If the real brand accepts that contrast for large text or decorative use, the file should say so in prose; the Do's and Don'ts section exists precisely for such caveats.

2. Orphaned tokens (61 files, 684 findings)#

The median file defines 23 colors but wires only some of them into components. Tokens that nothing references are context an agent pays for without being told when to use them: the opposite of what the format is for. This tracks a broader point about the format: clearly described intent shapes a generated design more than exact values do.

Orphaned tokens are not always a mistake: a palette can legitimately document colors that only appear in prose guidance. But 684 of them across the collection suggests most are palette dumps, not intentional documentation. Our advice in How to Write a DESIGN.md follows directly from this number: extract the tokens you actually use, then cut.

3. Unrecognized component properties (20 files, 466 findings)#

The spec defines eight component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width. A quarter of the files use properties outside that list: most commonly description, borderColor, border, and shadow.

This is the most interesting finding in the dataset, because it is less a community error than a signal about where the spec needs to grow. Authors clearly want to express borders, shadows, and per-component annotations. The spec's own consumer-behavior table says unknown properties are accepted with a warning, so these files still work, but 466 findings are a feature request written in lint output. The components section of the spec is marked "actively evolving," and this is presumably why.

The long tail#

Ten files ship no YAML frontmatter at all, and three contain YAML the parser rejects on a syntax error (a malformed compact mapping in each case). That is a YAML-formatting problem, not a limit of the format: v0.3.0 supports nested token groups referenced with dot-separated paths. If you are hand-rolling a file, running npx @google/design.md lint DESIGN.md before committing catches all of this in seconds.

What this means for your DESIGN.md#

• Run the linter, expect warnings, and triage them. Zero errors is table stakes; the community achieves it universally. The warnings are where the quality signal lives.
• Check your component contrast pairs first. It is the most common failure (55% of files) and the one with real accessibility consequences.
• Delete or document orphaned tokens. If a color earns a place in your frontmatter, a component or a line of prose should say when to use it.
• Stay inside the eight component properties for now, and put borders and shadows into prose (the Shapes and Elevation & Depth sections exist for this). Watch the components guide: if the spec's property list grows, we will document it here.
• Budget roughly 7,000 tokens of context for a typical file, and read our writing guide if yours trends toward the 11,000-token ceiling.

Limitations#

This is a snapshot of one curated collection, taken July 8, 2026. The files skew toward well-known consumer brands and were largely community-authored, not published by the brands themselves, so the numbers describe the ecosystem's output, not official brand practice. Token counts are estimates (~4 characters per token). The linter version matters: we used the current 0.3.0, which added the unknown-key rule; older versions report fewer findings.

Want to see how your own file compares? Run it through the DESIGN.md Viewer: it renders your file as a browsable brand guideline right in your browser, with nothing uploaded, and lint it with npx @google/design.md lint DESIGN.md.