How to Set Up DESIGN.md So AI Agents Generate Brand-Consistent UIs

AI coding agents generate UI components on demand — but without explicit brand rules, they guess. Google Labs’ DESIGN.md is an open-source specification that gives agents a deterministic source of truth for colors, typography, and accessibility constraints, committed to the project root like a README.

Purpose: Drop a DESIGN.md file into any project so that Claude Code, Cursor, GitHub Copilot, and other compatible agents generate interfaces consistent with your brand rather than improvising from context.

Pre-requisites:

• A Google account (for Google Stitch to generate an initial file) — or write DESIGN.md manually in any editor
• An existing brand design system with defined color tokens and typography
• One of the compatible agents: Claude Code, Cursor, or GitHub Copilot

Steps

1. Generate your initial DESIGN.md in Google Stitch

Open Stitch and import your brand palette or describe your visual identity. Stitch exports a structured DESIGN.md file. Alternatively, create the file manually — it’s plain markdown and doesn’t require any tooling.

2. Define color tokens with WHY context

Each token entry pairs the value with a plain-text explanation of its purpose. Format:

## Colors

- **Primary**: `#1A73E8`
  - Use for: primary action buttons, active navigation links
  - Avoid: body text (fails WCAG AA contrast on white backgrounds)

- **Surface**: `#F8F9FA`
  - Use for: card backgrounds, form containers
  - Note: distinguishable from pure white in low-brightness environments

The WHY explanation is what separates DESIGN.md from a simple color palette dump — agents use these notes to make context-appropriate choices rather than applying tokens mechanically.

3. Add typography tokens

## Typography

- **Heading 1**: `Roboto 32px / 700 weight / 1.2 line-height`
  - Use for: page-level headings, hero sections
- **Body**: `Roboto 16px / 400 weight / 1.5 line-height`
  - Use for: all paragraph content; minimum size for body copy

4. Add spacing and layout rules

## Spacing

- **Base unit**: `8px`
- **Component padding**: multiples of base unit (8, 16, 24, 32)
- **Grid**: 12-column, 24px gutter, 16px column padding

5. Add accessibility constraints

## Accessibility

- Minimum contrast ratio: 4.5:1 for body text (WCAG AA)
- Minimum contrast ratio: 3:1 for large text and UI components
- Interactive elements: minimum touch target 44×44px

When an agent generates a component and a DESIGN.md file is present, it can validate its color choices against these constraints before surfacing the output.

6. Place DESIGN.md in the project root and commit

mv design.md DESIGN.md
git add DESIGN.md
git commit -m "add DESIGN.md brand spec for AI agents"

Any compatible agent will discover the file automatically in the project root.

7. Instruct your agent to reference DESIGN.md

Explicit invocation ensures the agent uses the spec rather than its training defaults:

“Generate a card component for this product listing. Follow the brand rules in DESIGN.md.”

For Claude Code, the spec is read automatically when present — but an explicit instruction forces brand-validation to surface in the agent’s reasoning.

8. Explore the community spec collection

The awesome-design-md repository collects DESIGN.md files modeled on popular brand design systems. Useful as reference implementations or starting templates.

The Trap

Listing values without context. A DESIGN.md file that contains only token values — Primary: #1A73E8 — gives the agent nothing to reason with. The file’s leverage comes from the WHY: which tokens apply in which context, what the constraints are, and why a color exists. Without that, the agent reverts to inference, which is exactly the problem DESIGN.md is meant to solve.

Cited References

• Google Labs DESIGN.md announcement
• google-labs-code/design.md on GitHub — Apache 2.0
• VoltAgent/awesome-design-md — community DESIGN.md collection

Photo by Akshar Dave on Pexels

Source: Google Labs Blog

Content created with AI assistance and reviewed for accuracy.