Google's design.md: A Spec to Stop Agents Writing Ugly UI

Coding agents are remarkably good at writing functional React components, setting up Express routes, and refactoring legacy Python. But when it comes to frontend aesthetics, they are visually illiterate. Left to their own devices, LLMs will happily generate a button with neon green text on a bright blue background, or hallucinate a dozen random Tailwind spacing classes that completely break your layout.

To solve this, Google Labs has introduced design.md, an open-source format specification designed to give AI coding agents a persistent, structured understanding of a project's design system. By combining machine-readable design tokens with human-readable design rationale, the spec aims to act as a guardrail for AI-generated user interfaces.

The Hybrid Spec: Tokens Meet Prose

Most design systems are split. Developers use JSON or YAML files (like Style Dictionary) to feed design tokens into their build pipelines, while designers maintain documentation in Figma or a wiki. Coding agents struggle with this split. If you only give them raw JSON tokens, they lack the context of when and why to use them. If you give them a massive PDF of brand guidelines, they fail to parse the exact hex codes and spacing values reliably.

design.md bridges this gap by using a single file structured with YAML front matter for machine-readable tokens and Markdown for semantic prose.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a premium matte finish.

## Colors
The palette is rooted in high-contrast neutrals and a single accent color.
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders and metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

The YAML front matter defines the strict values (colors, typography, rounded corners, spacing, and component-specific tokens). The Markdown body below it provides the contextual rules. When an LLM reads this file, it gets the exact hex code for the tertiary color (#B8422E) and the explicit instruction that this color is "the sole driver for interaction," meaning it should only be applied to interactive elements like primary buttons or active states.

To keep things predictable for parser engines, the specification enforces a strict ordering for Markdown sections. If present, headings must appear in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, and Do's and Don'ts.

Linting and Diffing the Visual Pipeline

Static configuration files are only useful if they can be validated. Google Labs has released a CLI tool on npm under the @google/design.md package to lint and diff these files.

Running the linter parses the file, checks for broken token references, validates the token schema, and performs WCAG contrast ratio checks on your defined components.

npx @google/design.md lint DESIGN.md

The linter outputs structured JSON, making it easy to integrate into CI/CD pipelines or pre-commit hooks:

{
  "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
  }
}

There is also a diff command designed to compare two versions of a design system. This is particularly useful when you update your brand guidelines and need to verify if the changes will break existing token references or introduce prose regressions that might confuse an agent.

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

The Developer Angle: Integration and Trade-offs

For a working developer, adopting design.md is not about replacing your existing design system tooling. It is about creating a translation layer for your AI tools.

If you are already using Tailwind, Style Dictionary, or Figma Variables, you do not want to manually maintain a duplicate YAML file. The most practical path to adoption is writing a script that exports your existing design tokens into the YAML front matter of a DESIGN.md file, and then appending your high-level design guidelines as the Markdown body.

Once the file lives in the root of your repository, you can feed it to your coding agents in a few ways:

1. System Prompts: If you are building custom agentic workflows using LangChain or LlamaIndex, you can programmatically read DESIGN.md and inject it into the system prompt whenever the agent is tasked with modifying or creating UI components.
2. IDE Context: For tools like Cursor or Copilot Workspace, you can reference the file in your .cursorrules or system instructions, ensuring the agent always references the local DESIGN.md before writing CSS, Tailwind, or styled-components.
3. CI/CD Guardrails: You can run the @google/design.md linter in a GitHub Action to block PRs if an automated agent (or a human developer) introduces a token change that violates contrast accessibility standards.

However, the specification is currently in "alpha" and has some notable limitations. The component token schema is relatively basic, supporting only a handful of properties like backgroundColor, textColor, typography, rounded, padding, size, height, and width. Complex component states (like hover, active, or disabled) must be expressed as separate component entries (e.g., button-primary-hover) rather than nested objects, which can make the YAML front matter verbose and repetitive.

The Verdict

design.md is a highly pragmatic solution to a very modern problem. It acknowledges that coding agents do not just need raw variables; they need the semantic guardrails that human designers write in documentation.

While the specification is still early, the concept is solid. If agent frameworks and IDEs begin auto-detecting DESIGN.md in the same way they look for .gitignore or package.json, it could easily become the standard way we keep AI-generated code on-brand and accessible.