Why 23K‑Star DESIGN.md Lets AI Agents Create Consistent UI Styles in One Step

Problem

Developers using AI coding assistants (Cursor, Claude Code, GitHub Copilot) can generate functional front‑end code, but the resulting UI is homogeneous—default blue cards, uniform rounded corners, overused gradients, and cheap emoji decorations. Changing the model, tweaking prompts, or providing screenshots only treats the symptom.

What is DESIGN.md

DESIGN.md is an open‑source pure‑text design specification for AI agents, published by Google Labs. It has a two‑layer structure:

YAML front‑matter : machine‑readable tokens that define exact values for colors, fonts, corner radii, spacing, etc.

Markdown body : human‑readable design logic, usage rules, and positive/negative examples that guide the agent’s decision‑making.

Required sections (9 modules)

Overview – brand tone and visual atmosphere

Colors – palette with semantic roles

Typography – complete typographic rules

Layout – spacing system

Elevation & Depth – shadow and depth guidelines

Shapes – corner radius and geometric norms

Components – button, card, input styles and states

Do's and Don'ts – design red‑lines to prevent AI pitfalls

AI Assistant Prompt Guide – execution rules after the agent reads the file

Key advantages

One‑time authoring, permanent reuse : placed in the project root, all supported agents automatically read the file, ensuring every new page follows the same visual language.

Dual human‑and‑machine readability : precise numeric tokens in YAML combined with narrative constraints in Markdown make the specification up to ten times more stable than screenshots or oral prompts.

Complete toolchain : an official CLI can lint, diff, and export the spec to Tailwind, W3C DTCG tokens, etc.

Official tooling

The NPM package @google/design.md (alpha) provides three main commands: designmd lint DESIGN.md – validates color contrast, token references, and WCAG AA compliance. designmd diff DESIGN.md – shows changes between versions, suitable for CI gates.

designmd export --format css-tailwind DESIGN.md > theme.css

– generates a Tailwind v3/v4 configuration or DTCG token files.

Adoption paths

Ready‑made library –

https://github.com/VoltAgent/awesome-design-md

bundles 70+ industry design libraries for zero‑code onboarding.

Design Extractor plugin – a Chrome extension that captures a target site’s visual style via a mixed CSS + multimodal screenshot pipeline, then outputs a ready DESIGN.md file.

Custom DESIGN.md – start from the minimal template (YAML tokens for name, colors, typography, rounded) and extend as needed.

Extraction method comparison

CSS code parsing – pixel‑accurate values; cannot capture overall visual mood; best for exact layout replication.

Multimodal screenshot analysis – captures style, texture, lighting; numeric precision lower; best when visual feel matters more than exact dimensions.

Mixed (default) – combines precise numbers with visual mood; requires multimodal model API; recommended for ~90 % of daily development scenarios.

Integration with popular AI development tools

Cursor : place DESIGN.md in the project root and add a .cursorrules file that tells Cursor to read the spec before generating UI code.

Claude Code : add a .claude/ directory or a global CLAUDE.md containing the same rules; Claude’s Stitch MCP can update the spec in real time.

GitHub Copilot / Windsurf : import DESIGN.md into the project context so every completion respects the defined tokens.

CI pipeline integration (enterprise scenario)

Run design:lint on every commit to enforce design‑spec integrity.

Use design:diff to compare the current DESIGN.md against a baseline and detect unintended color or layout changes.

Fail the merge if contrast, token breakage, or other violations are found, guaranteeing UI consistency across the codebase.

Common pitfalls

DESIGN.md does not replace Figma; it is a lightweight constraint for AI agents, and final designs may still need fine‑tuning in Figma.

Only the color, typography, and rounded‑corner sections are required for a noticeable consistency boost; the full nine‑module set is optional.

Alpha components support only basic background, text color, and corner radius; hover/focus states require naming conventions like button-primary-hover and are being iterated.

On Windows, use the alias designmd instead of npx @google/design.md to avoid file‑association conflicts.

Core logic

Tokens supply reference values, but the prose in the Markdown body carries higher weight for constraining AI behavior; the agent follows the narrative rules first, then falls back to numeric tokens.

Example DESIGN.md (English)

---
name: Heritage
version: alpha
colors:
  primary: "#1A1C1E" # Primary heading text color
  secondary: "#6C7278" # Secondary text and border color
  tertiary: "#B8422E" # Accent color for interactions
  neutral: "#F7F5F2" # Page background, soft alternative to pure white
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
    fontWeight: 500
  body-md:
    fontFamily: Inter
    fontSize: 1rem
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
  lg: 12px
spacing:
  base: 8px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "#ffffff"
    rounded: "{rounded.sm}"
    padding: "12px 20px"
---
## Overview
Minimalist architecture with paper‑print texture, matte premium look, targeting high‑end magazine or gallery sites, avoiding gradients, glow, or glass‑like effects.
## Colors
Palette relies on high‑contrast neutrals plus a single accent; all interactive buttons use the tertiary color only.
- Primary: deep charcoal for headings and core text
- Secondary: soft gray for annotations, tags, dividers
- Tertiary: terracotta red for primary actions and highlighted links
- Neutral: warm ivory background to reduce harsh white
## Do's and Don'ts
✅ Cards use medium rounded corners with low‑opacity shadows
❌ No colorful gradients, neon glow, or halo effects
❌ No multi‑color buttons; all actions use the tertiary color

Step‑by‑step custom DESIGN.md creation (5 minutes)

Create a DESIGN.md file and add YAML tokens for name, colors, typography, and rounded corners.

Write an Overview that references concrete visual inspirations (e.g., Linear admin UI, academic paper layout) and avoids vague adjectives.

Add core component rules (button, card) using token references such as {colors.primary}.

Define Do's and Don'ts to forbid gradients, glow, large radii, and multi‑color cards.

Validate with the CLI: npx @google/design.md lint DESIGN.md (or designmd lint DESIGN.md on Windows).

Windows bug workaround

PowerShell treats npx @google/design.md as a Markdown file. Use the alias:

npx -p @google/design.md designmd lint DESIGN.md

Package.json script example

{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md",
    "design:export-tailwind": "designmd export --format css-tailwind DESIGN.md > theme.css"
  }
}

Official repositories

Design spec repository:

https://github.com/google-labs-code/design.md

Awesome design libraries:

https://github.com/VoltAgent/awesome-design-md

Design Extractor skill:

https://github.com/liaocaoxuezhe/get-web-design