How to Use DESIGN.md With AI Coding Agents

Google’s alpha DESIGN.md repository had more than 26,900 GitHub stars on August 4, 2026. That is a lot of developers asking AI coding agents to stop inventing a fifth shade of teal. It is not, however, proof that dropping one file into a project will fix every beige dashboard.

If you’re searching for how to use DESIGN.md with AI coding agents, the useful answer has three parts: write exact design tokens, explain the reasoning behind them, and validate the file before an agent touches your interface. Then tell the agent to read it explicitly. File names are conventions, not telepathy.

What DESIGN.md actually does

Google open-sourced the draft specification on April 21, 2026 after using the format in Stitch. The goal is portability: move design rules between projects and tools without forcing an agent to reverse-engineer intent from screenshots.

The official specification defines two layers. YAML front matter contains normative values—colors, typography, spacing, rounding, and component properties. Ordered Markdown sections explain why those values exist and where they belong. Tokens tell the agent that primary is #0B7285; prose tells it not to paint every card teal because teal is reserved for actions.

That distinction matters across different AI coding assistants. Exact values travel well. Unwritten taste does not. The format is still marked alpha, so treat it as a versioned interface under review, not stone tablets from Mountain View.

How to use DESIGN.md with AI coding agents

Start with tokens the agent must not invent

Before opening a text editor, identify the design source your team already trusts: CSS variables, a Tailwind theme, token JSON, or a reviewed component library. DESIGN.md should translate that source for an agent, not compete with it. Prefer semantic names such as text-muted and action-primary over a paint-box list like gray-500 and teal-700; roles survive redesigns better than hex codes masquerading as architecture.

Create DESIGN.md in the repository root. Start small: one usable palette, one body style, a spacing scale, rounding, and a component that references those tokens. A minimal file is more enforceable than a 900-line museum catalog nobody updates.

---
name: Acme
version: alpha
colors:
  primary: "#0B7285"
  on-primary: "#FFFFFF"
  ink: "#132238"
  surface: "#F6F8FA"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: 12px
---

## Overview
Quiet utility: dense enough for work, calm enough for reading.

## Colors
Use primary teal for actions. Use ink for text and surface for cards.

## Typography
Body copy stays at 1rem with a 1.5 line height.

## Layout
Use the spacing scale. Do not introduce one-off gaps.

## Shapes
Controls use modest rounding; cards should not look inflatable.

## Components
Primary buttons use the documented token references.

## Do's and Don'ts
Do preserve contrast. Don't invent gradients or new token values.

Write rationale for decisions, not adjectives

“Clean and modern” gives a model room to generate whatever won Dribbble that morning. “Primary teal is reserved for actions; body text uses ink; cards use surface” supplies a decision rule. The Design Tokens format exists to move named decisions between tools. DESIGN.md adds human rationale beside those values so an agent can apply them instead of merely copying them.

Do not duplicate the entire component library. Record the tokens and patterns whose absence causes visible drift. If a component already lives in code, name that implementation and instruct the agent to reuse it. Two sources of truth are just one source of arguments.

Use component tokens for invariants an agent can apply mechanically: background, text color, typography, radius, padding, and size. Put behavioral rules in prose and point to the real implementation path—for example, “Use src/components/Button.tsx; do not rebuild buttons with page-level CSS.” The file should narrow the model’s choices without pretending Markdown is a component framework.

Lint the contract before the agent uses it

The CLI turns DESIGN.md from decorative documentation into a testable contract. Run the linter before asking an agent to build anything:

npx @google/design.md lint DESIGN.md

The repository documents 11 checks, including broken token references, missing primary colors, low component contrast, orphaned tokens, missing typography, section order, and likely misspelled keys. In a local test with version 0.4.0, a sample passed with zero errors and correctly warned that an ink color was defined but unused. The linter exits with code 1 for errors, which makes it useful in CI rather than merely reassuring in a terminal.

npm install --save-dev @google/design.md@0.4.0
npx designmd lint DESIGN.md
npx designmd diff DESIGN.md DESIGN-next.md
npx designmd export --format css-tailwind DESIGN.md > theme.css
npx designmd export --format dtcg DESIGN.md > tokens.json

Test it with one deliberately boring screen

Do not begin the rollout with a homepage redesign and seventeen animated states. Pick a representative screen containing a heading, body copy, a card, a form control, and a primary button. Give the agent a narrow task and require it to read DESIGN.md first.

Inspect the code diff, not only the screenshot. A screenshot can flatter a broken token pipeline; a code diff will not.

• Every color, spacing value, and radius maps to a documented token.
• The agent reuses existing components instead of drawing local substitutes.
• No unexplained one-off CSS values appear in the diff.
• The final DESIGN.md lint run reports no errors.

Repeat the same task in a fresh agent session. That removes helpful context from the first conversation and tests whether the repository carries enough information on its own. If the second run drifts, strengthen the rule or the activation instruction. Do not respond by pasting a longer prompt into every future chat; that recreates the problem DESIGN.md is supposed to solve.

Pinning 0.4.0 is not romantic, but neither is discovering that an alpha parser changed during a release build. Review token diffs like code diffs. If agents can modify DESIGN.md, include it in the same approval boundary as dependency files and follow a security checklist for AI coding agents.

Keep DESIGN.md, Skills, and MCP in separate lanes

DESIGN.md is one layer of an AI-ready design system, not the whole stack. The cleanest architecture gives static rules, repeatable procedures, and live connections different homes.

Layer	Best job	Use it when
DESIGN.md	Stable tokens and visual rationale	The rule belongs beside the code and changes through review
Agent Skill	Repeatable build and validation procedure	The agent should load a workflow, scripts, references, or templates on demand
MCP	Live external data and actions	The agent needs current Figma state, an asset registry, or another remote system

A practical escalation path looks like this: store the approved palette and component rules in DESIGN.md. Add a Skill when “build a component” becomes a repeatable sequence with linting, screenshots, and review criteria. Add MCP only when the sequence must fetch current remote state or perform an external action. Each extra layer should buy a capability, not a more impressive architecture diagram.

The Agent Skills open format packages instructions in a SKILL.md folder and can bundle scripts, references, and assets. A design Skill might tell an agent to read DESIGN.md, reuse existing components, run the linter, capture a screenshot, and compare the result. The Skill owns the procedure; DESIGN.md owns the values.

MCP’s official definition is broader: it connects AI applications to external systems, tools, and workflows. That is appropriate when the latest design state lives outside the repository. Our Google Developer Knowledge MCP setup shows the same pattern for live documentation. A local palette does not need a network connection merely to remain blue.

One caveat: portable does not mean universally auto-discovered. Add an explicit repository instruction such as: “Before UI work, read ./DESIGN.md; treat its front matter as authoritative; do not invent tokens; run the linter after changes.” Put that in the instruction file your client actually loads. If the process grows beyond one sentence, graduate it to a Skill.

The adoption rule that will age well

The unresolved question is whether coding-agent clients will converge on native DESIGN.md discovery, or whether explicit repository instructions will remain the only reliable trigger. Alpha formats earn trust through boring things: stable parsing, predictable diffs, and clients that agree on when to read them.

A design file earns its place when it can reject a wrong token, not merely inspire a prettier prompt. The next tagged @google/design.md release after 0.4.0—or a stable-version declaration in the official repository—will show whether this draft is settling into a dependable contract.