Why AI-built interfaces all look the same, and how a design.md file fixes it

Ask an AI coding tool for a landing page and you’ll have something working in under a minute. You’ll also have something you’ve seen a thousand times: a soft purple gradient, a row of rounded cards, a friendly sans-serif headline and a button that says “Get started.” It’s competent, tidy and instantly forgettable.

That sameness isn’t a flaw in the model. It’s what happens when a very capable builder gets no brief. With nothing to go on, AI fills every gap with the safest, most common choice it knows, which tends to be the average of everything it has seen before. If you want output that looks like your product, the AI has to know what your product looks like. A design.md file is the simplest way to tell it.

The problem is missing context, not missing talent

Most teams already have a design system. It’s just scattered. The colors sit in a design file, the spacing sits in a config, the tone of voice sits in a brand PDF, and the hard-won rules (“we never put two primary buttons side by side”) sit in a senior designer’s head.

Some of that your AI can technically read. Almost none of it tells the AI how to make decisions. A config file knows your brand blue, but not that the blue is reserved for one action per screen. A design file shows a finished screen, but not the reasoning behind it. And nobody pastes a forty-page brand guide into every prompt.

So the AI guesses. Sometimes it guesses well. More often it guesses generic, and you spend the time you saved fixing padding, swapping colors and rewriting button labels. Worse, it guesses differently every time. Two screens built a week apart can disagree about something as basic as button height, and nobody notices until a customer does.

What a design.md file actually is

A design.md is a single, portable file that describes a complete design language. It has two halves that work together.

The top of the file holds your design tokens: colors, typography, spacing, corner radius, shadows and motion, each written as an exact value in a consistent structure. The rest is plain Markdown, where you describe your brand voice, layout principles, component guidance and the do’s and don’ts that make your product feel like yours.

Here’s a trimmed example:

---
name: Aurora
tokens:
  color:
    brand:
      primary: { value: "oklch(0.55 0.18 265)", type: color }
    text:
      muted: { value: "oklch(0.50 0.02 265)", type: color }
  radius:
    md: { value: "0.625rem", type: dimension }
---

## Components
Use color.brand.primary for one primary action per view.
Cards use radius.md and sit flat. Save shadows for overlays.

Because it’s just text, it works for everyone who touches the product. Designers can read it like a style guide, developers can review it like code, and AI tools can follow it like a brief. It lives in your project, changes alongside your product and never locks you into a single app. The full specification explains the complete format.

Tokens tell the AI what. Rules tell it when.

This is the part most teams miss: tokens on their own aren’t enough.

Give an AI a palette and it will happily use every color in it, often on the same screen. Give it a type scale and it will reach for the biggest size whenever something feels important. Give it motion tokens and suddenly everything slides, fades and bounces. Values describe your materials. They don’t describe your taste.

The Markdown half of a design.md carries that taste. A line like “Use the brand color for one primary action per view” prevents a page full of competing buttons. “Body text never drops below 16px” protects readability. “Write button labels as verbs, in sentence case” keeps your interface sounding like one product instead of five. Each rule is short and specific, which is exactly what makes it easy for a model to follow.

Think of tokens as the ingredients and rules as the recipe. You need both to get the same dish twice.

How your AI tools pick it up

The best part is that you write it once. Most AI coding tools automatically read a project-level instructions file, so you save your design rules wherever your tool already looks:

• Claude Code reads CLAUDE.md at the root of your project.

• Cursor reads rule files in .cursor/rules/.

• Windsurf reads .windsurfrules.

• GitHub Copilot reads .github/copilot-instructions.md.

With chat-based builders such as v0, you can paste the file straight into the conversation. Either way, every new screen starts from your system instead of a blank guess.

Here’s what that looks like in practice. Ask for a pricing page without a design.md and you’ll likely get three identical cards, a gradient “Most popular” badge and a different shade of blue on every button. Ask again with one in place and the cards share your radius and spacing, the recommended plan wears your single brand accent, and every button says exactly what it does, in your voice.

How to write a design.md your AI will follow

You don’t need a huge document. You need a clear one. The best design.md files read like notes a thoughtful designer would leave for a new teammate: specific, opinionated and short. A few habits make a big difference:

1. Name tokens by purpose, not appearance. text.muted tells an AI when to use a color. gray-500 only tells it what the color is.

2. Write rules as instructions. “Use,” “never” and “always” beat long paragraphs of explanation. If a rule needs a backstory, it’s probably two rules.

3. Cover the decisions AI gets wrong most often. Button hierarchy, spacing rhythm, shadows, corner radius, empty states and the tone of your copy are where generic output gives itself away.

4. Build in accessibility. State your contrast targets, focus styles and minimum tap sizes, so accessible choices become the default instead of a fix for later.

5. Keep it short enough to read in one sitting. If you wouldn’t read it, your AI won’t follow it well either.

6. Treat it like code. Keep it with your project and update it whenever your design changes, so your AI never builds from an old version of your brand.

Start from a system that already works

Writing your first design.md from scratch is very doable, but you don’t have to start from zero. The DesignMD directory has ready-made systems across styles and industries that you can preview live, fork and adjust. The guided builder takes you from a single brand color to an accessible, ready-to-use design.md in a few steps, with no design background needed. And if you already have a screen you love, Screenshot to Design System in DesignMD Pro turns it into a working design.md in a couple of minutes.

When your file is ready, export the version made for your tool, drop it into your project and ask your AI for that landing page again. This time, it will look like it belongs to you.

The takeaway

AI has made building interfaces fast. It hasn’t made them distinctive. The gap between generic and memorable output is rarely a cleverer prompt. It’s a clear source of truth your tools can read every single time. Write it once, keep it current, and every tool your team uses starts from the same brief. A design.md file gives your AI the one thing it can’t guess: your taste.