What is DESIGN.md and How It Solves Design-System Communication for AI Coding Agents

DESIGN.md is a dual-format specification that combines YAML front-matter for machine parsing and Markdown prose for human context, enabling AI coding agents to generate consistent, accessible UI code without inferring intent from ad-hoc comments.

The google-labs-code/design.md repository defines a plain-text standard that bridges the gap between visual design systems and automated code generation. By providing a single source of truth that is both human-readable and machine-parsable, DESIGN.md eliminates the ambiguity that previously forced AI agents to guess at design intent from scattered comments or hard-coded values.

The Core Problem: Design Intent vs. AI Inference

Before DESIGN.md, AI coding agents faced a critical knowledge gap when implementing UI components. Without structured access to design tokens—such as color palettes, typography scales, and spacing values—agents relied on pattern matching from existing code or informal documentation. This led to inconsistent implementations, accessibility violations, and brand dilution as agents substituted arbitrary values rather than authoritative design decisions.

The fundamental challenge was the lack of a persistent, structured knowledge base that preserved both the raw data (hex codes, dimensions) and the rationale (why certain contrasts meet WCAG standards, how tokens relate to semantic purposes). DESIGN.md solves this by encoding design systems into a format that agents can parse deterministically while preserving the explanatory context engineers need.

How DESIGN.md Bridges the Gap

DESIGN.md files utilize a hybrid structure defined in docs/spec.md that separates machine-readable configuration from human-readable documentation.

Machine-Readable YAML Front-Matter

The top of every DESIGN.md file contains YAML front-matter that defines design tokens—reusable variables for colors, typography, spacing, and components. According to the specification, these tokens support specific value types including Color, Dimension, Token Reference, and Typography. This structure allows agents to consume the design system as JSON-compatible data, resolving references like {colors.tertiary} to concrete values such as #B8422E during code generation.

Human-Readable Markdown Context

Following the YAML block, standard Markdown sections provide the "why" behind each token. These sections explain accessibility rationale, brand guidelines, and component usage patterns. This context enables AI agents to make design-sensitive decisions rather than blind substitutions, understanding that a specific color combination exists to meet WCAG contrast requirements rather than arbitrary aesthetic preference.

Standardized Schema Enforcement

The docs/spec.md file mandates an exact shape for tokens and the required order of sections. This standardization ensures that any valid DESIGN.md file can be parsed by automated tools. The schema defines how to structure component definitions, how to reference other tokens, and which value types are valid for specific properties, creating a contract between designers and AI agents.

CLI Tooling for AI Agents

The @google/design.md CLI package provides commands that expose DESIGN.md contents as structured data for automated consumption. These tools live in packages/cli/src/ and output JSON that agents can parse directly.

Linting for Accessibility and Structure

The lint command, implemented in packages/cli/src/commands/lint.ts, validates DESIGN.md files against the specification and accessibility standards. It checks for structural errors, missing tokens, and contrast ratios using the rule engine in packages/cli/src/linter/linter/rules/contrast-ratio.ts. The output format provides machine-readable findings that agents can use to automatically fix violations or report issues to developers.

npx @google/design.md lint DESIGN.md

{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

Diffing for Regression Detection

The diff command, found in packages/cli/src/commands/diff.ts, compares two versions of a DESIGN.md file to surface token-level changes. This allows AI agents to detect when design systems evolve and determine which downstream code requires updates to maintain synchronization.

npx @google/design.md diff DESIGN.md DESIGN-v2.md

{
  "tokens": {
    "colors": { "added": ["accent"], "removed": [], "modified": ["tertiary"] },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "regression": false
}

Practical Token Implementation

The specification allows components to reference design tokens using a bracketed syntax. The compiler in packages/cli/src/linter/spec-gen/compiler.ts resolves these references to generate the final JSON schema used by agents.

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px

When generating code, an AI agent resolves {colors.tertiary} to its defined value and produces CSS or framework-specific components that automatically respect the brand palette and accessibility requirements.

Summary

• DESIGN.md combines YAML front-matter for machine parsing with Markdown prose for human context, solving the communication gap between design systems and AI coding agents.
• The specification in docs/spec.md defines a standardized schema for tokens (colors, typography, dimensions) that ensures consistent parsing across different tools.
• The CLI tooling (@google/design.md) provides lint and diff commands that output JSON for automated consumption, enabling agents to validate accessibility and detect regressions.
• Token references allow agents to generate UI code that automatically respects brand guidelines and WCAG contrast requirements without human intervention.
• Key implementation files include packages/cli/src/commands/lint.ts for validation, packages/cli/src/commands/diff.ts for version comparison, and packages/cli/src/linter/linter/rules/contrast-ratio.ts for accessibility checking.

Frequently Asked Questions

What is the exact file structure of a DESIGN.md file?

A DESIGN.md file begins with YAML front-matter delimited by triple dashes, containing token definitions for colors, typography, spacing, and components. This is followed by Markdown sections that provide human-readable context and rationale. The docs/spec.md file defines the mandatory section order and required token value types.

How does DESIGN.md differ from CSS variables or JSON tokens?

Unlike static CSS variables or raw JSON, DESIGN.md preserves design rationale alongside the data. The Markdown sections explain why specific tokens exist and how they should be used, while the CLI tooling provides validation and diffing capabilities that standard token formats lack. This dual-format approach allows both humans and AI agents to understand intent, not just values.

Can AI agents automatically fix design violations detected by the linter?

Yes. The lint command outputs structured JSON findings with specific paths and severity levels that agents can parse programmatically. An AI agent can consume this output to automatically adjust component code, update token references, or suggest alternative color combinations that satisfy the contrast-ratio rules defined in packages/cli/src/linter/linter/rules/contrast-ratio.ts.

Where is the formal specification for DESIGN.md defined?

The formal specification resides in docs/spec.md within the google-labs-code/design.md repository. This document defines the exact shape of tokens, supported value types (Color, Dimension, Token Reference, Typography), and the required order of sections. Additional implementation details can be found in the CLI source code, particularly in packages/cli/src/linter/spec-gen/compiler.ts which generates the JSON schema from the YAML front-matter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}