DESIGN.md Guide for AI Agent Design Systems

Key takeaways#

• DESIGN.md is a Google Labs Code format for giving coding agents a persistent, structured description of a visual identity.
• A DESIGN.md file combines YAML front matter for exact design tokens with Markdown prose that explains how and why those tokens should be used.
• The official repository includes a specification, examples, and a CLI published as @google/design.md for linting and diffing design files.
• The format is most useful when an AI coding agent must generate UI that stays aligned with a product’s typography, color, spacing, and component rules.

What DESIGN.md is#

DESIGN.md is a resource and file format for describing a design system to coding agents. The official Google Labs Code repository defines it as a format specification for describing a visual identity to coding agents, giving agents a persistent and structured understanding of a design system. In practice, it turns brand and interface rules into a Markdown file that can live beside source code and be read by both humans and AI tools.

The core idea is simple: tokens give the agent exact values, while prose gives the agent judgment. A color token can tell an agent the exact hex value for a call-to-action button. A prose section can explain when that color is appropriate, what tone it communicates, and what contrast rules must be respected. That combination matters because coding agents often need more than raw variables to make good UI decisions.

How the format works#

A DESIGN.md file has two layers. The first layer is YAML front matter at the top of the file. This is the machine-readable layer. It can describe colors, typography, spacing, radii, shadows, components, and related design tokens. The second layer is a Markdown body with human-readable rationale. The body explains visual identity, accessibility expectations, brand tone, component behavior, and examples.

This dual structure makes the file useful for agentic development. An agent can parse tokens deterministically, then use the Markdown explanation when it needs to make choices that are not just variable substitution. For example, a product may use one type scale for marketing pages and another for dense dashboards. Tokens alone do not always encode that preference clearly. A DESIGN.md section can spell it out.

CLI workflow#

The repository documents an npm package named @google/design.md. Developers can install it with npm or run it through npx. The README shows linting a design file with npx @google/design.md lint DESIGN.md, producing structured JSON output, and diffing two versions with npx @google/design.md diff DESIGN.md DESIGN-v2.md. The README also notes a designmd alias for environments where the design.md command name conflicts with Markdown file handling.

The lint command is the first workflow to try. It validates structure, checks token references, reviews WCAG contrast ratios, and reports findings that coding agents can act on. The diff command is useful when a design system changes. It can catch token-level and prose regressions before those changes are handed to a code-generation agent.

When builders should use it#

Use DESIGN.md when you want coding agents to generate UI that matches a brand or product system without repeating a long style brief in every prompt. It is especially useful for teams using agents to scaffold pages, refactor components, build prototypes, or maintain multiple frontends. The file can become a stable contract between design and implementation.

It is also useful for solo builders. A single DESIGN.md file can capture your preferred fonts, colors, interaction style, and component conventions. When a coding agent starts a new screen, it has a shared source of truth instead of guessing from nearby files or generic defaults.

Practical adoption steps#

Start with a small file. Capture your primary colors, text styles, spacing scale, button styles, and accessibility notes. Add short rationale after each major section. Then run the linter and fix structural issues before giving the file to an agent. Once the agent starts producing UI from it, refine the prose where outputs drift from your intent.

Teams should keep the file in version control and review changes like code. If a token or guideline changes, run a diff and check a sample generated screen. This keeps the design contract explicit and makes agent output easier to debug.

Common pitfalls#

Do not treat DESIGN.md as only a token dump. The value comes from pairing exact values with design rationale. Do not let the file become stale; a stale design contract can make agent output worse than no contract. Finally, do not assume the format replaces visual QA. It gives agents better instructions, but builders still need to review accessibility, responsive behavior, and production UI details.

Related links#

• Official GitHub repository: https://github.com/google-labs-code/design.md
• Specification homepage: https://stitch.withgoogle.com/docs/design-md/specification
• npm package: https://www.npmjs.com/package/@google/design.md