Teaching AI Coding Agents Your Brand Style with DESIGN.md

Ask an AI coding agent to build a new React button component, and it will write clean, functional TypeScript in seconds. But the button will likely be a slightly off-brand blue, the padding will violate your spacing scale, and the text contrast might fail accessibility standards. You then find yourself in a tedious cycle of prompting: "No, use our primary brand blue, and make sure the corner radius matches our other inputs."

This is the AI user interface gap. Large language models are excellent at syntax and logic but blind to visual context and brand constraints. They lack a persistent, standardized way to consume design systems.

To address this, Google Labs recently open-sourced design.md, a specification designed to give coding agents a structured, persistent understanding of a visual identity. Originally developed for Google's Stitch app, the format is now open-source so it can be used across different platforms, developer tools, and agentic workflows.

The Hybrid Architecture: Tokens Meet Prose

Traditional design systems rely on design tokens (often stored as JSON or YAML) to distribute values like colors, typography, and spacing. While these work well for build pipelines, they are insufficient for LLMs. A raw JSON file of hex codes does not explain when or why to use a specific color. Conversely, pure markdown documentation is too imprecise for an agent to reliably extract exact pixel values or hex codes.

DESIGN.md solves this by combining machine-readable design tokens with human-readable design rationale in a single file. It uses YAML front matter for the raw tokens and standard Markdown prose for the semantic context.

---
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
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
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, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

When an agent parses this file, it gets the best of both worlds. It extracts the exact hex code #B8422E for interactive elements, and it understands from the prose that this color is "Boston Clay" and should be used exclusively as the driver for user interaction.

The Developer Angle: Tooling and Agent Integration

For developers, the value of DESIGN.md lies in its utility within automated workflows. The specification includes a CLI tool that allows you to validate your design files, check accessibility compliance, and track changes over time.

Automated Linting and Accessibility Checks

The CLI tool can validate a DESIGN.md file against the official schema and run automated WCAG contrast checks. It outputs structured JSON, making it easy for coding agents to parse the findings and self-correct.

npx @google/design.md lint DESIGN.md

This command evaluates the token relationships and returns a structured report:

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

In an agentic workflow (using tools like Claude Code, Cursor, or custom LLM pipelines), the agent can run this linting command locally. If the agent generates a component that violates the design system or fails contrast checks, the CLI output acts as a feedback loop, allowing the agent to correct its own code before presenting it to the developer.

Tracking Design System Drift

When design systems evolve, keeping downstream code in sync is incredibly difficult. The DESIGN.md CLI provides a diffing tool to compare two versions of a design system, identifying added, removed, or modified tokens and prose.

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

This outputs a clean JSON diff:

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

This diff can be integrated into your CI/CD pipeline. If a pull request modifies the design system, the pipeline can flag token changes and prompt the AI agent to update the corresponding component implementations across the codebase.

Adoption and Workflow Integration

Integrating DESIGN.md into your repository is straightforward. You do not need to rewrite your existing build pipeline or replace your Tailwind CSS configuration. Instead, you treat DESIGN.md as a documentation layer specifically optimized for AI consumption.

For teams using agentic platforms, the specification can be installed as an agent skill. For example, using the Open Agent Skill registry, you can add it directly to your agent's workspace:

npx skills add google-labs-code/design.md

This registers the design system rules with your local agent, ensuring that any subsequent code generation tasks reference the constraints defined in your repository's DESIGN.md file.

Trade-offs and Caveats

While DESIGN.md is a highly practical solution to a frustrating problem, developers should keep a few caveats in mind before adopting it:

• The Synchronization Burden: Introducing DESIGN.md adds another source of truth to your repository. You must ensure that the tokens defined in the markdown file match your actual runtime variables (such as Tailwind configs, CSS custom properties, or theme files). If they drift, the agent will generate code based on outdated or incorrect values.
• Alpha Specification: The specification is currently in alpha. While the core schema for colors, typography, and spacing is stable, more complex component-level tokens are still evolving.
• CLI Quirks on Windows: If you are running the CLI on Windows or within PowerShell, you may need to quote the package name (npm install "@google/design.md") to prevent the shell from misinterpreting the @ symbol. Additionally, running the npx command directly on Windows can occasionally fail to produce output or attempt to open the markdown file in a text editor.

The Verdict

DESIGN.md is a pragmatic, low-overhead addition to any frontend repository that uses AI-assisted development. It does not require you to change how you compile your CSS or bundle your JavaScript. By simply maintaining a single, structured markdown file at the root of your project, you can prevent your coding agents from hallucinating styles and ensure your generated user interfaces remain accessible and on-brand.