What is DESIGN.md? The Complete Guide
The problem DESIGN.md solves
Every engineering team adopting AI coding agents eventually runs into the same friction point: the AI has no persistent memory of what a product is supposed to look like. Every time you open a new session in Cursor, Claude Code, or GitHub Copilot, the context resets.
To compensate, engineers currently rely on a few flawed workarounds. They paste screenshots of target designs and hope the vision model infers the correct hex codes and spacing. They write extensive system prompts defining brand guidelines. They point the agent to raw CSS variables or a Tailwind configuration file.
None of these methods survive a session reset efficiently. Screenshots lead to approximation errors—vision models guess at hex colors rather than applying exact tokens. System prompts are tedious to rewrite and maintain across a team. Raw CSS files are built for the compiler, lacking the semantic narrative an AI needs to understand component hierarchy or interaction states. There is no shared, persistent source of truth for visual design in AI workflows, meaning engineers spend the first ten minutes of every task re-explaining the brand identity.
What is DESIGN.md, exactly?
DESIGN.md is a single markdown file, typically placed at the root of a repository, designed explicitly for AI coding agents. It provides a machine-readable definition of a product's entire visual design system.
The format bridges the gap between design tokens and human readability. It uses a structured YAML frontmatter block to declare precise design tokens—encompassing colors, typography, spacing scales, border radius, and shadows. Below the frontmatter, a human-readable markdown narrative provides context, allowing the AI to ground itself in the "why" and "how" of the design system.
When an AI agent starts a session and detects a DESIGN.md file in the workspace, it immediately understands the product's visual identity. It knows the exact hex value for the primary button, the precise pixel value for a medium gap, and the correct font stack, ensuring the very first code it generates adheres to the established design system. For a comprehensive overview of how this fits into the broader ecosystem, refer to our guide on AI coding agent design files.
The anatomy of a DESIGN.md file
A compliant DESIGN.md file consists of two primary sections: the frontmatter and the body.
The YAML frontmatter is the strict, machine-readable core. It defines the specification version, the project name, and categorized dictionaries for tokens.
yaml--- version: "alpha" name: "Stripe Dashboard" colors: primary: "#635BFF" surface: "#FFFFFF" textPrimary: "#1D1D1F" typography: fontFamily: "Inter, -apple-system, sans-serif" baseSize: "16px" spacing: sm: "8px" md: "16px" lg: "24px" ---
Below the frontmatter, the document uses a specific token reference syntax. Components and style guidelines reference the YAML tokens using curly braces and dot notation. For example, a button specification might dictate: style: { backgroundColor: colors.primary, textColor: surface, rounded: rounded.md }.
This intentional syntax allows AI models to resolve the references dynamically. The document typically details sections for Overview, Colors, Typography, Spacing, and specific Component patterns. It often concludes with a "Do's and Don'ts" block, instructing the agent on anti-patterns to avoid. You can see how these sections are formalized in the DESIGN.md specification.
How AI coding agents actually use it
Different AI coding environments process workspace files in slightly different ways, but the utility of DESIGN.md remains consistent across platforms.
In Cursor, the agent reads the file on session start if it's placed in the repository root or referenced in the context. Because Cursor index files aggressively, the structured format allows it to pull the correct tokens seamlessly during component generation. For specific instructions on optimizing this, read about using DESIGN.md with Cursor.
Claude Code operates similarly. It reads the file once and retains the token definitions across the duration of the CLI session. When tasked with building a new view, Claude Code maps the layout requests against the spacing and color constraints defined in the file. Further details are available in our DESIGN.md with Claude Code walkthrough.
GitHub Copilot surfaces the file in its chat context. When a developer asks Copilot Chat to "build a hero section using our standard design," Copilot references the DESIGN.md definitions to inject the correct utility classes or styled-component properties.
DESIGN.md vs the alternatives
The introduction of DESIGN.md naturally invites comparisons to existing tools and file conventions.
It is distinct from CLAUDE.md and AGENTS.md. Those files govern behavioral instructions, testing conventions, and orchestration patterns. DESIGN.md handles the visual identity exclusively. They are complementary files that divide repository instructions into logical domains.
It serves a different audience than Figma plugins. Figma plugins are built to synchronize tokens into build pipelines or design tools. DESIGN.md is a static, repository-native reference built entirely to instruct Large Language Models during code generation.
it is not a replacement for a Tailwind configuration or native CSS variables. Those files define how the browser renders the code. DESIGN.md defines how the AI writes the code. The AI requires semantic instructions and usage rules that a raw tailwind.config.js cannot provide effectively.
How to get a DESIGN.md file for your project
There are three primary paths to integrating this specification into your repository.
The first option is manual creation. Teams can write the file by hand, adhering to the specification. This is effective for small projects but can be tedious for complex, mature design systems.
The second option is automated extraction from your own live site. By using designmd.run, engineers can paste a URL and let the extraction pipeline parse stylesheets, analyze metadata, and generate a complete file. You can see examples of this output in our gallery.
The third option is extracting a reference design. If a team is building a new product and wants to align their interface with an established standard, they can extract a design system from a site they admire. For instance, developers frequently extract the Stripe design system to use as a foundational baseline for AI generation.
What is next for DESIGN.md
The specification is currently in the Alpha phase and is actively evolving based on developer feedback.
Future iterations will address spec maturity, ensuring token definitions can scale to handle highly complex, multi-theme enterprise applications. Native support for dark mode token extraction and mapping is planned for upcoming V1+ releases.
Also, we're developing CLI workflows to allow engineers to run extraction jobs directly from the terminal, bypassing the web interface. A GitHub Action is also on the V1+ roadmap, which will automatically update the DESIGN.md file whenever production deployments detect visual changes.
Frequently asked questions
What is DESIGN.md?
It is a single, markdown-based file placed in a repository that provides AI coding agents with a machine-readable definition of a project's design system, including colors, typography, and spacing tokens.
Which AI agents support DESIGN.md?
It is designed to be read natively by any context-aware AI agent, including Cursor, Claude Code, and GitHub Copilot, without requiring specialized plugins or integrations.
Does it replace my Tailwind config?
No. Your Tailwind config dictates how the browser compiles and renders CSS. The DESIGN.md file dictates how the AI agent writes the code before it's ever compiled.
How do I generate one?
You can write it manually following the specification, or use the extraction tool at designmd.run to generate one automatically from any live URL.
Get Started
Paste a URL and get your first DESIGN.md in about 3 minutes. Head to designmd.run to start your extraction.