What Is a DESIGN.md File? The Complete Guide for AI-Generated UI

AI coding agents can write a polished interface in minutes, but they often struggle to make the next page look like the first one. Colors drift. Border radii change. A new font appears. Cards gain a shadow that the rest of the product never uses. The problem is usually not the model’s ability to write CSS—it is the absence of durable design context.

Why AI-generated interfaces become inconsistent

Most AI UI prompts describe a result, not a system. “Build a modern pricing page with a purple accent” may produce an attractive page, but it leaves dozens of decisions undefined: which purple, which neutral background, which heading font, how much corner rounding, what hover easing, how wide the content container should be, and when layouts collapse on mobile.

An agent fills those gaps with reasonable defaults. On the next task it may choose different defaults. The output is locally plausible but globally inconsistent.

This is the same reason software projects keep a README.md, API schema, lint configuration, and coding standards. Important context should not depend on someone remembering to paste it into every conversation.

What should a DESIGN.md file contain?

A useful DESIGN.md is more than a list of hex codes. It explains both the ingredients of the design and the rules for combining them. A strong file usually has two layers:

1. Machine-readable design tokens

YAML frontmatter at the top gives an agent predictable values it can map to CSS custom properties, Tailwind configuration, theme objects, or component props. Common groups include:

• Colors: canvas, surface, text, muted text, borders, primary, accent, success, warning, and destructive roles.
• Typography: display and body families, sizes, weights, line heights, and letter spacing.
• Spacing: the product’s rhythm rather than arbitrary one-off gaps.
• Shape and elevation: radius scale, borders, shadows, blur, and glass effects.
• Layout: containers, columns, gutters, breakpoints, and section spacing.
• Motion: durations, easing curves, keyframes, and reduced-motion behavior.

2. Human-readable implementation guidance

Tokens alone do not explain intent. The Markdown body should describe how the system behaves in practice:

• Where the accent color is allowed and where it becomes visually noisy.
• How primary and secondary buttons differ.
• Which card treatment is standard, elevated, interactive, or featured.
• How navigation, forms, badges, tables, and empty states should look.
• How desktop hierarchy compresses on tablets and phones.
• Do’s and don’ts that prevent an agent from inventing off-brand UI.

A practical DESIGN.md example

The exact schema can vary by team. Consistency and clarity matter more than copying one universal format. Here is a compact example:

---
name: "Northstar Product UI"
colors:
  canvas: "#FAFAFC"
  surface: "#FFFFFF"
  text: "#141828"
  textMuted: "#5D6474"
  border: "#E7E8EE"
  primary: "#4F46E5"
typography:
  display:
    fontFamily: "Space Grotesk, sans-serif"
    fontWeight: 700
    letterSpacing: "-0.03em"
  body:
    fontFamily: "Inter, sans-serif"
    fontSize: "16px"
    lineHeight: 1.6
rounded:
  control: "10px"
  card: "20px"
motion:
  standard: "180ms cubic-bezier(.16,1,.3,1)"
---

## Visual direction
Use quiet white surfaces on a very light neutral canvas. Reserve the
indigo primary for actions, selected states, and small emphasis areas.

## Buttons
- Primary: solid primary background, white text, 10px radius.
- Secondary: white surface, 1px border, dark text.
- Never introduce gradient buttons outside major marketing CTAs.

## Guardrails
- Do not add colors outside the documented semantic palette.
- Do not use fully rounded cards; pill radii are for compact controls.
- Do not mix display and body font roles.

Notice that the file includes exact values and judgment. “Primary is #4F46E5” is useful. “Reserve primary for actions and selected states” is what keeps a full page from turning purple.

How Cursor, Cline, Claude Code, and other agents use DESIGN.md

Put DESIGN.md at the root of the repository. Then make reading it part of the agent’s operating instructions. The precise rules filename depends on the tool, but the instruction can remain simple:

Before writing or changing UI code, read DESIGN.md at the
repository root. Follow its design tokens, component recipes,
responsive rules, motion guidance, and guardrails. Reuse
documented patterns before inventing new ones.

You can place that instruction in .clinerules, Cursor project rules, CLAUDE.md, .github/copilot-instructions.md, or the equivalent file for your agent. You can also reference it directly in a task:

Build the account settings page using the existing application stack. Follow DESIGN.md exactly, reuse its form and card recipes, and do not introduce new colors, typefaces, radii, or shadows.

The file does not replace good prompts. It removes repeated design exposition from them, leaving the prompt free to describe the actual feature, content, and behavior.

How to generate DESIGN.md from an existing website or screenshot

If a mature product already exists, writing the design system manually can be slow. The implementation may contain hundreds of CSS values, yet only a small subset forms the real visual language. A useful extraction process should combine multiple kinds of evidence:

1. Inspect the implementation. Collect stylesheets, CSS custom properties, font imports, Tailwind utilities, breakpoints, transitions, and keyframes.
2. Measure repeated values. Frequency helps distinguish core tokens from one-off decoration.
3. Read the page structure. Headings, calls to action, navigation, cards, and form controls reveal component roles.
4. Use a screenshot as visual evidence. Code tells you what values exist; the rendered page shows hierarchy and composition.
5. Synthesize rules, not just inventory. The final document should explain how tokens work together and which choices are brand-defining.
6. Validate with a preview. A live HTML recreation exposes incorrect assumptions far faster than reading a token table.

DesignMD Maker automates that workflow. In URL mode it analyzes the page’s HTML, CSS, scripts, design signals, and a rendered screenshot. In image mode it can derive a system when only a screenshot or mockup is available. The result includes the DESIGN.md specification and a live preview.

DESIGN.md vs style guides, design tokens, and screenshots

These formats are complementary. A strong workflow may keep Figma for design creation, token files for runtime theming, Storybook for component examples, and DESIGN.md as the concise context layer an AI agent reads before making UI decisions.

Best practices for a DESIGN.md that agents actually follow

Be specific enough to remove arbitrary choices

“Use modern spacing” is not a rule. Define the spacing rhythm, standard section gaps, control heights, and container widths. Replace “subtle shadow” with the exact shadow token and when it applies.

Document semantic roles, not only raw values

A palette of 24 hex codes forces the agent to infer purpose. Label canvas, surface, primary text, secondary text, border, action, success, warning, and destructive roles.

Include negative guidance

Guardrails are unusually valuable for generative tools. If the brand avoids gradients, says so. If only buttons and badges use pill shapes, say so. If headings never use the primary color, make that explicit.

Keep it close to the code

Version the file with the application so design-rule changes can be reviewed beside implementation changes. A repository file is easier for an agent to access than a document hidden behind another product’s permissions.

Update it after visual changes

A stale source of truth is worse than a small current one. Refresh DESIGN.md when you change core tokens, introduce a new component family, or significantly alter responsive and motion behavior.

Is DESIGN.md a replacement for a designer?

No. It is a context and consistency tool. It can capture decisions, accelerate implementation, and reduce accidental drift, but it does not decide product strategy, understand users, or replace design judgment. The best results come from using AI to execute within a system that a thoughtful human has chosen or approved.

Start with the design you already have

You do not need a perfect enterprise design system before using AI coding tools. Start by documenting the visual language that already exists. Give the agent exact tokens, a few component recipes, responsive guidance, and clear guardrails. That small amount of persistent context can improve every interface generated afterward.