What a free DESIGN.md file is, and why every AI codebase should have one

I built freedesignmd.com because I was tired of the same thing happening on every AI project I touched. You give Claude or Cursor or Lovable a brief, the code comes back fine on the inside, and the outside looks like every other AI app on the internet. Soft purple gradient on a white card. Inter at 14 pixels. A pill button with a slight shadow. It works, but it has no voice.

After enough of those, I started keeping a single markdown file in the root of my projects. I called it DESIGN.md. It listed the colors, the fonts, the radii, the shadows, the button shapes, and a few rules about how things should feel. Nothing fancy. Just one file the agent could read before writing any UI.

The change was immediate. The agent stopped guessing. It picked the colors I had already chosen, used the fonts I wanted, and stopped reaching for that one purple gradient. So I started writing more of these files, for different moods, and eventually it became a directory that other people could use too.

This post is the long version of what a DESIGN.md is, why it works, and how to write one that an AI coding agent will actually respect.

What a DESIGN.md file actually is

A DESIGN.md file is a single markdown document that lives at the root of your project. It defines the visual language of the app in plain text, in a format that an AI coding agent can read and apply consistently. The point is not to replace a real design system. The point is to give an agent something concrete to anchor on, so every screen it builds belongs to the same family.

In practice, the file holds a few things. It declares the color tokens, including primary, secondary, accent, neutral, and surface. It names the fonts, usually one for display, one for body, and one for mono. It sets the radius scale. It defines how buttons look, in primary, secondary, outline, and ghost flavors. It often includes a short paragraph about the overall feel, the kind of thing you would tell a junior designer on day one.

That is the whole file. No framework, no special syntax, no plugin. Just markdown the agent reads alongside your code.

Why a single markdown file outperforms a Storybook or Figma link

This is the part that surprised me. I assumed that the more sophisticated the source of truth, the better the result. Hand the agent a Figma link, point it at a Storybook, give it a Tailwind config with thirty custom values. None of it worked as well as the markdown file.

The reason, I think, is that an AI agent reads its context linearly. It does not browse Figma. It does not navigate to a Storybook URL and click around. It reads files. So the closer your design system is to the file the agent is already opening, the more often the agent uses it.

A DESIGN.md sits next to your README. It loads with every prompt. The agent sees it before it sees any component, which means the system is the first thing in its working memory, not the fifth.

How to write your first DESIGN.md from scratch

If you want to write one yourself, you can. It takes about an hour for the first version, less once you have done it a few times. Start with a feeling, not a color. Write one sentence about what the app should feel like when someone opens it. Calm and editorial. Loud and confident. Soft and friendly. Stark and technical. That sentence is the constraint that makes every later choice easier.

Then pick three colors. A primary that carries the brand. A neutral for surfaces and text. A single accent for the one moment of color you allow per screen. That is it. Most AI generated UI fails because it has six accent colors fighting for attention, none of them winning.

Pick two fonts, maybe three. One for headlines, one for body, optionally one for monospace. Stick with what is on Google Fonts so the agent can install them in one line. Resist the urge to be clever here. A confident pairing of two fonts beats a creative pairing of four every time.

Set your radius scale. Sharp at zero pixels, a little softer at six, friendly at twelve, generous at twenty four. Not all of these have to appear in your UI. The point is that the agent has a small, named menu to pick from instead of typing rounded-md and hoping.

Then write a paragraph about buttons. What does the primary button look like. Pill or rounded or sharp. What is its shadow. What does the outline variant look like next to it. This paragraph alone fixes more agent UI mistakes than any other section, because buttons are where consistency breaks first.

How to wire it into Claude Code, Cursor, and Lovable

The wiring is small. For Claude Code, add a CLAUDE.md to your project that says, in one line, to reference DESIGN.md for all styling decisions. Claude reads CLAUDE.md automatically and will pick the file up. For Cursor, add the same instruction in .cursorrules. For Lovable, paste the instruction once into your prompt. Lovable holds project context across messages, so you only need to do this once per project.

After that, you can stop reminding the agent to use the system. It just does. When you ask for a new screen, the agent reaches for the colors and fonts you already declared, instead of guessing fresh ones. When you ask for a button, it gets the right shape. When you ask for a card, it picks the right radius.

The whole point of a design system in 2026 is to get the agent to stop reinventing your UI on every prompt. The DESIGN.md is the smallest thing that does that.

What separates a good DESIGN.md from a bad one

The bad ones are too long. They try to specify every component, every state, every interaction. The agent reads them, gets overwhelmed, and falls back to defaults anyway. A good DESIGN.md is short enough to fit in a single screen of editor, opinionated enough that there is only one obvious answer for any visual choice, and complete enough that the agent never has to invent.

The other failure mode is being abstract. A line that says soft and modern means nothing to an agent. A line that says oklch 0.97 0.02 250 for surfaces, with a one pixel hairline at oklch 0.85 0.02 250, means everything. Be specific in the tokens, opinionated in the prose, and short overall.

If you want a shortcut, browse the directory and pick a system close to the feeling you want. Copy the file into your project, change the brand color, and you are done. That is the fastest path to a project that does not look like every other AI app.

Where this goes next

I am collecting these systems publicly because I think the directory is more useful than any single one of them. If you find one that fits, take it. If you write your own and want to share, the contribute flow is in the repo. The whole point is to lower the cost of giving an AI a real visual identity from day one.

If you read this far and still are not sure where to start, pick a system that feels close, drop the file in your project, and ship one screen with it. You will see the difference in five minutes.