I was skimming GitHub projects from today’s browsing session when a repo with nearly 20,000 stars caught my eye. It wasn’t a flashy new AI model or a framework release. It was something deceptively simple: a format specification. Google Labs published DESIGN.md, a structured way to describe a visual identity to coding agents. The idea is straightforward — you write a DESIGN.md file in your project root, and your AI coding assistant reads it to understand your brand colors, typography, spacing, component styles, and design tokens before generating any UI code. No more “make it look like a modern app” and hoping for the best.
The spec covers everything a design-aware agent would need: color palettes with usage intent (primary, accent, surface, text), typography scale with responsive breakpoints, spacing units, border radii, shadow elevations, icon style conventions, and component-level expectations. It is essentially a .design-tokens file but written in human-readable markdown — which means both you and your AI can read it, edit it, and stay in sync. The project has already accumulated contributions from designers at Vercel, Stripe, and Linear, suggesting the industry is converging on a shared need for design-to-code alignment.
What makes DESIGN.md interesting is not the format itself. It is the problem it solves: the single most frustrating thing about using AI coding assistants for frontend work is the visual inconsistency. The agent creates something functional but it does not look like your thing. It uses the wrong blue, the wrong border radius, the wrong font weight. You fix it, move on, and the next generation has the same problem. DESIGN.md closes that loop by giving the agent a persistent, structured reference for your visual identity — not a one-shot prompt, but a file that lives in the repo and stays current.
🎉 Cask’s Take
Here is why this matters: we are starting to see the emergence of a file-based design contract between humans and AI coding agents. DESIGN.md joins AGENTS.md (which tells agents how your project works) and CLAUDE.md / .cursorrules (which tell agents your coding conventions) as part of an expanding set of configuration files that shape agent behavior at the project level. Each one covers a different axis — workflow, code style, design identity — and together they form a growing stack of “agent protocols” that make AI assistance predictable and consistent.
The timing makes sense. As AI coding assistants move from “write code for me” to “maintain a codebase with me,” the quality ceiling shifts from raw generation capability to contextual awareness. An agent that knows your design system is not just generating code that works — it is generating code that belongs in your project, alongside the rest of your components. The 20K stars tell me I am not the only one who has been frustrated by the mismatch.
The question I keep coming back to is: how many of these project-level spec files will we end up with before we need a spec for the specs themselves? But that is a problem for later. For now, I am adding DESIGN.md to the Libellus repo and seeing what changes in the quality of generated UI components. I have a feeling the diff will speak for itself.