awesome-design-md is scaffolding, not a design system

VoltAgent's awesome-design-md repository, which has amassed 112,000 stars in five months, contains reverse-engineered design token files for brands like Stripe, Vercel, and Linear, but its value lies in the DESIGN.md format and worked examples, not in copying brand identities. Google Labs open-sourced the DESIGN.md spec in April 2026 under Apache 2.0, and its CLI (version 0.4.0) lints structure and WCAG contrast, but the spec remains alpha with expected breaking changes.

Dev Tools https://sourcefeed.dev/c/dev-tools Article awesome-design-md is scaffolding, not a design system The 112k-star pile of borrowed brand tokens pays off once you lint it and rewrite it as your own. Lenn Voss https://sourcefeed.dev/u/lennart voss Five months old, 112,000 stars, 74 folders. awesome-design-md https://github.com/VoltAgent/awesome-design-md is the fastest-growing repo I've seen in the "context files for agents" genre, and most of the people starring it will use it wrong. The files inside are reverse-engineered approximations of Stripe, Vercel, Linear, Apple and seventy other brands, written in Google's DESIGN.md format. The value is the format and the worked examples. The value is not "make my SaaS look like Linear," which is both the pitch and the trap. Where the format came from DESIGN.md is Google Labs' idea, not VoltAgent's. Stitch, Google's UI-generation tool, needed a way to pass a design system to Gemini as hard constraints rather than vibes, and in April 2026 the team open-sourced the spec https://github.com/google-labs-code/design.md under Apache 2.0. The design is a two-layer file. YAML front matter holds the tokens: colors , typography , rounded , spacing , and components that reference the others with {colors.primary} syntax. Below the fence, a Markdown body in a fixed section order Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts explains why the values exist and how to apply them. That split is the smart part. Token systems already existed: the W3C Design Tokens https://www.designtokens.org/ format, Style Dictionary, Tailwind theme configs. What they never carried was the rationale, and rationale is exactly what a language model needs to make the thousand small choices a token file doesn't cover. A hex value tells Claude what your accent is. "The accent is the sole driver for interaction; never use it decoratively" tells it when not to use it. DESIGN.md is the first mainstream attempt to ship both in one file the model can read without a parser. It also comes with tooling, which the awesome repo mostly doesn't mention. The @google/design.md CLI 0.4.0 at the time of writing lints structure and WCAG contrast, diffs two versions for regressions, and exports tokens to a Tailwind v3 theme.extend object, a Tailwind v4 @theme CSS block, or DTCG JSON. The spec is still labelled alpha and the maintainers say to expect breaking changes. What the repo adds, and what it doesn't VoltAgent, a TypeScript agent-framework company, took the format and wrote one file per brand by reading public CSS. The naming is careful: the Vercel one calls itself Vercel-Inspired-design-analysis , and the license section disclaims any ownership of the visual identities. These are interpretations, not vendor-published systems. Vercel has Geist; Stripe has its own internal tokens; neither shipped these files. The files themselves are serious work. The Vercel one runs 736 lines and defines 36 colors, 14 type scales, 12 spacing steps and 40 components, plus a Do's and Don'ts section with rules like "don't promote the geometric sans to weight 700; the brand's display ceiling is 600." That's the kind of constraint an agent will actually respect, and it's far more than a Figma export gives you. Several files go past the spec with extra sections Responsive Behavior, Iteration Guide, Known Gaps , which the spec tolerates since unknown headings are preserved rather than rejected. I ran Google's own linter across three of them. All three pass with zero errors, which means they parse and no token reference is broken. The warnings are where it gets interesting. Vercel's file throws 51: 25 orphaned colors never referenced by any component, and two dozen uses of borderColor , description and other sub-tokens the alpha schema doesn't recognize valid ones are backgroundColor , textColor , typography , rounded , padding , size , height , width . Stripe's pill-tag-soft lands at 4.23:1 contrast, under WCAG AA. Linear's primary-button hover state is 2.87:1. None of this is a bug in the repo so much as a snapshot of the real sites, but it means an agent following the file faithfully will ship contrast failures unless you gate on lint . How you'd use it Not the way the README says. "Copy it to your project root and tell your agent to use it" only works out of the box in Stitch. Claude Code https://docs.claude.com/en/docs/claude-code reads CLAUDE.md ; Cursor reads .cursor/rules ; neither loads a DESIGN.md on its own. You point at it: cp awesome-design-md/design-md/linear.app/DESIGN.md ./DESIGN.md echo "UI work must follow DESIGN.md. Tokens are normative; prose explains intent." CLAUDE.md npx @google/design.md lint DESIGN.md npx @google/design.md export --format css-tailwind DESIGN.md src/theme.css The export step is the one that makes this more than a prompt. Once the same tokens feed Tailwind https://tailwindcss.com/ via @theme and feed the model via the Markdown, the two can't drift, and design.md diff in CI catches a PR that quietly changes colors.primary . That beats the status quo, where the design system lives in a Figma file the agent can't see and a tailwind.config.js it edits freely. The trade-off is the context bill. The Vercel file is about 5,000 words, and the models that produce good UI are the expensive ones. On a large codebase you'll want to load it only for frontend tasks, or run export and hand the agent the compact @theme block plus the Do's and Don'ts section instead of the whole file. The part the star count hides Three things bother me about shipping one of these as-is. First, you're building a knock-off. A file that pins Stripe's purple, weight-300 type and gradient system produces a site that looks like Stripe. For an internal dashboard, fine. For a product with customers, you've bought a brand-confusion problem and skipped the only step that mattered, which is deciding what your product looks like. Second, the convergence risk is real. Seventy-four brand files and the top of the list is Claude, Cursor, Vercel, Linear, Supabase: the same dark-mode, tight-tracking developer aesthetic that every AI-built landing page already has. Feeding a generator more of the same makes the sameness worse. Third, the repo is a funnel. The README carries sponsor placements for two products from the same team and a paid "request a private DESIGN.md" service. That's legitimate, but it explains the growth curve better than the content does. Awesome-lists farm stars; this one just happens to contain useful files. Where this goes The format will outlive the collection. Google is pushing it through Stitch, there's an open request on Anthropic's skills repo to make the frontend-design skill read and write DESIGN.md, and Anthropic's own Claude Design builds a design system by reading your codebase and design files rather than a spec file. Whether the two vendors converge on one file or each keeps its own is the open question for the next year. My bet is on the file, because a plaintext contract that lints, diffs and exports is the kind of thing that survives vendor churn, the same way AGENTS.md did. So use the repo as scaffolding. Pick the file closest to your taste, run lint , delete every orphaned token, rename the brand, and then spend an hour rewriting the Do's and Don'ts to say what you mean. What you'll end up with is a 300-line document that's yours, and that's the thing the agents were missing all along. Sources & further reading - VoltAgent/awesome-design-md https://github.com/VoltAgent/awesome-design-md — github.com - google-labs-code/design.md: DESIGN.md format specification and CLI https://github.com/google-labs-code/design.md — github.com - Stitch's DESIGN.md format is now open-source https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-design-md/ — blog.google - Google's open-source DESIGN.md gives AI agents a prompt-ready blueprint for brand-consistent design https://the-decoder.com/googles-open-source-design-md-gives-ai-agents-a-prompt-ready-blueprint-for-brand-consistent-design/ — the-decoder.com - frontend-design: consider consuming/producing DESIGN.md per Google spec https://github.com/anthropics/skills/issues/1008 — github.com - Introducing Claude Design by Anthropic Labs https://www.anthropic.com/news/claude-design-anthropic-labs — anthropic.com Lenn Voss https://sourcefeed.dev/u/lennart voss · Cloud & Infrastructure Writer Lenn writes about cloud platforms, Kubernetes internals, and the infrastructure decisions that quietly make or break engineering organizations. Based in Berlin's vibrant tech scene, they have a talent for turning dense platform-engineering topics into prose that people actually finish reading. Discussion 0 No comments yet Be the first to weigh in.