DEV Community

mufeng
mufeng

Posted on

DESIGN.md: Stop Letting AI Guess What Your UI Should Look Like

#ai #claudecode #codex #designsystems

A practical workflow for turning visual intent into a versioned, lintable contract for coding agents.

I started with one broken token reference:

components:
  button-primary:
    backgroundColor: "{colors.action}"
Enter fullscreen mode Exit fullscreen mode

There was no colors.action token.

Google's official DESIGN.md linter caught it immediately:

Reference {colors.action} does not resolve to any defined token.
errors: 1, warnings: 1, infos: 2
exit code: 1
Enter fullscreen mode Exit fullscreen mode

That small failure captures the point of DESIGN.md better than a polished demo does.

AI coding tools can already produce a working page. The harder problem is getting five pages to feel like the same product, then preserving that consistency across new sessions, new agents, and later revisions.

Most teams try to solve this by adding more adjectives to the prompt:

Make it modern, clean, premium, and similar to a top-tier SaaS product.
Enter fullscreen mode Exit fullscreen mode

The prompt is not too short. It is too ambiguous.

DESIGN.md replaces that ambiguity with a file that humans can review, agents can read, Git can version, and tools can validate.

Four project documents flowing through design tokens into a structured interface

What DESIGN.md actually is

Google Labs describes DESIGN.md as a format for communicating visual identity to coding agents.

A conforming file has two layers:

  1. YAML front matter containing machine-readable colors, typography, spacing, radii, and component tokens.
  2. Markdown prose describing the design intent, component semantics, responsive behavior, and explicit do's and don'ts.

A small file might look like this:

---
version: alpha
name: Signal Desk
colors:
  primary: "#182230"
  tertiary: "#5B5BD6"
  surface: "#FFFFFF"
rounded:
  sm: 6px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.surface}"
    rounded: "{rounded.sm}"
---

## Overview

Signal Desk should feel like an operations notebook crossed with a quiet
avionics panel: compact, factual, and calm under pressure.
It is not a glossy marketing dashboard.

## Do's and Don'ts

- Do make the release state legible before secondary metrics.
- Don't add gradients, glass blur, glowing borders, or decorative charts.
Enter fullscreen mode Exit fullscreen mode

The tokens and prose do different jobs.

  • Tokens define what to use.
  • Rationale explains why it should be used that way.
  • Negative constraints define what the result must not become.

Tokens alone reduce a design system to a palette. Prose alone leaves exact values open to interpretation. Together they form a visual contract.

A vague prompt becoming a constrained DESIGN.md and then a consistent UI

Why this improves AI-generated UI

This is an engineering explanation based on the public specification and the project described below. It is not a model-vendor benchmark, and DESIGN.md does not guarantee good taste.

What it does is reduce four kinds of guessing.

1. It reduces hidden degrees of freedom

Ask for a "modern dashboard" and the model still has to choose the font, scale, palette, density, radii, shadows, motion, and responsive behavior.

Every unspecified decision is another opportunity for drift.

DESIGN.md narrows the design space before implementation begins. The model is no longer sampling from the average visual language of the web. It is working inside a smaller, explicit system.

2. It turns taste into semantic rules

#5B5BD6 is only a color value. It becomes a rule when the file says that indigo is reserved for the single primary action and the current selection.

Likewise:

  • "Do not turn every metric into a floating card" is more actionable than "use fewer cards."
  • "Status must include text and cannot rely on color alone" is more testable than "remember accessibility."

The value is not more description. It is more operational description.

3. It persists across sessions

A chat prompt is temporary. A repository file is durable.

Once design decisions live in the project, the next session, another agent, and a code reviewer can all work from the same source of truth. Git also makes those decisions diffable and reversible.

Google's CLI currently supports lint, diff, and token export. That moves part of design-system maintenance out of memory and into a normal engineering workflow.

4. It creates a verification loop

"The colors feel inconsistent" is hard to put into CI.

