← All articles

Design

DESIGN.md Review: Describing Your Design System to AI Coding Agents

9 min read

Updated

An in-depth review of DESIGN.md, Google Labs' open-source specification and CLI for teaching AI coding agents your visual identity and design tokens.

If you have ever asked an AI coding agent to "build me a settings page that matches our brand" and watched it return something that looks like a screenshot from a decade ago, you already understand the problem DESIGN.md is trying to fix.

Agents do not see your Figma file. They do not see your Notion page where the color palette is locked. They guess. And every new chat is a fresh guess.

DESIGN.md is an attempt to make that guessing stop. It is a markdown file that lives in your repository and tells agents, with machine precision, what your design system actually is. The specification is open source, the CLI is free, and the format was originally extracted from Google Stitch before the team open-sourced it.

This independent review covers what DESIGN.md is, its capabilities, CLI commands, pricing, pros and cons, and how it compares to existing design token tools.

Quick verdict: If you are an AI-first development team shipping a single product, adopt DESIGN.md now. The alpha-stage breakage risk is real but small. If you run a multi-brand design organization that already lives in Tokens Studio or Figma variables, watch the format mature for a quarter before migrating.

What DESIGN.md actually is

The official specification describes DESIGN.md as "a format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system."

Structurally, every DESIGN.md file has two layers:

  1. YAML front matter at the top. This is the machine-readable layer. It defines tokens for colors, typography, spacing, rounded, and components. Token references work the way they do in any design token system: {colors.primary} resolves to your primary color, even inside component variants like button-primary-hover.
  2. Markdown prose below the front matter. This is the human-readable layer. It explains why each token exists, when to use which variant, and how the system holds together as a brand.

The spec states: "Tokens give agents exact values. Prose tells them why those values exist and how to apply them."

That split is the actual idea worth adopting. Most existing design token formats give agents values without context. Most design system documentation gives agents context without values. DESIGN.md is a format that puts both in one file an agent can read in a single pass.

The CLI: @google/design.md

DESIGN.md ships with an official command-line tool published to npm as @google/design.md. The CLI includes four primary commands:

  • lint validates structural correctness. It catches malformed YAML, broken token references like {colors.primry}, and runs WCAG contrast checks against your color pairs. If your primary button text fails AA contrast against your primary background, you know before the agent generates the component.
  • diff compares two versions of a DESIGN.md file and reports token-level changes. This is useful in code review when spacing scales shift.
  • export converts the YAML tokens into other formats. Three targets are supported: json-tailwind (Tailwind v3 config), css-tailwind (Tailwind v4 theme with CSS variables), and dtcg (the W3C Design Tokens Format Module). DTCG export provides a bridge to other token tools in the web ecosystem.
  • spec prints the format specification itself. Handy when you want to hand the specification to an agent in the same conversation as your DESIGN.md file.

You can run these commands without installing the package globally: npx @google/design.md lint.

Pricing

DESIGN.md is free. The specification is licensed under Apache 2.0. The CLI is on npm with no paywall. There is no enterprise tier, no cloud sync, and no SaaS layer. Even if related visual tools change or become deprecated, the DESIGN.md specification can continue independently because it is a Markdown-based file format with an Apache-licensed CLI.

What works

  • Agents follow the instructions. Testing with Claude Code and Cursor shows that both pick up the file with zero special prompting and produce UI matching the tokens. Instructing an agent to "build a CTA section in the brand style" results in a section using the exact hex codes, type scale, and rounded values from the YAML block.
  • WCAG linting catches accessibility issues. The contrast checker is capable of flagging button variants that fail AA contrast, and the token reference graph catches syntax typos (such as {colors.primaryHover} instead of {colors.primary.hover}) before deployment.
  • It coexists with AGENTS.md. Many teams use AGENTS.md for developer and agent runtime instructions. DESIGN.md is complementary: AGENTS.md tells the agent how to run tests, while DESIGN.md tells the agent what buttons and components should look like. Placing both in the repository root allows modern agents to read both.
  • Export to DTCG provides portability. If the format's design changes in the future, exporting via design.md export dtcg produces a W3C-standard token file that standard design token pipelines can read.

Technical limitations and rough edges

Because this is currently alpha-stage software, there are several rough edges to consider:

  • The components schema is complex. Defining variants like button-primary-hover works for simple components, but anything with compound state (size + variant + disabled + loading) gets verbose quickly.
  • There is no official Figma plugin. If designers live in Figma and developers want DESIGN.md, the transition must be bridged manually. There are community repositories collecting plugins and bridges to help manage this.
  • The tooling ecosystem is thin. Compared to established tools like Tokens Studio or Style Dictionary, DESIGN.md currently has a simpler tooling ecosystem focused on the linter and basic export formats.
  • Integration workflows. If your design team has not been involved in conversations about agent-generated UI, manual alignment will be required to translate visual rules into the markdown template.

How DESIGN.md compares

