DESIGN.md Files Are Trending. Most of Them Aren't Yours
By The WAALEE Team · · 4 min read
A new convention spread fast this year: drop a file called `DESIGN.md` in your repo, and Claude, Cursor or Copilot reads it before touching a single component. It's a good idea. The problem is where most people are getting the file from, and it isn't their own site.
What DESIGN.md actually is
The format traces back to Google Stitch, Google's AI design tool, and it's just a markdown file: colors, typography, spacing, components, elevation, responsive rules, and a "do's and don'ts" section that acts as a guardrail. Markdown over raw JSON tokens is the whole point. A token file tells an agent `#1A1A2E` is a color. A DESIGN.md tells it that color is the dark background used behind hero sections and nowhere else, which is the kind of context a model actually needs to stop guessing.
Drop one in the project root, and tools like Claude Code or Cursor pick it up the same way they'd read a CLAUDE.md or a .cursorrules file. No MCP server, no plugin. That's why it caught on so quickly.
The catch: the popular ones are someone else's brand
The fastest way people are adopting DESIGN.md right now is pulling a ready-made one from a collection like awesome-design-md, which hosts dozens of files modeled on well-known products. You can grab a Stripe-flavored spec or a Linear-flavored one in seconds.
- Those files are reconstructions of public designs, not licensed exports. They're someone's interpretation of Stripe's palette, not Stripe's actual tokens.
- If your product has no real reason to look like Stripe or Linear, you've just traded one generic AI aesthetic for a different, equally generic one.
- Everyone pulling from the same 60-ish starter files ends up with the exact convergence problem DESIGN.md was supposed to fix, just one layer removed.
- None of it reflects your actual color choices, your actual type scale, or the spacing your own designer already settled on.
Where the real spec should come from
If you already have a live site, you don't need to borrow anyone's design language. It's sitting in your own CSS, computed and shipped: real hex values, a real type scale, real spacing. The honest DESIGN.md isn't downloaded, it's extracted from the thing you already built, then handed to the agent in the same markdown shape it expects.
Three ways people are feeding AI coding agents a design spec right now:
- getdesign.md: Home of the DESIGN.md format itself: one markdown file with colors, type, spacing and do's/don'ts that an agent reads before writing code.
- awesome-design-md: A big collection of ready-made DESIGN.md files inspired by Stripe, Linear and other known products. Fast to grab, not your brand.
- WAALEE: Extracts the real colors, type and spacing from your own live site and turns them into an AI-ready prompt, so the spec your agent reads is actually yours.
Putting it to use
Whichever way you get there, the mechanics are the same. Save the file as `DESIGN.md` in your project root. Open it with Claude Code, Cursor or whatever agent you're using and ask it to follow the spec exactly, including the do's and don'ts section. Regenerate it whenever your real site changes, since a stale spec drifts from your actual design the same way a stale Figma file does.
The format isn't the problem. A markdown file with your tokens and a few hard rules is a cheap, effective way to stop an agent from defaulting to the same hero-then-three-cards layout everyone else gets. Just make sure the file in your repo describes your site, not someone else's.