An unresolved {colors.action} reference is not.

Once visual rules become structured data, tooling can catch broken references, missing typography, contrast problems, and structural mistakes before the agent produces more code from a bad contract.

The four-file setup

The useful setup is not four overlapping instruction manuals. Each file should own a different question.

project/
├── README.md
├── AGENTS.md
├── DESIGN.md
├── CLAUDE.md
└── src/
Enter fullscreen mode Exit fullscreen mode
File Question it answers What belongs there
README.md What are we building? Users, product goal, scope, setup, acceptance criteria
AGENTS.md How should code be changed? Architecture, commands, tests, boundaries, security rules
DESIGN.md What should the product look and feel like? Tokens, rationale, component semantics, responsive rules, anti-patterns
CLAUDE.md How should Claude Code consume the project context? Shared-rule imports and Claude-specific workflow notes

README, AGENTS, DESIGN, and CLAUDE files converging on one implementation

One detail matters here: Claude Code's official documentation says it reads CLAUDE.md, not AGENTS.md.

If the repository already uses AGENTS.md, Anthropic recommends importing it rather than maintaining a duplicate:

@AGENTS.md

## Claude Code

- Summarize the constraints in README.md and DESIGN.md before changing UI code.
- Do not replace specific design rules with generic "modern SaaS" styling.
Enter fullscreen mode Exit fullscreen mode

Codex discovers AGENTS.md files and merges instructions along the directory hierarchy.

That makes CLAUDE.md a good adapter layer. Copying all of AGENTS.md into it creates two sources of truth. When only one copy gets updated, the model receives conflicting context.

A working example: Signal Desk

I tested the approach with a small release-status website called Signal Desk.

The implementation uses only HTML and CSS. No React, Tailwind, component library, external font, or generated product screenshot. Keeping the stack small made it easier to separate the effect of project context from the capabilities of a framework.

Step 1: define the product boundary

The README.md describes the job and acceptance criteria:

# Signal Desk

A one-page release status dashboard for independent developers.
Users should understand the current version, outstanding risk,
recent releases, and the next action within ten seconds.

## Acceptance criteria

- Use native HTML and CSS with no third-party assets.
- Support 375px mobile and 1440px desktop widths.
- Keep the page keyboard-accessible with visible focus states.
- Follow the information hierarchy in DESIGN.md.
Enter fullscreen mode Exit fullscreen mode

This comes first for a reason. A detailed design system cannot rescue an undefined product. It can only help the agent build the wrong product more consistently.

Step 2: define the engineering contract

The AGENTS.md owns implementation and verification rules:

## Implementation

- Use semantic HTML before ARIA attributes.
- Keep CSS tokens in `:root`; token names must map to `DESIGN.md`.
- Support 375px and 1440px viewports without horizontal scrolling.
- Preserve visible `:focus-visible` states and reduced-motion behavior.

## Verification

- Run `npx @google/design.md lint DESIGN.md` after editing the design contract.
- Verify that actions, warnings, and status labels do not rely on color alone.
Enter fullscreen mode Exit fullscreen mode

Notice what is missing: background colors, radii, and card styling. Those belong in DESIGN.md, not in the engineering instructions.

Step 3: give the design a specific world

The Overview does not say "modern, professional, premium."

It says:

Signal Desk should feel like an operations notebook crossed with a quiet
avionics panel: compact, factual, calm under pressure.
It is not a glossy marketing dashboard.
Enter fullscreen mode Exit fullscreen mode

That reference naturally suggests a warm paper-like canvas, dark ink, sparse status color, compact information density, restrained corners, and no glassmorphism or decorative charts.

Google's DESIGN.md philosophy makes the same point: a specific reference carries more useful information than a broad list of adjectives.

Step 4: implement and inspect the result

The final page puts release state at the top of the hierarchy and keeps one primary action above the fold. Versions and timestamps use monospace. Success and rollback states combine color with labels. Borders and tonal shifts create structure without floating-card effects.

