Something landed in Google Labs this week that’s going to make a lot of frontend devs nod slowly.
It’s called DESIGN.md. And while the name sounds unremarkable, the Redditor who surfaced it in r/PromptEngineering nailed the actual problem it solves: every time you spin up a new AI coding session, the assistant starts from zero. It doesn’t know your brand colors. It doesn’t know your font stack. It doesn’t know why you use that specific shade of red for primary CTAs and not for secondary buttons. So it guesses. And the guess is almost always the same default Tailwind blue.
The author put it plainly: the AI isn’t broken. The context is just missing.
What DESIGN.md Actually Is
Think of it as a README.md, but built specifically for your design system. You drop a single DESIGN.md file in your project root. It has two layers that work together.
The YAML layer carries machine-readable specs. Exact hex codes, font families, spacing scales, border radius values. The numbers your AI agent needs to stop guessing.
The Markdown layer carries the rationale. Not just “#B8422E,” but “use #B8422E only for primary interactive elements.” The prose tells the model why those values exist and when to apply them, which is exactly the kind of judgment context that raw tokens can’t capture.
When Cursor, Claude Code, or GitHub Copilot picks up a task, it reads the file first. Builds on-brand from the start. No more “match the existing style” prompts that produce generic output because the model is inferring rules from scattered examples across the codebase.
There’s also a CLI bundled with the spec. It lints the file, checks WCAG contrast ratios automatically, and can export your tokens directly to a tailwind.config.js. More on that below.
The Twist
Here’s the part worth sitting with: the AI was never the bottleneck.
A commenter in the original thread put it sharply: “most agent failures aren’t capability gaps, they’re context gaps.” The model has always been capable of generating on-brand UI. It just had no persistent access to your brand specification. Every conversation started cold. Every output was a best-guess reconstruction.
DESIGN.md doesn’t add new model capability. It adds structured, persistent context that lives in the repo and gets read automatically. That’s the insight, and it’s deceptively simple.
It also generalizes far beyond UI work. Any time an agent is making decisions based on vague instructions or inferred patterns, you have a context gap. Explicit, structured files beat vague prompts. The same principle is already behind CLAUDE.md and .cursorrules. DESIGN.md extends that pattern to design systems and formalizes it with a standard schema, a lint tool, and accessibility checks.
How to Set It Up
- 🔧 Get the file. Use a template from the official Google Labs repo, or generate a starter automatically using Google Stitch if you’re already in their design toolchain.
- 🎨 Add your YAML tokens. Hex codes, font families, spacing scale, shadow tokens. Be specific: “use #B8422E for primary interactive elements” beats “red for CTAs” every time, because the model has something concrete to apply rather than something to interpret.
- 📝 Write the Markdown rationale. Explain the why, not just the what. This is the layer that helps the model handle edge cases the numbers don’t explicitly cover.
- ⚡ Run the CLI. Lint the file, check WCAG contrast automatically, and export tokens to
tailwind.config.js. One source of truth. No duplicate maintenance between the design spec and the Tailwind config.
Pro Tips
Don’t stop at colors. Your spacing scale, border radius system, and shadow tokens all belong in the YAML block. The more explicit the spec, the more consistent the output. The more consistent the output, the less time you spend prompting corrections on the third iteration.
Check this into version control and treat it like infrastructure, not a one-time setup. When the design system changes, the file changes with it. Every agent that reads the repo benefits automatically.
If you’re already injecting design constraints into .cursorrules or CLAUDE.md, DESIGN.md is a natural next step. Same habit, standardized format, with actual tooling behind it.
Why This Will Catch On
The r/PromptEngineering community is already debating whether a standardized format like this will become universal across toolchains. My read is yes, and the reason is structural: the cold-start problem affects every AI coding assistant across every codebase. Any solution that lives in the repo and travels with the code has a natural adoption advantage over prompt-based approaches that vanish when the session ends.
The trend is clear. Structured context files in the project root are becoming the standard way to communicate constraints to AI agents. Not just for code style, but for brand, architecture, and business rules. DESIGN.md is just the latest addition to that stack.
🔗 The spec, CLI documentation, and GitHub repo are all linked in the original r/PromptEngineering thread. Start with the template, run the CLI once, and see how different your first on-brand component output looks.
Frequently Asked Questions
Q: Why does DESIGN.md work better than just asking the AI to “match the existing style”?
Models infer rules from code examples and guess wrong. DESIGN.md states the rules explicitly, so there’s nothing to infer – the model reads the constraints directly. Explicit rules compound consistency; vague prompts don’t.
Q: Can I use this pattern for things beyond UI, like rules or architecture?
Yes, the insight applies broadly. Whether it’s design tokens, behavioral rules, or architectural constraints, explicit files beat vague prompts because LLMs can’t remember implicit context across interactions. CLAUDE.md uses the same pattern for non-design stuff.
Q: Will DESIGN.md become the standard format, or just one of many?
That’s the open question. The pattern (explicit + machine-readable) is proven; whether Google’s specific format wins adoption is another story. Some teams might build on it; others might stick with existing tools. The key is committing your constraints to a file, whatever format you pick.
Q: What’s the real bottleneck – is AI not smart enough, or missing context?
Mostly context. Agent failures are usually context gaps (missing architectural knowledge), not capability gaps. DESIGN.md closes the context gap without making the model smarter. When agents know what they’re supposed to build, they build it right.
Q: How is this different from .cursorrules or CLAUDE.md?
Same principle, different focus. All three are explicit files that beat vague prompts. DESIGN.md optimizes for design tokens (tokens + rationale in YAML/Markdown), while .cursorrules and CLAUDE.md handle general rules and behavior. Pick what fits your use case; the pattern matters more than the format.
Google Labs just open-sourced DESIGN.md so your AI agents stop guessing your brand colors
by u/Exact_Pen_8973 in PromptEngineering