DESIGN.md vs. AGENTS.md

These files are complementary. AGENTS.md tells agents how to work on the project (setup commands, test commands, code style). DESIGN.md tells agents what the project should look like (tokens, components, brand rationale). Both live in the repository root next to your README.

DESIGN.md vs. Tokens Studio

Tokens Studio is a Figma plugin that lets designers define and sync tokens directly inside Figma. DESIGN.md is a Markdown file that lives in your repository. Tokens Studio is aimed at designers who own the visual source of truth, whereas DESIGN.md is aimed at engineers who want agents to understand the system directly from the code repository. Teams can run both, using Tokens Studio for design and exporting to DESIGN.md for engineering and AI workflows.

DESIGN.md vs. Style Dictionary

Style Dictionary is a token transformation pipeline that takes tokens in (usually JSON or YAML) and emits them as platform-specific code (iOS, Android, Web CSS, etc.). DESIGN.md acts as the source of truth for tokens and design rationale, while Style Dictionary can consume those tokens (via DTCG export) to compile them for multiple platforms.

DESIGN.md vs. standard agent instruction files

Some teams include design instructions in a section of a CLAUDE.md or .cursorrules file. This works for simple rules, but as token references, variants, or contrast requirements grow, a dedicated schema becomes necessary. Plain prose in standard rules files cannot be linted, exported, or parsed by tools other than the agent reading the file.

Community Adoption and Examples

A community-curated repository, Awesome DESIGN.md, collects brand design systems expressed in the DESIGN.md format (such as reference implementations for major tech brands). The repository has gained significant traction, indicating that developer interest in design-system formatting for AI is growing quickly. Practitioners can review these community templates to reverse-engineer layout specifications for their own brands.

Who should adopt DESIGN.md now

Recommended for:

  • AI-first development teams shipping a single product where developers manage the design system.
  • Solo developers and indie creators already building with code-generation tools like Claude Code, Cursor, or Bolt.new.
  • Open-source projects that want contributors and AI agents to produce visually consistent UI without reading extensive design system manuals.
  • Teams using Google Stitch for prototyping, as DESIGN.md serves as a native handoff format.

Not ideal for:

  • Multi-brand design organizations with mature Tokens Studio and Figma variable workflows.
  • Design-only teams who do not work directly inside Git repositories.
  • Regulated projects where alpha-status specifications cannot be easily integrated into compliance audits.

Getting started in five minutes

  1. Read the specification: Run npx @google/design.md spec to print the full specification to your terminal.
  2. Obtain a starter file: Copy an existing system configuration from community templates or generate one via Google Stitch.
  3. Save to your repository: Save the file as DESIGN.md in your repository root.
  4. Run the linter: Execute npx @google/design.md lint to identify broken token references and WCAG contrast failures.
  5. Prompt your agent: Ask your coding agent to build a CTA section, a settings page, or a pricing card, and let it read the file to align with your design tokens.

Tips for AI-Assisted Workflows

  • Pair DESIGN.md with AGENTS.md: Store codebase configuration in AGENTS.md and visual design specifications in DESIGN.md.
  • Use the prose section for guidance: Use tokens to define specific values, and use the prose section to define when to use them (e.g., "Use the alert color sparingly, only for destructive actions").
  • Generate DTCG in CI: Build a step in your continuous integration pipeline to export to DTCG, keeping your tokens compatible with standard design system pipelines.
  • Pin your CLI version: Since the tool is in alpha, pin the npm version to prevent build breaks (e.g., npm install --save-dev @google/[email protected]).

FAQ

What is DESIGN.md?
DESIGN.md is a format specification for describing a visual identity to coding agents. It combines machine-readable YAML tokens with human-readable Markdown rationale in a single repository file.

Is DESIGN.md free?
Yes. The specification is Apache 2.0 licensed, and the CLI is free to use.

Which agents read DESIGN.md?
Any agent capable of reading repository files (such as Claude Code, Cursor, Gemini CLI, or v0) can read and utilize the file. The format is agent-agnostic.

How does DESIGN.md compare to Tokens Studio or Style Dictionary?
DESIGN.md is agent-native and markdown-based. Tokens Studio is designer-first and Figma-native. Style Dictionary is a token transformation pipeline. They solve adjacent problems and can be used together.

Is DESIGN.md production-ready?
The format is currently at version alpha and the spec, token schema, and CLI are under active development. Teams should pin their CLI versions to manage updates.

Does DESIGN.md replace my design system?
No. It is a format for translating your design system values and rules into a structure that AI agents can easily understand and reference during code generation.

Summary Verdict

DESIGN.md is a design system format built specifically for how AI coding agents consume repositories. The YAML-plus-prose structure provides both values and context to agents. The CLI features a useful WCAG linter, and the DTCG export provides portability.

While the components schema remains an area of active development, teams experiencing issues with agents generating off-brand UI will find that adopting this format helps align agent output with their visual identity.

Rating: 8/10