There’s a specific frustration every dev who’s used code agents knows well: you ask the agent to build a feature, it works perfectly at a functional level, and then you look at the UI and it looks like it was designed by a committee in 2009. Wrong colors, inconsistent spacing, fonts that don’t match anything else in the project.
The agent understood the logic. It had no idea what your design system looks like.
That’s the problem awesome-design-md solves, and the approach is so simple it seems obvious in retrospect: drop a DESIGN.md file in the root of your project and tell your agent to use it.
What is DESIGN.md?
DESIGN.md is a plain text format introduced by Google Stitch for communicating design systems to AI code agents. Think of it as the design equivalent of AGENTS.md:
| File | Who reads it | What it defines |
|---|---|---|
AGENTS.md |
Code agents | How to build the project |
DESIGN.md |
Design agents | How the project should look and feel |
The logic is straightforward: markdown is the format LLMs read best. No parsing, no tooling, no Figma exports, no JSON schemas to configure. You describe your design system in natural language with structured sections, and the agent actually understands it.
What awesome-design-md offers
The VoltAgent team took this format and did the tedious work for you: they reverse-engineered the design systems of over 55 popular products from their public CSS and documented everything in DESIGN.md format.
The repository launched on March 31, 2026 and accumulated over 4,400 GitHub stars in its first days.
The collection covers a wide variety of products:
- Dev tools: Stripe, Vercel, Linear, Raycast, Sentry, PostHog, Resend, Mintlify
- AI Platforms: Claude (Anthropic), Cursor, Lovable, VoltAgent, Replicate, RunwayML
- Productivity: Notion, Airtable, Zapier, Superhuman
- Infrastructure: MongoDB, HashiCorp, Sanity, ClickHouse
Each folder contains three files: a DESIGN.md with the complete design system specification in markdown, a preview.html with a visual component catalog in light mode, and a preview-dark.html for dark mode surfaces.
What’s inside a DESIGN.md?
The depth of these files is what makes the approach work. The Stripe DESIGN.md, for example, doesn’t just list colors — it documents why the decisions exist:
Stripe uses weight 300 as the signature weight for its titles — an extraordinarily light choice in a world where everyone uses 600–700 to grab attention. The multi-layer shadow system uses a primary shadow with blue tint (rgba(50,50,93,0.25)) combined with a darker layer, creating shadows with atmospheric depth directly tied to the brand’s navy-purple palette.
A typical DESIGN.md includes:
- Visual theme and atmosphere — the overall design philosophy in prose
- Complete color palette with semantic role names, not just hex values
- Typographic hierarchy — each size, weight, letter-spacing, and line-height
- Component styles with hover, active, and disabled states
- Layout principles and spacing rules
- Elevation system — how shadows communicate depth
The result is a document that gives an AI agent the same context a senior designer would give a junior dev in a detailed handoff.
How to use it
Three steps:
1. Download the DESIGN.md from the system you want to use:
# Stripe design system
curl -O https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/stripe/DESIGN.md
# Vercel design system
curl -O https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/vercel/DESIGN.md
# Linear design system
curl -O https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/linear/DESIGN.md
2. Drop the file in your project root (at the same level as your CLAUDE.md or AGENTS.md)
3. Reference it in your agent prompt:
Build a pricing card component using DESIGN.md as a visual guide.
Make it match the design system exactly.
That’s it. Your agent now has the complete design context it needs.
Works with any agent
The format is completely model-agnostic. It’s formatted specifically for AI code agents to interpret and implement — Claude Code, Cursor, GitHub Copilot, and Codex CLI all understand plain text format natively.
If you’re building a new project and want it to look like a specific product — say, you want your internal tool to have the black-and-white precision of Vercel — you now have a reusable design specification ready to drop in.
The growing ecosystem
The design-md format has already spawned related tools: a Figma-to-DESIGN.md converter that extracts design tokens from Figma files, a web scraper that distills any website’s design system into a DESIGN.md file, and even a DESIGN.md collection specifically for terminal applications (TUI) covering tools like Claude Code, Lazygit, and btop.
The ecosystem moves fast. If the product you need isn’t yet in the awesome-design-md collection, you can open an issue with the website URL to request it.
The real shift
Frameworks like CLAUDE.md and AGENTS.md taught agents how to build your project. DESIGN.md closes the other half: teaching agents how it should look.
The approach recognizes something that’s been true for a while: AI agents are excellent software engineers and mediocre designers. Not because they can’t generate visually precise code — they can — but because they’ve never had a standardized way to receive design intent. DESIGN.md is that standard.
The repository is at github.com/VoltAgent/awesome-design-md. Check out the preview.html files before choosing — seeing the visual component catalog will help you decide which design system best fits your project.