Is DESIGN.md the "Visual Specification" for the AI Era?
When you have AI build a UI, the first problem you usually run into isn't a lack of functionality, but a lack of consistency.
The corner radius of buttons differs from screen to screen.
The way margins are handled shifts every time.
Even though it's supposed to be the same product, it looks like it was made by different people on every page.
Recently, DESIGN.md has emerged as one answer to this problem.
In a nutshell, DESIGN.md is a file that turns colors, fonts, margins, and component quirks into text that is easy for AI to read. In the community, it is often organized such that while AGENTS.md describes "how to build," DESIGN.md describes "how it should look." In other words, it is the idea of separating the implementation contract from the visual contract.
I think this separation is quite essential.
Until now, we have been cramming technical requirements and design requirements together into one-off instructions for AI.
Things like: build it with Next.js, make it accessible, keep it modern, but don't play around too much, make it look a bit like Notion, keep the margins wide, make the text easy to read, and so on.
With this approach, the constraints shift with every conversation.
It's not so much that the AI is bad, but that the premises are shifting every time.
What's interesting about DESIGN.md is that it allows you to move those shifting premises outside of the conversation.
Instead of relying on the mood of the moment, you can keep it as a file.
And since it's Markdown, it's readable by humans, you can track diffs, and it's easy to start making rough edits.
Looking at the chapter structure widely shared in the community, DESIGN.md is not just a memo for color schemes.
Visual theme and atmosphere
Color palette and roles
Typography rules
Component styles
Layout principles
Depth and layering expressions
Dos / Don'ts
Responsive behavior
Prompt guide for agents
It is treated as a document that concretely defines "visual judgment criteria" in forms like these.
The important thing here is that DESIGN.md is not a magic paper that automatically generates good taste.
It is actually the opposite; it is a file for verbalizing ambiguous aesthetic sensibilities in a way that you cannot escape.
Instead of saying "make it stylish,"
you specify judgments concretely, like: "Background is off-white, body text is dark gray, headings are slightly condensed, cards have weak shadows, and corner radii are small."
For AI, constraints are more effective than adjectives.
DESIGN.md is a place to accumulate those constraints.
For example, at a minimum, you can start with something like this.
DESIGN.md
Visual theme and atmosphere
Calm, minimal, and easy to read.
Maintain a quiet tone. Do not use flashy gradients. Do not use excessive decoration.
Color palette and roles
Background color: #FAFAF7
Body text: #1F1F1F
Secondary text: #5F5F5F
Accent color: #2F6FED
Border: #E7E5E4
Typography rules
Headings are bold, with slightly condensed letter spacing.
Body text is normal weight, maintaining high readability.
Do not make headings too large on mobile.
Component Styles
Buttons: 8px rounded corners, subtle shadows.
Cards: White background, use thin borders.
Input fields: Keep them simple and flat, with clear indicators when focused.
Dos / Don'ts
Dos:
Use generous spacing
Keep the information hierarchy calm and clear
Don'ts:
Do not use neon colors
Do not mix multiple different shadow styles
Even this much is far more powerful than praying for the AI to "make it look good" in every prompt.
However, there is one point to keep in mind. The DESIGN.md libraries spreading through the community are based on design tokens extracted from public websites, and the providers themselves clearly state that "these are based on publicly available CSS values and do not claim ownership of the visual identity of each site." In other words, many of the DESIGN.md files in circulation are not official brand guides, but reference materials reconstructed from public-facing interfaces.
This point is quite important.
DESIGN.md is more powerful when used to solidify your own product decisions rather than as a tool to copy the atmosphere of other companies.
If you use it as a template for imitation, you will inevitably end up with something that just "looks the part."
But once you start writing down your own colors, typography, spacing, and prohibitions, it suddenly becomes a design.
Perhaps the true value of DESIGN.md is not that the AI becomes smarter.
It is that human aesthetic sense finally becomes a reusable asset.
Until now, design intent has tended to be buried deep within Figma, oral nuances, and vague atmospheres.
DESIGN.md drags that out into plain text that both AI and humans can read.
In that sense, I think this is not just a trendy file name, but a sign that design culture in the AI era has begun to change.