If you’ve ever asked AI to design something and thought “that’s not quite my style”, you’ve already run into the problem DESIGN.md is trying to solve.
AI is getting very good at building things.
What it’s still not great at is being consistent.
That’s where this comes in.
What is DESIGN.md?
DESIGN.md is a simple text file that describes how your product should look and feel.
It came out of experiments at Google Labs (via a project called Stitch), but the important bit is this:
it’s not a Google thing.
It’s just a plain text format.
Which means:
- anyone can create one
- any AI tool can read one
- any project can use one
Think of it as a portable design system for AI.
Why this matters now
We’re moving into a world where:
- AI builds interfaces
- AI edits layouts
- AI generates entire products from prompts
And in that world, the question changes from:
“Can AI design this?”
to:
“Can AI design this in my style, consistently, every time?”
Without some kind of shared design language, the answer is usually no.
You get:
- slightly different colours
- inconsistent spacing
- components that almost match, but not quite
It works… but it doesn’t feel right.
How DESIGN.md fixes that
A DESIGN.md file gives AI two things at the same time:
- Clear rules
- Context for those rules
And that combination turns out to matter a lot.
How it actually works
A DESIGN.md file has two parts working together.
1. The rules (at the top)
At the top, you’ll see something called YAML.
It stands for “YAML Ain’t Markup Language”, which is a slightly nerdy way of saying:
👉 it’s just a clean way of listing settings
For example:
colors:
primary: "#1A1C1E"
background: "#F7F5F2"
spacing:
small: "8px"
medium: "16px"
You’re simply naming things and giving them values.
No real “coding” involved.
This part gives AI precision.
No guessing, no interpretation.
2. The explanation (below)
Under that, you write normal text using Markdown.
Markdown is just a simple way of writing formatted text
(headings, paragraphs, lists).
Example:
# Design principles
This design should feel calm and minimal.
Use generous spacing to avoid clutter.
Primary colour should be used sparingly for emphasis.
This part explains:
- why the design looks the way it does
- how things should feel
- when to use certain styles
This gives AI judgement.
Why both parts matter
If you only give AI rules:
- it follows them rigidly
- but doesn’t always apply them well
If you only give AI explanation:
- it understands the intent
- but still guesses the details
Put them together and you get something much more useful:
- rules = precision
- explanation = judgement
That’s the core idea behind DESIGN.md.
The bigger shift
This is the part that’s easy to miss.
For years, design systems have lived in tools:
- Figma
- Sketch
- internal docs
They’re visual, collaborative, and human-first.
But AI doesn’t live in those tools.
AI lives in:
- prompts
- files
- repositories
So design systems are starting to move there too.
From:
“Here’s a Figma file, go look at it”
To:
“Here’s a file you can read and design from”
That’s a big shift.
A simple example
---
colors:
primary: "#1A1C1E"
background: "#F7F5F2"
radius:
default: "12px"
---
# Style
Keep things minimal and calm.
Use the primary colour sparingly for emphasis.
Buttons should feel soft, with rounded corners and subtle shadows.
That one file is enough for an AI tool to start producing designs that feel consistent.
Why this could become important
Right now, this still feels a bit experimental.
But look at the direction things are moving:
- more products are being built with AI
- more teams are using multiple AI tools
- more work is happening in code and text
At some point, consistency becomes the bottleneck.
And when that happens, something like DESIGN.md starts to look less like a nice idea and more like a requirement.
Not because it’s perfect.
But because it’s:
- simple
- portable
- understandable by both humans and machines
The takeaway
README.md tells AI how your project works
DESIGN.md tells AI how your project looks
And if AI is doing more of the building, that second file starts to matter a lot more.
Not overnight.
But over the next few years, this idea or something very close to it is likely to show up everywhere.
Quietly shaping how things look, without most people ever noticing the file behind it.
How to try this out (takes 2 minutes)
If you want to see this working, it’s surprisingly easy.
- Go to https://claude.ai/design
- Grab an example
DESIGN.mdfrom
https://github.com/VoltAgent/awesome-design-md - Upload the file into Claude
- Ask it to design something using that file
That’s it.
You’ve just given the AI a design system to follow.
Instead of starting from scratch, it now has:
- clear rules
- a defined style
- and context for how things should look
…and the difference is pretty obvious.
Leave a Reply