DESIGN.md is a plain-text Markdown file, kept at the root of a project, that describes a visual design system in words and exact values: colors, typography, spacing, shapes, components and the rules for using them. Coding agents like Claude Code, Cursor and Codex read it before they write UI code, so a new page looks like the rest of your product, or like a style you picked, rather than like every other AI-generated site.
OpenDesignMD is a free library of 1,186 DESIGN.md files made from real websites. This guide explains the format and how to use it.
Why use a DESIGN.md?
Ask an agent for a pricing page with no direction and you get the average of everything it has seen: centered hero, purple gradient, rounded cards, a drop shadow on everything. A DESIGN.md replaces that guess with a decision.
- Consistent UI. Every screen the agent builds uses the same colors, type scale and components.
- Fewer corrections. You stop repeating "smaller headings, no gradient" in every prompt.
- Works with any agent. It's Markdown, so any tool that reads files can use it.
- Lives with your code. It's versioned in Git, reviewed in pull requests, and shared with your team.
- Portable. Switch agents, or start a new project in the same style, by copying one file.
What goes in a DESIGN.md
Most DESIGN.md files, including every guide in this library, cover the same ground:
- Overview: the character of the design in a few sentences, and its key traits.
- Colors: each color's value and its job, such as page background, body text or primary action.
- Typography: font families, the type scale, weights, line heights and letter spacing.
- Layout: content width, spacing scale, grid and the rhythm between sections.
- Elevation and shapes: shadows, borders and corner radii.
- Components: buttons, cards, navigation, forms and their states.
- Responsive behavior: what changes on small screens.
- Do's and don'ts: the rules that keep the design from drifting.
Many files also start with design tokens as YAML frontmatter, so tools can read the values directly and the text can refer to them by name, like {colors.primary}.
A DESIGN.md example
A minimal file looks like this. Real guides go into much more detail on components and states.
# How Acme is designed
## Overview
Calm and precise. A white canvas, near-black text and one blue accent
used only for the main action on each screen.
## Colors
| Token | Value | Use |
|---------|---------|---------------------------|
| canvas | #FFFFFF | Page background |
| ink | #0A0A0A | Headings and body text |
| primary | #2563EB | Primary buttons and links |
## Typography
- Inter. Display 56px / 1.05, weight 700, tracking -0.03em.
- Body 16px / 1.5, weight 400.
## Do's and don'ts
- Do keep one primary button per screen.
- Don't add gradients or drop shadows.For complete examples, open any design in the library, such as apple.com, about.instagram.com, bugatti.com, evilmartians.com, landonorris.com, artsandculture.google.com, microsoft.com or openai.com. To write your own, start from the blank DESIGN.md template.
How to use DESIGN.md with your coding agent
- Find a style in the library, or write your own from the template.
- Copy or download it, and save it as
DESIGN.mdin the root of your project. Each design page also has a one-linecurlcommand. - Tell your agent to follow it, either once in its instructions file or in your prompt.
| Agent | Where to point it at DESIGN.md |
|---|---|
| Claude Code | Add @DESIGN.md to CLAUDE.md to load it in every session, or mention the file in your prompt. |
| OpenAI Codex | Add "Follow DESIGN.md for all UI work." to AGENTS.md. |
| Cursor | Reference it in a project rule, or type @DESIGN.md in chat. |
| GitHub Copilot | Mention it in .github/copilot-instructions.md, or attach the file in chat. |
| Windsurf and other agents | Add a line to the project rules or AGENTS.md. |
| v0, Lovable, Bolt | Paste the file into the project instructions or your first prompt. |
Then ask for UI the way you normally would. A prompt that names the file works well:
Build the pricing page. Follow DESIGN.md: use its colors, type scale,
spacing and button styles, and respect its don'ts.DESIGN.md vs AGENTS.md, README and design tokens
| File | Audience | What it says |
|---|---|---|
README.md | People | What the project is and how to run it. |
AGENTS.md / CLAUDE.md | Coding agents | How to work in the codebase: commands, conventions, structure. |
DESIGN.md | Coding agents and designers | How the interface looks, and the reasons behind it. |
| Design tokens (JSON, YAML) | Tools | Raw values only, without the rules for using them. |
A full design system includes component code, documentation and design files. A DESIGN.md is the part an agent can read in one go: the visual rules, written down.
Tips for better results
- Be exact. "#2563EB" beats "a friendly blue", and "16px / 1.5" beats "comfortable body text".
- Give every color a job. Say where the accent may appear, not just what it is.
- Write the don'ts. They stop the defaults agents fall back on.
- Name font fallbacks. If a typeface isn't free, say which licensed alternative to use.
- Keep it current. Update it in the same pull request as the design change.
- Make it yours. When you start from a famous site's guide, keep the structure and choices you like, and use your own name, logo and brand.
Frequently asked questions
What is a DESIGN.md file?
A DESIGN.md is a Markdown file, usually saved at the root of a project, that describes a visual design: colors, typography, spacing, shapes, components and the rules for using them. AI coding agents read it so the interfaces they build follow that design instead of a generic default.
Is DESIGN.md an official standard?
It is a convention rather than a strict standard. Agents read plain Markdown, so any clear structure works. Most files follow the same sections (overview, colors, typography, layout, components, and do's and don'ts), and many start with YAML design tokens as frontmatter.
Where do I put DESIGN.md?
Save it as DESIGN.md in the root folder of your project, next to README.md. Then reference it from the instructions file your agent reads, such as CLAUDE.md or AGENTS.md, or mention it in your prompt.
Does DESIGN.md work with Claude Code, Cursor and Codex?
Yes. Any coding agent that can read files in your project can use a DESIGN.md, including Claude Code, Cursor, OpenAI Codex, GitHub Copilot and Windsurf. App builders such as v0, Lovable and Bolt can use it too if you paste it into the project instructions or your first prompt.
What is the difference between DESIGN.md and AGENTS.md?
AGENTS.md (or CLAUDE.md) tells an agent how to work in a codebase: commands, conventions and structure. DESIGN.md tells it how the interface should look. They work together: one line in AGENTS.md can tell the agent to follow DESIGN.md for all UI work.
Are the DESIGN.md files on OpenDesignMD free?
Yes. All 1,186 files are free to copy, download and use, including in commercial projects, under the MIT License.
Can I use a DESIGN.md made from a famous website for my own product?
Use it as a direction for layout, type, spacing and color, not to copy another company's identity. Don't reuse its logo, name or trademarks, and check the licenses of any fonts it names.
How long should a DESIGN.md be?
Long enough to name every value an agent needs and short enough to read in one go. The guides in this library are about 2,000 words each. Exact values and clear rules matter more than length.
Browse DESIGN.md files
Find one by category, tag, color or font, see dark mode orlight mode designs, or scan the A–Z directory of all 1,186.