DESIGN.md: A Markdown Design System File for AI Coding Agents
DESIGN.md is a Markdown file placed in the root of a project that defines a design system for AI coding agents to follow. It was introduced by Google Stitch and contains two types of content: structured design tokens (exact values for colors, typography, spacing, and components) and qualitative descriptions of design philosophy and intent. The awesome-design-md repository provides community-created DESIGN.md files modeled after popular brands including Stripe, Linear, and Vercel.
Why existing approaches fall short
Without design guidance, AI coding agents produce statistically common patterns from their training data: unstyled defaults, generic color choices, and uniform spacing that lacks intentionality.
Previous approaches have addressed this with mixed results. Repeating design instructions in every prompt is tedious and inconsistent. Figma-to-code plugins produce unmaintainable code and keep the design source of truth outside the repository. JSON design tokens are machine-readable but difficult to author and cannot convey the qualitative intent behind design decisions.
Markdown solves all three problems. It is human-readable and easy to write, LLMs understand it natively, and it lives in the repository under version control.
Structure of a DESIGN.md file
A DESIGN.md file has two parts: hard token definitions and design philosophy.
Design tokens
The token section defines the specific values the agent must use for styling. Common sections include:
Colors. List each color with its hex value and its intended use. Including usage context prevents the agent from applying a CTA color to decorative elements.
Typography. Specify font families, sizes, weights, and line heights for each text style (H1, H2, body, caption).
Spacing. Define a base unit and a scale derived from it so margins and padding are consistent throughout the UI.
Components. Specify border-radius, box-shadow, input styles, modal behavior, and other component-level rules.
Motion. Define duration values (for example, 150ms for fast interactions, 300ms for standard transitions) and cubic-bezier easing functions.
A minimal example:
Design philosophy
The qualitative section explains the intent behind the tokens. This is where DESIGN.md exceeds what JSON token files can provide.
Useful content for this section includes:
- Overall vibe. Descriptive language about how the UI should feel: "airy and uncluttered" or "bold and high-contrast."
- Usage guidelines. Explain when and how to apply each token. "The primary blue is reserved for the most important action on a page. It should never be used decoratively."
- Accessibility. "All text must meet a minimum contrast ratio of 4.5:1. Interactive elements must have visible focus states."
- Dos and don'ts. "Do use shadows to indicate elevation for interactive cards. Don't use more than two font weights on a single screen."
This qualitative context gives the agent the judgment to apply rules correctly in situations the token list does not explicitly cover.
Practical comparison
Running the same prompt ("Build a modern dashboard") without and with a DESIGN.md file demonstrates the difference.
Without design context, the agent produces a functional layout with generic defaults.
With a Stripe-inspired DESIGN.md added to the project root, the same prompt produces a polished result using Stripe's color palette, spacing conventions, and component styles.
Swapping the file for a different brand's DESIGN.md produces a correspondingly different result with no other changes to the prompt or project.
Why this approach works well with AI agents
Markdown sits at the intersection of what humans can comfortably write and what LLMs parse well. Because the file lives in the repository, it is version-controlled, reviewable in pull requests, and always co-located with the code it governs. It does not depend on external tools or proprietary formats.
The combination of structured tokens and natural language philosophy means the agent has both explicit rules for straightforward cases and contextual guidance for ambiguous ones. A JSON token file provides the former but not the latter. A prompt provides the latter but must be repeated for every interaction.
Getting started
The awesome-design-md repository at github.com/awesome-design-md/awesome-design-md contains community-created files modeled after well-known design systems. These can be used as starting points and customized to match a project's brand. Adding the file to the project root and instructing the agent to "strictly follow DESIGN.md" is sufficient for most AI coding agents to pick it up as context.
Final thoughts
The era of AI as a simple code-completion tool is over. We are now entering a phase of true collaboration, where AI agents act as junior developers, capable of executing complex tasks with precision. However, to unlock their full potential, we must provide them with clear, unambiguous instructions. DESIGN.md is the missing link—the instruction manual that teaches our AI partners how to build with taste, consistency, and brand identity.
The next time you start a project, don't just ask your AI to "build a dashboard." Give it a DESIGN.md file and tell it to build your dashboard. The results will speak for themselves. Start by exploring the community-curated templates on the "Awesome DESIGN.md" repository, drop one into your project, and customize it to fit your vision. The future of fast, high-quality, AI-powered UI development is here, and it starts with a single Markdown file.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.