DESIGN.md measured: what the catalog gets right, what i...

A few months ago somebody had a very good idea. Instead of teaching an AI coding agent to design by describing what you want in a prompt every single time, write the design system down once as a markdown file, drop it at your project root, and let the agent read it. Google Labs published a draft specification for the format out of Stitch. A curated collection of them appeared on GitHub. In under five months that collection passed 109,000 stars.

The idea is right. I use a version of it every day. But I did what I always do before recommending something, which is measure it, and the measurement turned up a gap large enough to change how you should use these files.

Then I did the more useful thing, which is write the missing pieces. This post is both halves: what the DESIGN.md catalog actually contains, and the five-file kit that covers everything it does not, from search indexing through structured data through WCAG 2.2 AA through picking a host.

What a DESIGN.md is

A plain markdown file describing a visual system in enough detail that a language model can build UI from it. No tooling, no build step, no dependency. You copy one into your project root and say "build the pricing page using DESIGN.md."

It works because a design system is mostly prose and numbers, and prose and numbers are what these models are good at. A Figma file has to be interpreted. A markdown file with --accent: #533afd in it does not.

The reference collection is VoltAgent/awesome-design-md. Read off the GitHub API on August 24, 2026: 109,887 stars, 12,535 forks, MIT licensed, created March 31 2026, last pushed July 31 2026. The companion site is getdesign.md, run by the same team, which also built VoltAgent and Refine.

The catalog, counted

The site advertises 300-plus analyses. The repository, which is the part you can actually read and verify, contains 74 directories under design-md/. Each holds a DESIGN.md, a preview.html, and a preview-dark.html.

I downloaded all 74 and measured them.

Measure	Value
Files	74
Median size	28,200 bytes, about 546 lines
Smallest	4,336 bytes
Largest	43,867 bytes
Brands covered	AI platforms, developer tools, fintech, automotive, retail, media, plus a 1996 and a 2001 retro pair

These are not thin summaries. The median file is 28 KB of specific, structured description. That is real work, and the collection is genuinely useful as a starting point.

What is inside one

Every file opens with YAML frontmatter carrying a version marker, a name, a long prose description, then machine-readable colors: and typography: maps. Here is the shape, from the payments-brand file:

---
version: alpha
name: Stripi-Inspired-design-analysis
description: An inspired interpretation of Stripi's design language ...
colors:
  primary: "#533afd"
  primary-deep: "#4434d4"
  ink: "#0d253d"
  ink-mute: "#64748d"
  canvas: "#ffffff"
  canvas-soft: "#f6f9fc"
  hairline: "#e3e8ee"
typography:
  display-xxl:
    fontFamily: "sohne-var, 'SF Pro Display', system-ui, sans-serif"
    fontSize: 56px
    fontWeight: 300
    lineHeight: 1.03
    letterSpacing: -1.4px
---

Then nine markdown sections: Visual Theme, Colors, Typography, Layout, Elevation and Depth, Shapes, Components, Do's and Don'ts, Responsive Behavior, and an iteration guide for prompting. Colors are split into Brand and Accent, Surface, Text, and Semantic, each entry a bullet with a human name, a token reference, a hex value, and a sentence saying where it is used.

