Getting Started
What is DESIGN.md?
DESIGN.md is a markdown file that explains a product visual system to AI agents before they generate UI.
The short version
DESIGN.md is a markdown file that gives AI coding agents a written model of how a product should look and feel. It sits in the repository root next to engineering instruction files and acts as the visual layer of the agent's instructions. When an agent like Cursor, Claude Code, or Codex reads DESIGN.md before working on UI, it has access to the same visual intent a designer would carry in their head: color roles, typography scale, spacing rhythm, component behavior, page layout rules, and explicit examples of what not to build. The result is UI that reflects the product instead of defaulting to the agent's trained intuitions about what "modern" or "clean" means. DESIGN.md does not replace design tooling; it extends design intent into the development workflow in a format that agents can read, search, and apply directly to every file they touch.
Why it matters now
AI coding tools are now capable of generating and editing real production UI at scale. A single Codex session can touch fifteen components across three routes. A Claude Code session can add a new feature surface with forms, tables, empty states, and responsive behavior in one pass. When that happens without a design reference, each generated component makes independent visual decisions. The color is technically valid but not the brand color. The spacing is internally consistent but does not match the product's spacing system. The empty state is functional but not designed. Multiplied across dozens of sessions, this produces a product that looks like it was built by many different people with different taste. Google Stitch made the DESIGN.md convention visible, but the need extends to every AI coding tool. Cursor, Claude Code, Codex, Windsurf, Bolt, and v0 all benefit from a stable design reference before they touch a component.
How AI agents read and use it
Most AI coding agents have access to files in the repository. Cursor indexes files for context. Claude Code reads files on request. Codex can be instructed to inspect specific files before planning. When DESIGN.md lives in the repository root, agents can find it automatically or with a short instruction: "Read DESIGN.md before making any UI changes." The plain text format is ideal for this use case: no plugin required, no API call, no rendering pipeline. Agents parse markdown headings as section breaks and treat the prose as a specification to implement. The most effective DESIGN.md files use short, direct sentences and concrete values rather than aspirational language. "Primary buttons use #FF5722 with white label text, 14px font, 8px vertical padding, 16px horizontal padding" is more useful than "primary buttons should feel bold and energetic." Concrete rules produce consistent output; abstract rules produce subjective interpretations that drift from the intended design.
What belongs inside
A practical DESIGN.md includes three layers: visual values, component rules, and behavior constraints. The values layer defines color tokens and their semantic meaning, the type scale from small captions to display headings, the spacing scale used throughout the product, border radius values, and shadow usage. The component rules layer describes how the most common UI elements work: primary and secondary button states, card structure and density, table row height and header treatment, form input spacing and validation styles, modal and dialog tone, empty state composition, and loading state treatment. The behavior constraints layer sets rules that values alone cannot capture: "never add decorative gradients to operational dashboards," "settings pages should be quiet and dense, not sales-like," "empty states should feel calm and actionable, not apologetic." All three layers are necessary. Values alone leave interpretation gaps; behavior rules alone are too abstract without concrete values to back them up.
DESIGN.md vs traditional design documentation
Traditional design documentation lives in Figma files, Notion docs, internal wikis, or Storybook. These formats are built for human readers: interactive, visual, and browsable. DESIGN.md is built for AI agent readers: plain text, flat, short, and direct. An agent cannot open Figma, browse a component library, or interpret a Notion database. It can read a markdown file and extract rules from the prose. This is why DESIGN.md exists as a dedicated format rather than a style guide link or a design system URL. The file is also committable, diffable, and close to the code it governs. When a design decision changes — a new primary color, a revised card style, a change in navigation density — the update goes in the same pull request as the component change. That keeps design intent and implementation synchronized in version control, which makes the spec reliable over time rather than drifting out of date.
Getting started today
The fastest way to start is to write a thin file and iterate from real usage. Open a blank DESIGN.md in your repository root. Write one paragraph about the product personality. List your primary color, neutral palette, and one semantic color for destructive actions. Write the font family, base size, and heading scale. State the default border radius and the spacing values you use most often. Describe the primary button and secondary button in one sentence each. Add one anti-pattern: something the AI has already done that you had to correct. That file, even at 300 words, is already more useful than no file. Every fix you make to AI-generated UI is an opportunity to add a rule. Over two weeks of consistent use, the file grows to cover the surfaces where the product actually needs visual consistency. That incremental approach produces a more accurate spec than trying to write a comprehensive design system document on day one, before you know which rules actually prevent real mistakes.
Use DESIGN.md with a real product reference
Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.
Related guides
Best DESIGN.md examples
Examples of DESIGN.md files, templates, and public tools for AI-readable design systems.
DESIGN.md vs CLAUDE.md
Keep engineering behavior and visual behavior separate so agents can follow both well.
DESIGN.md vs AGENTS.md
A clean mental model for splitting agent instructions by domain.