AI Can Write Code that Passes Review, But Can't Pass Aesthetics — An MD File Is Filling the Last Gap

title: "AI Can Write Code that Passes Review, But Can't Pass Aesthetics — An MD File Is Filling the Last Gap" description: "Google's open-source DESIGN.md finally lets AI understand what 'a bit more premium' really means. But the path to codifying design specifications is far from smooth." tags: ["AI Design", "DESIGN.md", "Google", "Open Source", "AI Programming"]

All AI-generated pages look like the same person wearing different colored clothes.

Buttons are round, spacing is symmetrical, and the color palette is always the same few — Tailwind default indigo, Inter font, white background. You say "make it more premium," it swaps indigo for dark purple; you say "make it cooler," dark purple turns into fluorescent green. Same soup, different bowl.

It's not that AI has bad taste — it's that you haven't given it a standard of taste.

On the code side, we solved this long ago — CLAUDE.md tells AI which framework to use, AGENTS.md tells it how to collaborate, Skills tells it how to call tools. AI-written code can pass code review, but the UI it generates is something you don't even want to look at twice.

On the design side, we've always been missing a "constitution."

Google Labs' open-source DESIGN.md, released in April, is filling that gap. On GitHub, it hit 6,700 stars in two weeks and now sits at 25,000. But more impressive than the numbers is what it's trying to define: a standard format for design systems in the AI era.

From "Guess What You Want" to "Know What You Want"

The core idea of DESIGN.md is extremely simple: write your design system as a Markdown file that AI can read.

The file has two layers. YAML front matter holds machine-readable precise values — color hex codes, font sizes in pixels, spacing, border radius. The Markdown body holds human-readable design rationale — why this primary color, why buttons are rounded.

When AI reads primary: "#1A1C1E", it knows to use deep ink for titles; when it reads "warm beige background for reading comfort," it knows why not pure white. Precise values let it execute; design intent lets it make judgments.

Both layers are indispensable. Only values without intent — AI gets lost in unfamiliar scenarios: the spec didn't define card shadow size, so it just guesses. Only intent without values — AI knows it wants "warm" but doesn't know whether to use #F7F5F2 or #FFF8E7.

Google officially provides a Heritage example: Public Sans font, deep ink headings, Boston Clay red CTA button, warm beige background. Every value has a source, every intent an explanation. With this file, AI generates pages that look like they were designed by the same person.

More Than "Just Another Design Spec"

Some may ask: Doesn't Figma already have Design Tokens? Can't Tailwind theme config also define colors and spacing? Why invent another Markdown format?

The difference is who reads it.

Figma tokens are for designers; Tailwind config is for the compiler. DESIGN.md is for AI agents. It doesn't need Figma opened, doesn't need build tools run — just read a plain text file before generating code.

Behind this is a deeper paradigm shift: the consumer of design systems is changing from humans to AI.

Over the past decade, the main users of design systems were frontend engineers — measuring sizes from Figma, copying colors, matching spacing. Now AI agents generate UI code directly, and design systems must become AI-native formats. DESIGN.md is the product of this shift.

Its companion CLI tool confirms this. Four commands — lint, diff, export, spec — each can be called automatically by an AI agent. Run npx @google/design.md lint DESIGN.md, eight rules auto-check, output structured JSON, and the agent fixes issues based on results. AI doesn't just read DESIGN.md — it can maintain it itself.

Ecosystem Puzzle: The Trinity Is Complete

DESIGN.md doesn't exist in isolation. Put it together with CLAUDE.md and AGENTS.md, and a complete AI programming trinity emerges:

• CLAUDE.md: teaches AI how to write code — framework, naming, test conventions
• AGENTS.md: teaches AI how to collaborate — role division, process orchestration
• DESIGN.md: teaches AI how to write good-looking code — colors, fonts, spacing, design philosophy

Code conventions + collaboration conventions + design conventions — three Markdown files cover the full spectrum of AI agent code generation.

Another open-source project, Awesome Design.md, fills in the content — it reverse-engineered the visual styles of over 70 well-known brands including Claude, Notion, and Apple into DESIGN.md format. Google sets the rules, the community provides templates, and the ecosystem begins to self-sustain.

Sobering Trade-offs: One Markdown Can't Cover Everything

But DESIGN.md is far from a silver bullet.

First, the spec is still in draft. Google itself stated on LinkedIn that "spec could change under you." Building workflows around this format now may require changes next month. Early adopters pay the cost of helping Google find the potholes.

Second, static files can't handle dynamic scenarios. How do you define responsive breakpoints? How do you map tokens for dark mode? How do you describe animation timings for complex interactions? DESIGN.md currently covers none of these. A Markdown file can define "button border-radius 8px," but not "button hover 200ms ease-in scale 1.05."

Third, the community has already exposed real problems. Someone added a DESIGN.md plugin with real-time preview to Claude Code, only to find that when page design is extremely understated (like Claude's site with its warm gray tones), the preview rendering drifts significantly. The gap between static tokens and actual rendering is larger than expected.

Finally, there's a more fundamental question: Can design really be codified? When great designers make decisions, they rely heavily on intuition and context — brand tone, user psychology, cultural nuances. Whether this "tacit knowledge" can be captured in YAML key-value pairs is itself an open question.

Competitive Landscape: Who's Defining AI's Aesthetic Standards?

There's another layer of competition behind DESIGN.md.

Google is pushing this format under the guise of open-source contribution, but it's really competing for standard-setting power in AI design tools. Stitch is Google's AI design tool, and DESIGN.md was originally Stitch's internal format. Open-sourcing it means all AI tools — including competitors' — will read a format defined by Google. Who defines the format defines the rules.

Figma won't sit idly. Its Design Token standard has already been submitted to the W3C, backed by the vested interests of the entire design tool ecosystem. While DESIGN.md's token format is "inspired by W3C Design Token Format," it's ultimately a different system. Two standards coexisting means developers will eventually have to pick a side.

Meanwhile, AI programming tools like Cursor, Claude Code, v0, and Lovable are all moving toward "AI-generated UI." Whoever best integrates with design systems will capture more market share in the AI frontend development race. DESIGN.md is Google's chip in this game.

Trend Assessment

It's too early to say whether DESIGN.md will become an industry standard. But one trend is already clear:

The competitive dimension of AI programming is shifting from "being able to write code" to "being able to write good-looking code."

When all AIs can generate functionally correct code, design quality becomes the new differentiator. And design quality requires that design systems be consistently understood and executed by AI. Whether or not DESIGN.md is the final answer, it's asking the right question.

The last piece of the trinity is being filled. Code can pass review, and aesthetics can pass review too — that's the state where AI programming truly becomes usable.

As for whether that Markdown file is sufficient, let the community stomp around for another six months and we'll know.