That last part is the good design decision in the whole format. A hex value alone tells an agent nothing. Ink Mute (#64748d): Helper text, captions, table labels tells it exactly where the color goes. Copy that habit into your own tokens.

The naming tell, and why it matters

Nineteen of the 74 files are named X-Inspired-design-analysis rather than X-design-analysis, and inside several of them the brand name itself is altered. The payments file calls the company "Stripi" throughout. The other 55 name the brand directly.

That inconsistency is the repository quietly acknowledging a real problem. These files describe real companies' visual identities. Using one to learn, or on an internal tool, is fine. Shipping a customer-facing site that reproduces a competitor's exact look invites trademark and brand-confusion trouble that has nothing to do with the license on the markdown.

The MIT license covers the file. It does not cover the trade dress the file describes. Take the structure, not the fingerprint.

What getdesign.md sells

The catalog is free to browse. The paid tier is a private DESIGN.md extracted from a website of your choosing, at $39 at the time of writing, listed as reduced from $59, one-time, no subscription. It includes light and dark themes, theme preview pages, and a private Discord channel. There is a $249 tier, listed as reduced from $299, that bundles a full starter codebase with authentication, payments, AI chat, blog, email and analytics.

I mentioned this service in passing in an earlier post about GitHub's 2026 star leaderboard and wrote at the time that the private option had no published price. It does now. That is the correction, and the price is fair for what it is.

Now the part I measured, which is the part that matters

I searched all 74 files for accessibility content. Here is what came back.

Check	Result
Files mentioning WCAG	54 of 74
Files mentioning contrast at all	55 of 74
Files stating a contrast ratio (4.5:1, 3:1, or 7:1)	0 of 74
Files naming a WCAG version or success criterion number	0 of 74
Files citing a 44 pixel touch target	65 of 74
Files citing the 24 by 24 pixel AA minimum	3 of 74
Files mentioning `prefers-reduced-motion`	0 of 74
Files mentioning a focus ring, focus state, or `:focus-visible`	25 of 74

Three of those rows deserve unpacking.

Fifty-four files invoke WCAG and none states a ratio. The word appears as a badge, almost always attached to touch-target sizing. An agent reading one of these files is told the palette is accessible and given no number against which to check that claim. "WCAG AAA" with no criterion attached is not a specification, it is reassurance.

The 44 versus 24 confusion is systematic. Sixty-five files cite a 44 pixel target. Some label it "WCAG AAA," which is correct: SC 2.5.5 Target Size (Enhanced) is Level AAA in WCAG 2.1. Others label it "WCAG AA (at least 44 by 44)," which is not correct. The AA requirement is SC 2.5.8 Target Size (Minimum), 24 by 24 CSS pixels, new in WCAG 2.2. Three files mention 24 by 24. Zero name either criterion by number. A design brief that hands your agent the AAA number while calling it AA is teaching it the wrong floor in both directions: too strict where it does not need to be, and silent about the one it actually has to meet.

Zero files mention reduced motion. Every one of them specifies transitions, easing and hover behavior. None specifies the prefers-reduced-motion block that turns those off for people who need them off. That is not a WCAG AA failure by itself, but it is a five-line omission repeated 74 times.

The palettes themselves

Text against surface is the check nobody skips and everybody fails, so I ran it properly.

I parsed the ## Colors section of every file, split the entries into text roles and surface roles by their own subsection headings, discarded border and hairline tokens (borders are held to 3:1, not 4.5:1) and inverse "on-dark" tokens (they pair with brand colors, not surfaces), then computed the WCAG contrast ratio of each remaining text token against every surface declared in the same file, keeping the most favorable result. Fifty-four files parsed cleanly, giving 231 text tokens.

Twenty-three of those 231 tokens, spread across 18 files, cannot reach 4.5:1 against any surface their own file declares. Ten percent.

Two examples so you can check my arithmetic:

In the workflow-automation brand's file, Mute is #c5c0b1, described as "lowest-priority text, fine print, low-emphasis captions." Against that file's own Canvas of #fffefb that is 1.8:1.
In the telecom brand's file, Body is #7e7e7e, described as "secondary body text on light surfaces, captions, metadata, supporting copy." Against #ffffff that is 4.06:1. Close, and still under the line.

A fairness note, because this matters. These are properties of an extracted markdown file, not audits of those companies' live websites. On the real site the same value may only ever appear at a size where the 3:1 large-text threshold applies, or in a context that is genuinely exempt. What I am measuring is what the file hands your agent, and what the file hands your agent is a token labelled for captions and body copy with no ratio attached and no surface constraint. The agent will use it wherever captions go.

That is the gap in one sentence: a DESIGN.md describes appearance beautifully and specifies almost nothing you can fail.

So write the other five files

DESIGN.md solves one layer. A shipped site needs five more, and every one of them is the same idea: plain markdown at your project root that the agent reads before it writes a line.

Here is the set I use, and what goes in each.

SEO.md

The rules that are verifiable from rendered HTML. Titles at 50 to 60 characters. Meta descriptions at 150 to 170 characters with a hard ceiling of 170, because past that Google truncates the part you wrote for the click. That number is not advice on my site, it is a build gate: audit-meta-descriptions.mjs --gate runs inside my deploy script and blocks the deploy on a single violation. A rule you enforce by hand is not a rule.

The sitemap section is where most generated sites quietly go wrong. lastmod has to be true. Emit it from a real dateModified field, never from the build clock. A sitemap where all 1,166 URLs changed today is a sitemap that stops being read. If a page has no modification date, emit its publish date, and if you have neither, omit lastmod entirely rather than invent one.

SCHEMA.md

Structured data, written as an entity graph rather than a pile of blocks. Give every recurring entity a stable @id and reference it by @id everywhere else.

https://example.com/#organization        Organization, site-wide
https://example.com/#person              Person, the author or owner
https://example.com/#website             WebSite, plus SearchAction
https://example.com/{path}#webpage       WebPage, one per page
https://example.com/{path}#breadcrumb    BreadcrumbList, one per page

On this site that graph currently produces 390 Person references, 386 SoftwareApplication, 349 BreadcrumbList, 160 WebPage, 81 matched Question and Answer pairs, and 22 Organization nodes across the templates, all pointing at the same handful of @id values rather than repeating anonymous copies.

The rule that took me longest to learn is worth stating flatly: emit exactly one page-type node per page. I used to ship a ProfilePage block alongside two anonymous WebPage blocks on the same URL. Three nodes competing to answer "what is this page." That was enough to break the binding between the person entity and the bio page it was supposed to anchor. One node, and Person.mainEntityOfPage pointing at that node's exact @id.

Two more that generic validators get wrong. FAQ parity is mandatory: every Question in your FAQPage must exist as visible text, worded the same way. And shipping and return fields belong on physical goods only, detected by the presence of gtin, mpn, isbn, productID or itemCondition. Adding them to a Service or LocalBusiness node is a false positive that a lot of tools will cheerfully recommend.

AEO.md

Answer Engine Optimization, meaning being retrievable and quotable by AI answer engines rather than only by search crawlers. The publishable surface is small and mostly one-time work:

/llms.txt and /llms-full.txt, /AGENTS.md, /feed.xml and /feed.json, /ai.txt, /.well-known/security.txt (RFC 9116), and /.well-known/api-catalog (RFC 9727). Then a markdown twin of every substantive page, advertised in the head:

<link rel="alternate" type="text/markdown" href="https://example.com/blog/slug.md" title="Markdown source">

If your host lets you negotiate content, serve markdown to Accept: text/markdown and set Vary: Accept on those responses. Skip the Vary header and a CDN will eventually collapse the markdown and HTML entries into one cache object, after which some visitors get markdown in a browser and some agents get HTML, at random, and it is miserable to reproduce.

On crawler posture, take an allow-list rather than a deny-list unless you have a reason. Blocking every AI crawler and then wondering why you are never cited in an AI answer is self-inflicted. Blocking them on purpose, because your writing is your product, is a legitimate business decision. Doing it by accident is the only wrong answer.

What actually makes a page quotable is simpler than the file list: answer the question in the first two sentences of the section, make each heading the question a person would type, put the number in the sentence rather than only in a chart, keep dateModified honest, and cite your sources with real links. Pages that cite get cited.

A11Y.md

This is the file that keeps a generated site out of trouble, and it is the exact hole the DESIGN.md catalog leaves.

Target WCAG 2.2 Level AA. Because 2.2 is backward compatible with 2.1, conforming to 2.2 AA covers 2.1 AA as well, with one exception worth knowing: SC 4.1.1 Parsing was removed in WCAG 2.2, because the failures it described are handled by browsers now. If a checklist still gates on 4.1.1, that checklist is 2.1-era and you can stop spending effort there.

The six criteria that are new at AA in 2.2 are the ones a generated site fails most often, because they describe patterns that are everywhere in modern layouts:

2.4.11 Focus Not Obscured (Minimum): a sticky header or a cookie banner must not fully cover the element that has focus. This is the most commonly introduced 2.2 failure, because sticky headers are the default in every template.
2.5.7 Dragging Movements: any drag interaction needs a single-pointer alternative.
2.5.8 Target Size (Minimum): 24 by 24 CSS pixels, with documented exceptions for inline links and essential controls.
3.2.6 Consistent Help: if a help mechanism appears on multiple pages, it appears in the same relative order.
3.3.7 Redundant Entry: do not ask for the same information twice in one process.
3.3.8 Accessible Authentication (Minimum): no puzzle, memory task or transcription without an alternative, and allow paste into password fields.

Around those sit the 2.1 AA criteria that carry forward. My own accessibility audit tool checks 37 distinct criterion and check-name pairs and marks 22 of them as critical AA failures rather than warnings, which is the split that matters when you are triaging: 1.1.1, 1.2.2, 1.3.1, 1.4.4, 2.1.1, 2.2.1, 2.2.2, 2.4.1, 2.4.2, 2.4.4, 2.4.6, 2.4.7, 3.1.1, 3.3.2 and 4.1.2 are the ones that break the page for somebody rather than merely degrading it.

And then the rules that stop an agent creating new problems: compute contrast rather than estimating it, never emit outline: none without a :focus-visible replacement, never let aria-label contradict the visible label (SC 2.5.3, which is what breaks voice control), never nest an interactive element inside another, never set tabindex above zero, and include a prefers-reduced-motion block in every stylesheet you generate.

DEPLOY.md

Where it lands, and what has to pass before it does. I re-read the three big free tiers this week rather than trusting what I remembered.

	Cloudflare Pages	Netlify	Vercel
Free tier shape	free plan	300 credits	Hobby
Builds	500 a month, 1 concurrent, 20 min timeout	credit-metered	100 deployments a day
Files per deploy	20,000	not published	not published
Max asset size	25 MiB	not published	not published
Custom domains	100 per project	included with SSL	50 per project
Requests	no published bandwidth cap on free	credit-metered	up to 1,000,000 edge requests
Redirects	2,000 static, 100 dynamic	`_redirects` or `netlify.toml`	`vercel.json`
Header rules	100 rules, 2,000 chars each	`_headers` or `netlify.toml`	`vercel.json`
Next tier up	Workers Paid $5/mo	Personal $9/mo, 1,000 credits	Pro $20/user/mo
Commercial use on the free tier	allowed	allowed	not allowed

That last row is the one that decides it for most small businesses. Vercel's own documentation states that the Hobby plan "restricts users to non-commercial, personal use only." A business site on Hobby is out of policy no matter how little traffic it gets. Cloudflare Pages and Netlify carry no equivalent restriction. If you are shipping something commercial and want to pay nothing, it is a two-horse race, and Vercel is the one you pay for.

Netlify has also moved to a credit model rather than published bandwidth and build-minute allowances, so the familiar "100 GB and 300 build minutes" framing no longer describes it. Free is 300 credits, Personal is $9 a month for 1,000, and the per-credit conversion is not on the pricing page. Budget by watching your first month, not by arithmetic.

Whichever you pick, put a gate in front of the build:

node predeploy-check.mjs && npx @11ty/eleventy

Fail the build on a meta description over 170 characters, a page with zero or two <h1> elements, a hero image path that does not exist on disk, an internal link to a URL not in the build output, a JSON-LD block that does not parse, a sitemap lastmod later than today, an image without width and height, or an outline: none with no :focus-visible nearby.

One hard-won note on gates: a gate that cannot find its target and passes anyway is worse than no gate. I shipped one of those. It searched for a marker string, never found it because the file was stored with different line endings, and printed "all blocks in sync" and exited zero for months. Every "not found" branch must increment an error counter and exit non-zero.

The whole thing as one file

All five blocks, plus a DESIGN.md template with the accessibility rules baked in and an AGENTS.md stub that points an agent at all of them, are in one downloadable file:

agent-site-standards-kit.md

It is free, needs no signup, and you are welcome to adapt it. Split it into five files at your project root, or leave it as one STANDARDS.md; agents read either shape. Fill in every FILL: marker, because an unfilled marker is the single most common reason an agent invents a value instead of using yours.

Then one prompt does the work:

Read STANDARDS.md. Build this site to it. Work presentation-only where the file
says presentation-only, keep every change additive and reversible, and verify
contrast by computation rather than by eye.

Do not take the agent's word for it

The failure mode with any of this is the agent reporting that it complied. Check with something that is not the agent. Every tool below runs in a browser, needs no signup and no account, and takes a ?url= parameter so you can run it directly.

What you want to know	Run
Everything in one pass: SEO, schema, E-E-A-T, voice, mobile, performance, accessibility, indexing, retrieval, plus a generated fix prompt	Mega Analyzer
Ranking authority, hygiene, AEO, performance, security, trust and compliance across seven parallel probes	Mega SEO Analyzer
Ten AEO probes: schema, attribution, retrievability, freshness, accessibility, tokenizer, prompt injection, AI-bot meta, speakable	Mega AEO Analyzer
Ten local probes: NAP consistency, LocalBusiness schema, service area, reviews, hours, geo, multi-location, categories	Mega GEO Analyzer
Seven security layers: TLS, post-quantum hybrid key exchange, HTTP security headers, SPF, DKIM, DMARC, CAA, CSP strictness	Mega Security Analyzer
Up to ten URLs side by side as a score matrix	Mega Batch
WCAG 2.1 and 2.2 AA, with critical AA failures separated from warnings	WCAG Accessibility Audit
Whether your FAQ schema matches the visible page text	FAQ Schema Parity
Whether your sitemap `lastmod` values are honest	Sitemap Lastmod Truthfulness
Whether your llms.txt matches the spec	llms.txt Quality Scorer
Whether an agent can actually use your site	Agent-Ready Audit

The full catalog is 346 tools: 266 audits, 43 generators and 37 utilities, all at jwatte.com/tools. Every one of them is free, runs in your browser, and stores nothing.

Four checks no tool will do for you, and all four take a minute:

Tab through the page without touching the mouse. Can you reach and operate everything, and can you always see where you are?
Set the page to greyscale. Does anything stop making sense?
Zoom to 200%, then set the viewport to 320 pixels wide. Does anything scroll sideways?
Read the generated copy out loud. If you would not say it, do not ship it.

Where this approach genuinely falls short

Markdown standards do not produce taste. I took apart seventeen expensive real estate sites recently and wrote up what actually made them expensive. The answer was seven numbers and a photography budget. A standards file can carry the seven numbers. It cannot buy the photography, and it cannot make the decision that the section gap should be 240 pixels rather than 96.

A file the agent reads is not a file the agent obeys. Long context degrades. The rules that survive are the ones that also exist as a gate: a script that exits non-zero, a test that fails, an audit you run afterward. Write the file for guidance and build the gate for enforcement, and never confuse the two.

Every number in the deploy table will drift. Free tiers change quarterly. Re-read the pricing page before you commit a client to one.

And the accessibility numbers here are a floor, not a finish line. Passing every automated check is roughly a third of the work. The rest is a keyboard, a screen reader, and somebody who actually uses one.

If you want the full version of this argument, from an empty domain to a working, accessible, indexed site for about a hundred dollars, that is what The $97 Launch covers chapter by chapter, including the WCAG, Schema.org and llms.txt material this post compresses into five files.

Fact-check notes and sources

Repository figures for VoltAgent/awesome-design-md, 109,887 stars, 12,535 forks, MIT, created March 31 2026, last pushed July 31 2026: read from https://api.github.com/repos/VoltAgent/awesome-design-md on August 24, 2026. Star counts drift daily.
The count of 74 directories, the median file size of 28,200 bytes and 546 lines, the range from 4,336 to 43,867 bytes, and every accessibility count in the table: computed locally after downloading all 74 DESIGN.md files from the main branch on August 24, 2026. Anyone can reproduce this by cloning the repo and grepping. The WCAG-mention count is a case-insensitive match on "wcag"; the ratio count is a regex for 4.5:1, 3:1 and 7:1; the reduced-motion count matches both prefers-reduced-motion and the phrase "reduced motion."
The contrast analysis: text and surface tokens were parsed from each file's ## Colors section by subsection heading, with border, hairline, divider and inverse "on-dark" tokens excluded, then each text token was scored against every surface in the same file using the WCAG relative-luminance formula, keeping the best result. 54 of 74 files parsed cleanly, yielding 231 text tokens, of which 23 across 18 files fell below 4.5:1 against every surface available to them. Files that did not parse used a different bullet format and were excluded rather than guessed at.
The two named token examples are quoted verbatim from the files' own descriptions. As stated in the post, they describe an extracted markdown file and are not an audit of any company's live website.
getdesign.md pricing of $39 for a private DESIGN.md and $249 for the starter kit, both one-time: read from getdesign.md/request on August 24, 2026.
The DESIGN.md format originates with Google Stitch; Google Labs published the draft specification in 2026 (Google Labs on DESIGN.md).
WCAG criteria, levels and version history: WCAG 2.2 at the W3C. SC 2.5.8 Target Size (Minimum) is Level AA at 24 by 24 CSS pixels and is new in 2.2; SC 2.5.5 Target Size (Enhanced) is Level AAA at 44 by 44 and dates to 2.1; SC 4.1.1 Parsing is marked obsolete and removed in 2.2. What's New in WCAG 2.2 is the short version.
Cloudflare Pages free-plan limits, 500 builds a month, 1 concurrent build, 20-minute timeout, 20,000 files, 25 MiB per asset, 100 custom domains, 100 header rules, 2,000 static and 100 dynamic redirects: Cloudflare Pages limits, read August 24, 2026. The page publishes no free-tier bandwidth cap.
Vercel Hobby terms including up to 1,000,000 edge requests, 100 deployments a day, 50 domains per project, and the quoted non-commercial restriction: Vercel Hobby plan, read August 24, 2026. The restriction is stated there and detailed in Vercel's fair-use guidelines.
Netlify free tier at 300 credits and Personal at $9 a month for 1,000 credits: Netlify pricing, read August 24, 2026. Netlify does not publish a per-credit conversion on that page.
Schema type counts, the 170-character meta-description gate, the one-page-node rule and the gate-that-passed-anyway story are all from this site's own build, and the audit tool's 37 criterion pairs with 22 marked critical are from /tools/wcag-accessibility-audit/.

This post is informational, not legal or accessibility-compliance advice. Automated checks cannot establish WCAG conformance on their own; treat them as a floor and test with real assistive technology. Mentions of the repositories, services, hosts and brands named are nominative fair use. No affiliation is implied, nothing here is sponsored, and I have no commercial relationship with any of them.

I Measured Every File In The 110,000-Star DESIGN.md Catalog. Fifty-Four Of Them Say "WCAG" And Not One States A Contrast Ratio.