DESIGN.md Guide — The New Standard for Communicating Design to AI Agents
Introduction
Ask an AI coding agent to build your UI, and you will quickly notice the problem: button colors shift between requests, font sizes drift across pages, and border-radius values change from one component to the next. Without explicit design constraints, AI agents fall back to generic defaults — producing functional but visually inconsistent interfaces.
In March 2026, Google Labs' Stitch team proposed DESIGN.md as the solution. Just as README.md explains a project to humans, DESIGN.md explains a design system to AI agents. The concept struck a nerve immediately — the community-driven awesome-design-md repository quickly gained significant traction on GitHub within days of its release.
Key Takeaways
- DESIGN.md is a plain Markdown file that defines colors, typography, spacing, and component styles for AI consumption
- Proposed by Google Stitch, and can be used as context by Claude Code, Cursor, Gemini CLI, and other major AI tools
- Placing it in your project root can improve UI consistency in AI-generated code
- Tools and curated collections for generating DESIGN.md files are growing rapidly
Why Was DESIGN.md Created?
As AI coding agents matured, the ecosystem developed several file formats for communicating coding context: Cursor's .cursorrules, Anthropic's CLAUDE.md, and Microsoft's AGENTS.md. These files tell agents how to write code — but none of them address how things should look.
DESIGN.md fills this gap. Without a persistent design context file, AI agents make visual decisions from scratch on every prompt, producing outputs that look different each time. By placing DESIGN.md in the project root, agents can reference it as context and produce more brand-consistent UI.
The Lineage of AI Context Files
| File | Creator | Scope |
|---|---|---|
.cursorrules | Cursor | Coding rules and patterns |
CLAUDE.md | Anthropic | Project context for Claude Code |
AGENTS.md | Microsoft (for GitHub Copilot) | Agent coding guidelines |
DESIGN.md | Google / Stitch | Visual design system |
These files are complementary, not competitive. CLAUDE.md and AGENTS.md instruct agents on code behavior; DESIGN.md instructs them on visual behavior. A well-equipped project has both.
What Does a DESIGN.md File Look Like?
DESIGN.md is written in plain Markdown — no JSON schemas, no proprietary formats. AI agents parse it as natural language with structured headings. A standard file includes the following sections.
1. Visual Theme
A 2-3 sentence description of the project's overall aesthetic direction — minimal, dark mode, glassmorphism, etc. This sets the tone for all subsequent design decisions.
2. Colors
Define your palette as role + hex code + usage description triplets.
## Colors
- **Primary** (#6366F1): Main brand color for buttons and links
- **Secondary** (#EC4899): Accent color for CTAs and highlights
- **Background** (#0F172A): Page background
- **Surface** (#1E293B): Card and modal backgrounds
- **Text Primary** (#F8FAFC): Body text
- **Text Secondary** (#94A3B8): Supporting text
- **Success** (#10B981): Success states
- **Error** (#EF4444): Error states3. Typography
Specify font families, sizes, weights, and line heights for each text hierarchy level.
## Typography
- **Font Family**: Inter, system-ui, sans-serif
- **Heading 1**: 48px, Bold (700), line-height 1.2
- **Heading 2**: 32px, Semibold (600), line-height 1.3
- **Body**: 16px, Regular (400), line-height 1.6
- **Caption**: 14px, Regular (400), line-height 1.44. Spacing and Layout
Define your spacing scale, container widths, and breakpoints.
5. Components
Document styles for buttons, cards, inputs, and other frequently used UI elements — including dimensions, colors, border-radius, and state variations (hover, disabled, focus).
6. Elevation
Define shadow levels, border styles, and depth cues.
7. Do's and Don'ts
This section is critical. Without explicit guardrails, AI agents revert to probabilistic defaults and produce inconsistent results.
## Do's and Don'ts
### Do
- Add hover/focus states to all interactive elements
- Use 24px spacing between cards
- Use Lucide Icons for all iconography
### Don't
- Don't use drop shadows on interactive elements
- Don't center-align body text
- Don't use gradients with more than 2 colorsHow to Write a DESIGN.md: Three Practical Steps
Step 1: Start with Colors and Typography
These two properties have the greatest impact on visual consistency. Create a DESIGN.md with just these two sections and generate a few UI components with your AI tool. You will immediately see the difference in output consistency.
Step 2: Add Component Styles
Document the specific styles for buttons, cards, and input fields — the elements that cover the most UI surface area in your project. Include dimensions, padding, border-radius, and state variations.
Step 3: Add Guardrails
Tell the AI what not to do. Without a Do's and Don'ts section, AI agents make probabilistic design choices that drift across prompts.
Generating DESIGN.md from Existing Sites
You do not need to write DESIGN.md from scratch. Several tools can extract design systems from live websites:
- Google Stitch: Enter a URL to extract and generate a DESIGN.md automatically
- awesome-design-md: A curated collection of 58 brand DESIGN.md files (Stripe, Vercel, Linear, Notion, and more) published by VoltAgent under MIT license
- getdesign.md: A CLI tool — run
npx getdesign add [brand]to add a brand's DESIGN.md to your project
Note: A DESIGN.md extracted from a live website is a snapshot of that site's current appearance. As the site evolves, the extracted file will drift. Where possible, base your DESIGN.md on canonical design tokens rather than extracted CSS values.
What Are the Best Practices for Writing DESIGN.md?
Use specific values. Write #1A73E8, not "a trustworthy blue." AI agents interpret concrete numbers far more accurately than subjective descriptions.
Name colors semantically. Define colors by role (Primary, Error, Surface), not just hex codes. This enables AI to make contextually appropriate color choices.
Keep it concise. DESIGN.md is not a full design system. It does not cover UX judgment calls like "when should we use a primary button vs. secondary?" It covers mechanical visual properties: color, size, radius, spacing.
Version control it. Commit DESIGN.md to your repository and review changes through pull requests. Your design rules gain the same traceability as your code.
Grow it incrementally. Start with two sections (colors, typography) and expand as your project matures. A minimal but accurate DESIGN.md is far better than an exhaustive but outdated one.
How Do You Handle Dark/Light Dual Themes?
Many websites support both dark mode and light mode, but there is no established standard for expressing dual themes in DESIGN.md.
Google Stitch's official format specification does not define a dual-theme syntax, and the DESIGN.md files in awesome-design-md are written for a single theme only — Stripe is light-only, Linear is dark-only.
However, Linear's DESIGN.md contains an interesting pattern. While the file is primarily dark-themed, its Colors section includes a ### Light Mode Neutrals (for light theme contexts) subsection that supplements a subset of light mode colors alongside the main dark palette.
Practical Approaches for Now
For sites with dual themes, consider structuring your Colors section with subsections:
## Colors
### Light Mode
- **Background** (#FFFFFF): Page background
- **Surface** (#F8FAFC): Card backgrounds
- **Text Primary** (#0F172A): Body text
### Dark Mode
- **Background** (#0F172A): Page background
- **Surface** (#1E293B): Card backgrounds
- **Text Primary** (#F8FAFC): Body text
### Shared (Theme-independent)
- **Primary** (#6366F1): Brand color (both themes)
- **Error** (#EF4444): Error states (both themes)This keeps everything in a single file while giving AI agents clear context for each theme. Typography, spacing, and component structure typically remain the same across themes — only colors change.
Dual-theme DESIGN.md is still an evolving area. A standardized pattern may emerge from Google Stitch or the community. For now, the most practical approach is to document your primary theme fully and supplement with alternate theme colors.
The Google Stitch Ecosystem
DESIGN.md was born out of Google Stitch, but it is a tool-agnostic format that works across the AI ecosystem.
What Is Google Stitch?
Stitch is an AI-native design tool from Google Labs. It debuted at Google I/O in May 2025. A major update in March 2026 introduced DESIGN.md support, multi-screen generation, and interactive prototyping, significantly expanding its capabilities.
In Stitch, every prompt is automatically paired with the project's DESIGN.md before reaching the model. This eliminates the need to re-specify brand colors, fonts, and spacing in every request.
Using DESIGN.md Beyond Stitch
Because DESIGN.md is plain Markdown, it works with any AI tool that reads project files:
- Claude Code: Can reference DESIGN.md when generating UI-related code
- Cursor: May use it as project context
- Gemini CLI: Can be specified as a context file
- GitHub Copilot: Can include it as part of repository context
Community Momentum
The ecosystem around DESIGN.md is expanding rapidly. VoltAgent's awesome-design-md repository offers 58 brand design systems under MIT license. Tools like getdesign.md and designmd.app provide web galleries and CLI access. Japanese tech media including @IT and DevelopersIO have published detailed coverage, reflecting strong interest in the Asia-Pacific developer community.
FAQ
Q. Do I need design expertise to write a DESIGN.md?
A. Not necessarily. Tools like Google Stitch and getdesign.md can auto-generate DESIGN.md from existing websites. You can also start from a template in awesome-design-md and customize it.
Q. How is DESIGN.md different from CSS custom properties?
A. CSS custom properties are a technical implementation that browsers interpret. DESIGN.md is a natural-language document that AI agents interpret. Ideally, use both: DESIGN.md communicates design intent to AI, while CSS variables enforce consistency at runtime.
Q. Does updating DESIGN.md immediately affect AI output?
A. Yes. When AI agents reference DESIGN.md as context, changes take effect on the next generation. However, AI interprets the guide probabilistically — it is not a pixel-perfect compiler.
Q. Can I use DESIGN.md with Tailwind CSS?
A. Absolutely. Define your design tokens in DESIGN.md and implement them in tailwind.config.js. The AI reads DESIGN.md to select appropriate Tailwind classes.
Q. How do I handle sites with both dark mode and light mode?
A. There is no official standard yet. A practical approach is to split the Colors section into Light Mode / Dark Mode / Shared subsections. Typography and spacing are usually theme-independent, so splitting only the color definitions is sufficient.
Q. Can I use DESIGN.md alongside CLAUDE.md or AGENTS.md?
A. Yes. They serve complementary purposes. CLAUDE.md / AGENTS.md define coding behavior; DESIGN.md defines visual behavior. Place both in your project root for comprehensive AI context.
Summary
DESIGN.md is emerging as the design equivalent of README.md — a plain-text standard that bridges the gap between design intent and AI-generated code. Its simplicity (just Markdown), portability (tool-agnostic), and git-friendliness give it the characteristics of a lasting project standard.
Start with just two sections — colors and typography — and ask your AI agent to generate a UI component. The consistency improvement speaks for itself.
At ZenChAIne, we continue to explore how AI agent tooling can streamline the bridge between design and development. DESIGN.md represents exactly the kind of pragmatic, developer-friendly innovation that makes AI-assisted workflows more reliable.
References
- Design UI using AI with Stitch from Google Labs
- DESIGN.md — Stitch Documentation
- VoltAgent/awesome-design-md — GitHub
- What Is Google Stitch's Design.md File? — MindStudio
- DESIGN.md files and the foundational patterns of AI-assisted design — Fifty Five and Five
- DESIGN.md: Context, Not Magic — Slot Machine