The real Signal Desk page built for this test

This is a real local browser capture from the project. The interface copy is Chinese, but the behavior of the design contract is language-independent.

The screenshot does not prove that DESIGN.md beats every possible prompt. It proves a narrower claim: the four-file contract can produce a running artifact whose design decisions can be traced back to versioned project files.

The failure was more useful than the first render

The intentionally broken {colors.action} reference failed lint as expected.

After fixing it, the linter still reported four warnings. The neutral, line, success, and warning tokens existed but were not referenced by any component.

That exposed a common design-system mistake: more tokens do not automatically mean more control. An unused token is inventory, not a working rule.

I added semantic component mappings for page, divider, status-success, and status-warning. The final result was:

errors: 0, warnings: 0, infos: 1
exit code: 0
Enter fullscreen mode Exit fullscreen mode

The real lint record from failure to a clean result

Three practical lessons came out of that loop:

  1. DESIGN.md has to evolve with real components. It should not expand independently of the product.
  2. A small number of high-value tokens with semantic component mappings is better than hundreds of copied variables.
  3. Passing lint proves structural validity, not visual quality. Responsive inspection, accessibility checks, and human review still matter.

Do not copy another company's visual identity

The awesome-design-md repository is useful for studying how detailed design documents are structured. Its files are extracted from publicly visible websites and provided as-is. The repository explicitly says it does not claim ownership of those visual identities.

The safe use is to study decisions, not clone a brand:

  • How are primary and secondary actions distinguished with few colors?
  • How do type scale and spacing establish hierarchy?
  • How are interaction states, responsive behavior, and accessibility described?
  • Which rules are general principles, and which belong to that specific company?

Vercel's public /design.md is a useful large example. It documents the light Geist system through color scales, typography, radii, spacing, and component tokens. It also points to a separate dark-theme document.

It is not a universal starter template. Vercel's own Web Interface Guidelines explicitly separate general interface guidance from Vercel-specific preferences.

Study how constraints are expressed. Do not copy the identity they protect.

A practical adoption sequence

If you want to introduce DESIGN.md into an existing app or website, use this order:

  1. Choose one bounded screen. Start with a login, settings, dashboard, or detail page.
  2. Extract facts from the current product. Record the colors, type, spacing, radii, and states that actually exist.
  3. Write the Overview and Don'ts first. Define a concrete reference and the five to ten failure modes agents repeat most often.
  4. Add the minimum useful tokens. Only add values used by the first screen, then map them to semantic components.
  5. Put verification in AGENTS.md. State when lint runs and which viewports, states, and accessibility rules must be checked.
  6. Keep CLAUDE.md thin. Import shared rules and add only tool-specific instructions.
  7. Review design changes with diff. Run the official command before accepting token or semantic changes: 
npx @google/design.md diff DESIGN.md DESIGN-v2.md
Enter fullscreen mode Exit fullscreen mode

Design-system changes should be reviewed like API changes. They should not appear silently inside one generation.

What DESIGN.md cannot solve

DESIGN.md is not a replacement for Figma, user research, information architecture, content design, or interaction prototyping.

It is also context, not enforcement. Anthropic makes this distinction explicitly for CLAUDE.md: instructions guide model behavior, but they are not a hard configuration layer. The same caution applies to any file an agent reads.

Specific, concise, non-conflicting rules improve the odds of compliance. They do not guarantee it.

The useful scope is narrower:

  • Make fewer visual decisions implicit.
  • Keep design language stable across pages and sessions.
  • Put visual intent under version control and review.
  • Catch some contract errors before they spread into implementation.

The real gain is not that DESIGN.md raises the model's aesthetic ceiling. It raises the quality of the constraints around the model.

README.md defines what to build. AGENTS.md defines how to work. DESIGN.md defines what the result should look and feel like. CLAUDE.md adapts those shared rules for Claude Code.

That is how a one-off prompt becomes maintainable project context.

References

Top comments (0)