DESIGN.md: Tell Your AI Agent What to Build, Not Just How to Build It

There’s a gap that most AI coding workflows ignore. You tell your agent how to write the code — but you never tell it how the UI should look. The result is functional pages with no coherent style, inconsistent components, and a design that feels assembled rather than considered.

DESIGN.md is a plain-text fix for this. Drop one file in your project root and any AI coding agent instantly understands your visual system — colours, typography, component patterns, spacing, the lot.

What DESIGN.md Actually Is

It’s a concept from Google Stitch. A markdown file — just like AGENTS.md — but instead of build instructions, it carries design instructions. The idea is simple: LLMs already read markdown better than anything else, so make your design system markdown.

The file covers everything an agent needs:

• colour palette with semantic names and hex values
• full typography hierarchy
• button, card, and input states
• spacing scale and grid rules
• shadow and elevation system
• do’s and don’ts to keep agents on guardrails
• ready-to-use agent prompts at the bottom

No Figma exports. No JSON schemas. No extra tooling. One text file, instant context.

The Awesome DESIGN.md Collection

This is where awesome-design-md comes in. It’s a curated repo of 71 ready-made DESIGN.md files — all extracted from real, well-designed developer-facing websites.

You want your app to feel like Linear? There’s a file for that. Like Vercel’s black-and-white precision? File for that too. Stripe’s purple gradient elegance, Apple’s premium whitespace, Supabase’s dark emerald — all extracted, structured, and ready to drop in.

The collection spans AI platforms, developer tools, databases, fintech, e-commerce, and automotive. Each entry ships with three things: the DESIGN.md itself, a preview.html showing swatches and components in light mode, and a preview-dark.html for the dark variant.

The workflow is exactly what it should be:

1. Pick a site whose design resonates with your project
2. Copy its DESIGN.md into your project root
3. Tell your agent: “Build me a page that looks like this”

That’s it.

Why This Matters

Every developer who’s used an AI agent to scaffold a UI has hit the same wall — the code works, the layout looks generic. The agent had no design context. It made assumptions and they were fine, just not yours.

DESIGN.md gives agents the same brief a designer would hand to a developer. It’s not a constraint — it’s context. The agent stops guessing and starts building something coherent.

The other half of what makes this repo useful is the sourcing. These aren’t invented design systems — they’re reverse-engineered from sites that your clients, stakeholders, or users already find credible. Borrowing Stripe’s design language for a payment tool isn’t laziness — it’s anchoring your UI to something users already trust.

Takeaway

If you’re building anything with AI coding agents and care about what the output looks like, DESIGN.md belongs in your workflow. The awesome-design-md repo gives you 71 starting points so you’re not writing one from scratch. Pick the aesthetic closest to your brief, drop it in, and let the agent do what it’s actually good at — building to spec rather than guessing.

Repo: github.com/voltagent/awesome-design-md Requests for custom DESIGN.md files: getdesign.md/request