DESIGN.md Needs a Spec, Not Just a Gallery

The first wave of DESIGN.md enthusiasm was about examples. People wanted files that captured the feel of Claude, Notion, Apple, Linear, Vercel, or other recognizable products, then handed those files to coding agents as style references. That is useful, but it is not enough.

Google Labs’ design.md project points to the more durable layer: the specification. If AI-generated UI is going to become part of normal product development, design context needs rules, validation, and export paths. A gallery can inspire an agent. A spec can constrain it.

Awesome Design.md collection page — A gallery of design files is useful for starting points, but it does not define the contract every file should follow.

Examples solve taste discovery

Collections such as awesome-design-md are valuable because they turn recognizable visual languages into agent-readable documents. They answer a practical question: “What should this product feel like?” For many teams, that is already better than asking an agent to make a page “modern” or “premium.”

But example files vary. Some are richer than others. Some contain enough component guidance; others are mostly mood. Without a formal boundary, a DESIGN.md file can become another long prompt with a nicer name.

A spec solves reliability

Google’s project defines a two-layer structure: YAML front matter for machine-readable design tokens, and markdown sections for human-readable rationale. The tokens can describe colors, typography, spacing, radius, and component properties. The prose can explain the visual identity, color logic, layout rules, elevation, shapes, components, and do’s and don’ts.

This matters because agents need both precision and judgment. If only precision is provided, the agent can apply values mechanically while making bad layout decisions. If only prose is provided, the agent may understand the mood but drift in implementation. The spec forces both into one artifact.

Google Labs design.md repository — Google design.md formalizes the file format instead of treating design context as an informal prompt convention.

Validation changes the role of DESIGN.md

The CLI is the operational bridge. lint can surface broken references, missing tokens, section problems, or contrast issues. diff can compare two versions and detect token-level regressions. export can turn the file into Tailwind theme configuration or standard design token output.

That moves DESIGN.md closer to code review. A design change can be discussed as a versioned diff. A regression can be flagged before an agent produces a full UI. A team can preserve visual identity even as different agents, models, and frameworks touch the same product.

The practical pattern

Use galleries to find a starting visual language.
Normalize that file against the Google design.md structure.
Add explicit do’s and don’ts for the product’s real constraints.
Validate the file before large UI generation tasks.
Export tokens into the implementation stack so design context and code stay aligned.

A gallery gives an agent taste. A spec gives the team control over that taste. For AI UI work, the second layer is what makes the first layer safe to reuse.