What Is a DESIGN.md File? (And Why Every Vibe-Coded Project Needs One)
A DESIGN.md is the single file that keeps your AI-built app looking consistent from the first screen to the last. Here's what it is, how it works, and why it matters more than any prompt.
If you've spent any time building with AI tools, you've probably run into the moment where your app stops looking like one product. The first screen is sharp. The tenth screen has drifted somewhere else entirely. A DESIGN.md is the fix for that. So what is a DESIGN.md file, and why does it matter more than any single prompt? Here's the full picture.
The short version
A DESIGN.md is a markdown file that holds your project's design decisions in one place. Colors, typography, spacing, component styles, all written down as specific rules. It lives in your project, and your AI tool reads it every time it builds something new. It's a design system in markdown form, which is what makes it so easy for an AI coding tool to read and follow.
Think of it as the design source of truth for your whole app, or the AI design reference file the tool checks before it builds. Instead of the design living only in your head or in a prompt you typed three sessions ago, it lives in a file the AI reads on every build.
How it's different from a SKILL.md
These two files get mixed up, so here's the clean split.
A SKILL.md is the instruction set. It has your design guidelines plus specific direction for how the AI should apply them: build buttons this way, use these patterns, avoid these mistakes. It teaches the AI how to design in a particular style.
A DESIGN.md is the reference. It holds the settled decisions for your specific project and gets pulled in every time the AI builds a new page, so everything stays consistent as the app grows. One teaches the approach. The other keeps your project aligned to it.
Most well-built skills come with both.
Why it matters so much
The core problem with AI coding tools is that they have no memory of the design choices they made earlier. Every new prompt starts fresh. Ask for a settings page today and a dashboard tomorrow, and the tool makes reasonable design decisions each time, just not the same ones. The padding shifts. A new shade of blue appears. The corners round differently.
A DESIGN.md closes that gap. Because the AI reads it before building, screen ten follows the same spec as screen one. The decisions stop drifting because they're written down in a place the AI always checks.
That consistency is a huge part of what makes an app look professionally designed. Same spacing everywhere, same components everywhere, one palette applied the same way throughout. It reads as finished. Miss it and even a clever app looks unpolished.
What goes in one
A solid DESIGN.md usually covers:
- Colors with exact hex values for background, surface, text, and accent
- Typography: the fonts, the size scale, and weight usage per hierarchy level
- Spacing: a consistent scale, often built on an 8px grid
- Components: border radius, border treatment, shadow rules, button and input styling
- Constraints: the things to avoid, like default framework colors or mixed font weights
The more specific each rule, the less room the AI has to improvise its way into inconsistency.
Where to get one
You can write a DESIGN.md from scratch, and it's a good exercise. It also takes time and a decent eye for design specifics. The faster path is to start from a proven one.
Skills UI skill files come with a DESIGN.md built in for each style, already filled with the exact colors, type, spacing, and component rules that make the aesthetic work. Drop one into your project and your AI tool has its design reference from the first build.
Download a skill with a DESIGN.md →