What does quality design look like?
Agents can build consistent, branded UI with the right direction, not guesswork. One plain-text file is all it takes.
Generate some UI with your LLM of choice. It's probably fine with a logical structure that does what you asked, but something feels off. The colors feel generic. The buttons look like every other button you've seen. Run the same prompt tomorrow and you'll get something slightly different and just as generic, because there's nothing anchoring it.
❇️ The agent isn’t missing a skill, it’s missing direction.
We're meticulous about prompting for functionality (what the app does, how data flows, etc...) but say almost nothing about how the experience should feel. The AI fills that void with its best guess, and its best guess looks like every other AI-generated interface you've ever seen. Any consistency you're getting is largely accidental. Which is great at first, but it only works until it doesn't. One new component or prompt style and the floor drops.
The solution? One markdown file.
If you’re used to opening projects in GitHub you probably already know about a README.md file. It’s written for humans to read and gain an overview of the project. There’s also a file that tells coding agents how to build the project, such as a CLAUDE.md file. A DESIGN.md is the same idea, but for visual decisions. A plain-text file, living in your project, containing everything an AI needs to make consistent UI choices every single time. Not written for humans to admire, written for AI to execute. No Figma, no design software required.
A solid DESIGN.md covers six things, and the specificity is what makes it work:
-
Colors – Hex values with usage rules. ”#C8914A for all primary CTAs”, not “use warm colors.”
-
Typography – Font names, type scale, hierarchy. This alone helps cure most cross-session inconsistency.
-
Spacing & Layout – A base grid unit so interfaces feel intentional, not random.
-
Components – Button radius, card structure, input states. The more specific, the better.
-
Voice & Tone – How the brand speaks. The words matter as much as the visuals.
-
Do's & Don'ts – Guardrails that catch the AI before it drifts. "Never use drop shadows."
How do I get started?
None of these require design expertise. Pick whichever matches where you are right now and get started.
-
Let AI write it – Describe the vibe, ” A warm boutique hotel, with earthy tones, and quiet luxury" and let the AI translate it into a full system. You edit, not invent. A vibe in a prompt disappears when the session ends, but a vibe captured in a DESIGN.md becomes a system that persists.
-
Extract from an existing brand – Have a company website, brand guidelines PDF, or even just a logo? Provide a URL or image, and then let AI pull your palette, typography, and style patterns automatically. Your brand is already there, this just gives it a home your AI can read and act upon.
-
Write it by hand – Start minimal with just colors and typography. When the AI produces something that's almost right but not quite, that's your sign to add a rule. The file teaches you what to put in it.
Same prompt. Same AI. Completely different result. The AI didn't get smarter, it just got direction.
Start Before It's Perfect
Before your next time building with AI, spend a few minutes writing a design markdown file. Don't wait until it's perfect. Start with a few colors, typography preferences, and one or two component rules and ship it. A rough file beats no file every time.
❇️ A rough DESIGN.md file that took you 20 minutes to generate is infinitely more useful than a perfect one you never write.
This is a living document that grows with you. Start with what meets your needs for now and graduate to a more refined file as you learn what your project needs.
Grab the starter template and example file
Add your colors, fonts, and a few component rules and you're set.
