DESIGN.md files measured: 84 brand files against Google's spec, and what Claude Code does with one

Summary

If you want Claude Code to build in a specific brand’s look, put that brand’s DESIGN.md in the folder and tell it to follow the file. Naming the brand is not enough. Check the file’s contrast first, and expect each session to cost more.

The reason is simple: we measured both the files and the result. We checked the 84 DESIGN.md files in awesome-design-md against Google’s DESIGN.md spec, then had Claude Code on Haiku build 54 pages for Airbnb, Stripe and Jobright three ways: with no brand, with only the brand name, and with the brand’s DESIGN.md:

• The file works. With it, the median page took 100% of its colors from the brand’s palette, and every page used the primary color and named the brand font. All 18 runs read the file first.
• A name gets a guess. With only the name, 25% of colors matched. For Airbnb, the model knew the red and used it in 5 of 6 pages. For Stripe it used #635bff from memory every time, while the file specifies #533afd. For Jobright, a smaller brand, it fell back to generic grays.
• The files are long. The median brand file is 28,200 characters, about 7,000 tokens, three times the size of Google’s own examples. Runs with the file cost 2.8 times as much as runs with no brand.
• Some colors fail contrast. In 33 of the 71 files with color tokens, at least one text-on-background pair is below the 4.5:1 that the spec’s own guidance asks for. A few pairs set text and background to the same color.

Our picks

1. Use a DESIGN.md when the brand is not famous or the palette must be exact. The model’s memory covers big brands loosely and small ones not at all. The file is what makes the colors exact.
2. Check every text and background pair before you hand the file to an agent. The agent copies the file faithfully, mistakes included. Google’s design.md project includes a linter, and any WCAG contrast checker works. Treat a pair under 4.5:1 for normal text as a bug.
3. Watch the size. Every session that follows the file reads all of it. Google’s three examples run about 2,200 tokens each; the median brand file runs 7,000. If you write your own, start from Google’s examples, not from the longest file you can find.
4. Write tokens, not only prose. 71 of the 84 files put colors and type in YAML, the way the spec does, and 73 use all eight of its sections in order. Tokens give the agent exact values to copy, which is why the file arm hit the palette.
5. Use the spec’s color names if you want tools to read the file. The spec recommends names such as primary, surface, on-surface and error. The brand files use a median of one of those seven; the rest are names like ink or canvas.

Does your project already have a CLAUDE.md or AGENTS.md that says how the UI should look? A DESIGN.md is the same idea, kept in its own file. Our CLAUDE.md and AGENTS.md study shows how those get read.

How we tested

1. The files. All 84 DESIGN.md files in VoltAgent/awesome-design-md (MIT), read on November 7, 2026. Each one describes a well-known brand’s design system.
2. The spec. Google’s DESIGN.md spec, version alpha (Apache-2.0): eight sections in a set order (Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts), tokens in YAML front matter or YAML blocks, and recommended token names.
3. Contrast. For every component token with both backgroundColor and textColor, we resolved references such as {colors.primary} to hex and computed the WCAG contrast ratio. We left out disabled states, which WCAG exempts, and non-text parts such as dividers, rings and icons. That left 1,438 text pairs.
4. The test. Three brands with distinct palettes (Airbnb, Stripe, Jobright), three pages (a pricing page, a sign-up form, a landing hero), three arms, two runs each: 54 fresh claude -p sessions on Claude Code 2.1.314 with --model haiku. Only the Read tool was allowed. Each answer was one HTML file.
5. Scoring. We collected the distinct hex colors in each page and counted the share that appear among the brand’s DESIGN.md color tokens, whether the brand’s primary color appears, and whether the brand’s first font family is named.

Results

The 84 files against the spec

	Brand files	Google’s examples (3)
Median length	28,200 characters, about 7,050 tokens	8,660 characters, about 2,165 tokens
Colors and type in YAML tokens	71 of 84	3 of 3
All eight spec sections, in order	73 of 84	7 of 8 sections each
Median color tokens	23	47
Spec’s recommended color names used, median	1 of 7	6 of 7
Common extra sections	Responsive Behavior (61), Iteration Guide (50), Known Gaps (43)

Text on background, 1,438 pairs in 71 files

	Pairs	Files with at least one
Below 4.5:1	77 (5%)	33
Below 3:1	24
Text and background the same color	3	3

The lowest pairs are in components like a featured pricing tier or a marketing hero, where text and background resolve to the same token. That looks like a mistake in the file rather than a design choice, and an agent following the file will reproduce it.

What Claude Code did with each arm, 18 pages per arm

	No brand	Brand name only	DESIGN.md
Colors from the brand palette, median	9%	25%	100%
Brand primary color used	0 of 18	5 of 18	18 of 18
Brand font named	0 of 18	0 of 18	18 of 18
Median output tokens	2,689	4,259	7,240
Cost, 18 runs	$0.052	$0.067	$0.147

By brand, colors from the palette, median

	No brand	Brand name only	DESIGN.md
Airbnb	9%	65%	100%
Stripe	10%	25%	97%
Jobright	9%	9%	100%

The no-brand matches are white, which every palette contains. With Airbnb’s name the model reached for Circular, the brand’s older typeface, which the file lists only as a fallback behind Airbnb Cereal. With Stripe’s name it chose the familiar blurple and navy every time; the file’s analysis gives a different violet. We cannot say which one Stripe uses today; only the file arm used the file’s value.

What to ignore

• The number of files in a collection. A gallery of 84 or 759 files says nothing about whether any one of them is correct. Check the one you use.
• Style adjectives. The files open with long descriptions of mood. The agent copied the YAML values; we did not measure whether the prose changed anything.
• Font matches as rendering. Naming a brand font in CSS does not load it. Most brand fonts are licensed, so the page falls back to the next font in the stack unless you host it.

Limitations

• Three brands, three pages, Haiku. A larger model may know more brands from memory, which would narrow the name-only gap.
• Palette share counts exact hex matches. A page could use a near-identical shade and score as a miss.
• The brand files are third-party analyses. They describe how each brand looked to the author, not an official spec from the brand.
• Contrast covers component tokens only. Text colors described only in prose were not checked.

Reproduce it

The scripts are design-md-files-2026-11-catalog.py, which measures a folder of DESIGN.md files against the spec, and design-md-files-2026-11-test.py, which runs the 54 pages with Claude Code and scores them. The data, design-md-files-2026-11.json, has every file’s measurements and contrast pairs, Google’s three examples, and every test run.

Sources

1. google-labs-code/design.md: the DESIGN.md spec · official
2. VoltAgent/awesome-design-md · official
3. W3C: WCAG 2.2 contrast minimum · official
4. AgentCraft: CLAUDE.md and AGENTS.md in 5,864 repos · blog