DESIGN.md: Google's New Standard for Telling AI Coding Agents How Your App Should Look
Author: Hamza Chahid (TekMag)
The Core Problem
AI coding agents generate functional code but fail at visual consistency — colors, fonts, and spacing vary wildly between sessions. If you've worked with AI-assisted development tools like Claude, Cursor, or Gemini Code Assist, you've experienced this frustration firsthand.
What Is DESIGN.md?
Google Labs has introduced DESIGN.md , an open-source format specification that lives in your project root and tells AI agents how your app should look. It's the visual counterpart to AGENTS.md.
The spec lives at github.com/google-labs-code/design.md and combines two layers:
- YAML Front Matter (Machine Tokens): Precise, parseable design values for colors, typography, spacing, border-radius, elevation, and component structure.
- Markdown Body (Human Rationale): Prose explaining why those values exist and how to apply them in context — eight canonical sections covering overview, colors, typography, spacing, iconography, imagery, data visualization, and components.
Concrete Example
[code]
---
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
---
# Visual Identity
## Overview
A clean, confident brand built on dark charcoal and warm terracotta.
[/code]
Tokens use a reference system where {colors.tertiary} resolves to #B8422E. Unknown token names are accepted if valid, but duplicate sections trigger an error and the file is rejected.
The CLI Toolkit (@google/design.md v0.3.0 alpha)
The npm package provides four commands: lint validates structure and WCAG AA 4.5:1 contrast ratios; diff enables token-level regression detection; export converts tokens to Tailwind config, CSS custom properties, or W3C DTCG format; and spec outputs the formal spec for agent prompting.
Ecosystem Traction
Launched as part of Google Stitch (March 2026), DESIGN.md became the #1 trending repository on GitHub with 18,000+ stars. The community-driven awesome-design-md has 93,000 stars and 73 brand design systems from Apple to Vercel. Anthropic's Claude Design team has released 30+ DESIGN.md files grouped by aesthetic families.
Figma's stock dropped 11% in two days after the Stitch announcement — the market clearly sees where design is heading.
The Standard Project File Trio
DESIGN.md joins README.md (what the project is for humans) and AGENTS.md (how to build for agents) as the third essential project root file — telling design agents how it should look. Without it, every agent session starts from scratch guessing colors and inventing spacing.
How to Get Started in 5 Steps
- Install the CLI:
npm install @google/design.md - Browse awesome-design-md and copy a DESIGN.md from a brand whose style aligns with yours
- Drop it in your project root as
DESIGN.md - Tell your AI agent: "Build me a page that looks like this"
- Validate:
npx @google/design.md lint DESIGN.md
If you're building with AI coding agents, adding a DESIGN.md to your project is the single highest-leverage thing you can do for UI quality. Your agents will thank you — and so will your users.
Originally published on TekMag
