If you’ve used any AI tool to generate UI — Cursor, Claude Code, v0, Bolt, Lovable, Windsurf, whatever — you’ve hit this wall: the AI generates something functional but visually generic. You describe “a dashboard with my brand colors” and it returns a default Tailwind palette with blue buttons. You fix it by hand, prompt again, and the next component comes out with a completely different visual language.
The problem isn’t the AI. The problem is that your AI has no idea what your design system looks like.
Google just open-sourced the solution. It’s called DESIGN.md.
What Is DESIGN.md
DESIGN.md is a format specification — a markdown file that describes your visual identity in a way that AI coding agents can read, understand, and apply consistently. It was born inside Google Stitch, Google Labs’ AI-native design canvas, and as of this week the spec is open source under the Apache 2.0 license.
The repo: github.com/google-labs-code/design.md
The concept is simple but powerful: combine machine-readable design tokens (YAML front matter) with human-readable design logic (markdown prose). The tokens give the agent exact values. The prose tells it why those values exist and how to apply them.
Here’s what a DESIGN.md file looks like:
---
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 — a high-end broadsheet or contemporary gallery.
## Colors
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.
An agent that reads this file produces a UI with headings in dark ink using Public Sans, a warm limestone-like background, and action buttons in Boston Clay. Every time. In every component it generates.
That’s the unlock: visual consistency without manual correction on every prompt.
Why It Matters Now
The timing is no accident. We’re at a moment where AI tools generate UI from text at impressive speed — but each tool has its own way of understanding design intent. You build something in Stitch, want to continue in Claude Code, and start over with the visual language. You prototype in v0, move to Cursor for production code, and spend an hour re-explaining your color palette.
DESIGN.md proposes to be the universal contract between your design system and any AI agent that touches your code. One file. You drop it in your project root. Every tool reads it.
The format is deliberately simple: it’s markdown. You don’t need Figma exports, proprietary JSON schemas, or special tooling. Markdown is the format LLMs read best — there’s nothing to parse or configure. And because design logic lives alongside the tokens, the AI doesn’t just know that your primary color is #1A1C1E — it knows it’s called “Deep Ink” and is used for headlines, not backgrounds.
The Practical Workflow
Here’s how you’d use it in practice:
Option 1: Start from Stitch. You design your UI in Google Stitch, and when you’re done, export the DESIGN.md. This gives you a file with all the tokens, color roles, typography, spacing, and design logic already written for the AI to understand. Then you drop it in your code project.
Option 2: Write it by hand. If you already have a design system or brand guidelines, you can write the DESIGN.md yourself. The YAML front matter covers tokens (colors, typography, spacing, border-radius), and the markdown prose describes the philosophy, the do’s and don’ts, and component patterns. The spec has clear documentation on what to include.
Option 3: Extract it from an existing site. An ecosystem of tools has formed around this format. There’s a Chrome extension (DESIGN.md Style Extractor by TypeUI) that extracts CSS variables and computed styles from any website and generates a DESIGN.md. There are CLIs like dembrandt that crawl a URL with Playwright and produce design tokens in DESIGN.md format. And there’s an entire curated repository — awesome-design-md — with pre-built DESIGN.md files modeled after Stripe, Vercel, Linear, Notion, Airbnb, and dozens of other well-known design systems.
Once you have the file, usage is identical across all tools:
project/
├── DESIGN.md ← your design system spec
├── src/
│ ├── components/
│ └── pages/
└── package.json
You tell your AI agent: “Build a settings page following the design system in DESIGN.md.” The agent reads the file, applies the tokens, follows the design logic, and generates code that actually looks like your brand.
Agent Skills: Going Deeper
Google also maintains a skills library — google-labs-code/stitch-skills — that complements DESIGN.md. Skills are small sets of instructions that teach coding agents how to perform specific workflows. The design-md skill, for example, tells your agent how to analyze a Stitch project and generate a complete DESIGN.md from it.
They’re installed like this:
npx skills add google-labs-code/stitch-skills --skill design-md --global
Other skills in the collection include stitch-loop (generates a multi-page website from a single prompt), react:components (converts Stitch screens to React component systems with design token consistency), and enhance-prompt (transforms vague UI descriptions into detailed, optimized prompts for Stitch).
These skills follow the open Agent Skills standard, which means they work with Claude Code, Cursor, Windsurf, Gemini CLI, and other compatible agents — not just Google tools.
What About Accessibility?
One detail from Google’s blog post worth highlighting: DESIGN.md doesn’t just capture visual tokens — it can encode accessibility intent. Instead of an agent guessing whether a color combination meets WCAG contrast requirements, the spec lets you declare color roles with their semantic purpose. The agent can then validate its decisions against accessibility rules before generating code.
This matters because AI-generated UI has a known accessibility problem. When the agent doesn’t know the intended role of a color, it can’t verify whether that bright orange on a white background meets AA contrast. With DESIGN.md’s semantic color roles, the information is there for the agent to make that check.
The Ecosystem That’s Already Forming
The spec is one day into its open source form and already has ~1,600 stars on GitHub (with accelerating growth rate). But the interesting signal is the ecosystem forming around it:
- awesome-design-md — a community-curated collection of DESIGN.md files for popular brands (Stripe, Binance, Airbnb, Meta, etc.)
- DESIGN.md Style Extractor — a Chrome extension that generates the file from any site you’re browsing
- dembrandt — a CLI that crawls sites with Playwright and generates DESIGN.md, DTCG tokens, and even brand guide PDFs
- design-md-generator — uses Playwright extraction + Claude Code for semantic DESIGN.md writing
- Shuffle.dev — already supports DESIGN.md export from its UI builder
- MindStudio — released a workflow for chaining Stitch → DESIGN.md → Claude Code
For something that just went open source, this adoption curve is remarkable. It suggests the format is hitting a real gap in the design-to-code pipeline that developers have been solving with ad-hoc solutions.
The Honest Assessment
What works well:
- The format itself is elegant: YAML for machines, markdown for humans, both in one file. No new tooling needed.
- Agent-agnostic by design. Works with Claude Code, Cursor, Windsurf, Gemini CLI, Codex — any tool that reads markdown.
- The combination of exact tokens + design logic is smarter than just tokens. Knowing that
#B8422Eis “Boston Clay, the only interaction driver” gives the agent more info than justaccent: #B8422E. - Apache 2.0 license. No lock-in with Google’s ecosystem.
What to watch:
- The spec is still a draft. It works, but structural changes are possible as more tools adopt it.
- Generation from existing sites (via Chrome extensions or CLIs) produces approximations, not official design system documentation. Computed CSS values don’t always capture design intent.
- Whether this becomes a true industry standard or remains a Google-originated format that others tolerate depends on adoption by Figma, Storybook, and the broader design tooling ecosystem.
- There’s still no alignment with the W3C Design Tokens Community Group. The DTCG has its own tokens format spec. Whether DESIGN.md and DTCG converge or compete remains to be seen.
How to Get Started
The fastest way to try DESIGN.md:
- Go to the repo: github.com/google-labs-code/design.md
- Check the
examples/folder for sample DESIGN.md files - Copy one as a starting point, edit it with your brand tokens
- Drop it in your project root
- In your preferred AI tool, reference it: “Follow the design system in DESIGN.md”
Or, if you want to extract from an existing site:
# Using dembrandt
npx dembrandt yoursite.com --design-md
Or browse the pre-built collection at awesome-design-md for inspiration.
Are you already using DESIGN.md or something similar to maintain consistency in your AI-generated UI? What’s your strategy for keeping visual coherence when coding with AI? Let us know in the comments. 