What is a DESIGN.md file? How to give your AI coding agent real design taste

A DESIGN.md is a single markdown file that documents a product's design system — its colors, typography, spacing, radii, and component patterns — as structured tokens an AI coding agent can read and build from. Instead of describing the look you want in a long prompt, you hand the agent one file and it builds in that visual language.

Why AI-generated UIs look generic

If you have built a site with an AI coding agent — Cursor, Claude Code, v0, Lovable, Bolt — you have probably noticed the output tends toward the same look: a little too much purple, default shadows, rounded-everything, the "AI admin panel" aesthetic. That is not the model's fault. Without a concrete design system, the agent has nothing specific to aim at, so it falls back to the average of everything it has seen.

A DESIGN.md fixes that by giving the agent a specific, named target: this exact set of colors, this type scale, this spacing rhythm, these component rules.

What goes in a DESIGN.md

A good DESIGN.md has two parts:

• Structured tokens (usually YAML frontmatter): colors, typography (family, size, weight, line-height, letter-spacing per role), spacing, rounded/radius, and a components map where each component references tokens rather than hard-coded values.
• A written analysis: a short, plain-language description of the design's character, plus its layout system, elevation/shadow recipes, and a "do's and don'ts" section so the agent knows what to avoid, not just what to copy.

The token references matter. A button should say "background: {colors.primary}", not "background: #635BFF". That way the whole system stays consistent and is easy to re-theme.

How to use a DESIGN.md with your agent

1. Pick a design you like in the duply library.
2. Copy its DESIGN.md (every entry exposes a clean, copy-paste file).
3. Paste it into your agent and say: "Build this page using the design system in DESIGN.md — use the tokens, follow the do's and don'ts."

Because it is plain markdown, it works in any tool that takes text: Cursor, Claude Code, v0, Lovable, Bolt, or a plain ChatGPT/Claude chat.

DESIGN.md vs. design tokens vs. a screenshot

• A screenshot tells the agent what something looks like, but it has to guess every value. Results drift.
• Raw design tokens (a JSON blob of colors and sizes) are precise but have no rules — the agent knows your blue but not when to use it.
• A DESIGN.md combines both: exact tokens plus the written rules for applying them. That is why it produces consistent, on-brand UI instead of a pile of correct-but-random values.

FAQ

Is a DESIGN.md the same as design tokens? No. Design tokens are the raw values. A DESIGN.md wraps those tokens in usage rules and component specs so an agent knows how to apply them, not just what they are.

Can I use it with any AI coding tool? Yes. It is plain markdown, so it works with Cursor, Claude Code, v0, Lovable, Bolt, and general chat assistants.

Do I need to write one myself? No. duply documents real products' design systems as ready-to-use DESIGN.md files. Browse the library, copy one, and hand it to your agent.

Are these official brand files? No. Each DESIGN.md is an independent analysis of publicly observable design choices, not an official asset — see our terms for the full framing.