Google Open‑Sources design.md: A 20K‑Star Design System for AI‑Generated UI

Google Labs recently open‑sourced design.md , a design‑system specification aimed at AI agents. The repository has attracted nearly 20 000 stars on GitHub, indicating strong community interest.

What design.md is

Design.md is a markdown file written for AI agents. It combines a YAML front‑matter containing precise design tokens (hex colors, font sizes, spacing, border radius) with a markdown body that explains the design rationale (why a primary color is chosen, why a button is rounded). This dual‑layer format lets AI both execute exact values and understand the intent behind them.

Core design example

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview
Architecture minimalism meets formal newspaper gravitas. UI feels premium and matte‑like.

## Colors
- **Primary (#1A1C1E)**: deep charcoal for headings and core text.
- **Secondary (#6C7278)**: subdued slate for borders and metadata.
- **Tertiary (#B8422E)**: "Boston Clay" – the sole interactive accent.
- **Neutral (#F7F5F2)**: warm off‑white background.

When an AI reads this file it can generate a page with a Public Sans heading, a warm‑beige background, and a Boston Clay CTA button, because every token has a documented source and purpose.

CLI tool

The zero‑configuration CLI @google/design.md offers four commands:

lint : validates the file against eight built‑in rules (broken references, missing primary color, WCAG contrast, token isolation, section order, etc.).

diff : compares two versions of a DESIGN.md file and reports token‑level regressions.

export : outputs Tailwind theme configuration or W3C DTCG token files for seamless integration with design tools.

spec : emits a formal specification document that can be dropped into an AI system prompt.

Example lint output (JSON) shows a warning about contrast ratio:

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

Integration with Stitch

Stitch, Google’s internal AI‑design tool, can export a DESIGN.md file directly from a canvas. Designers adjust a style in Stitch, and the tool generates the corresponding DESIGN.md, ensuring that downstream AI agents (e.g., Claude Code) produce UI that matches the designer’s vision without drift.

Getting started

Three simple steps are enough to adopt design.md:

Create a DESIGN.md file at the project root ( touch DESIGN.md).

Copy the Heritage example above and modify the tokens as needed.

Run npx @google/design.md lint DESIGN.md to validate.

If the project already uses Tailwind, you can export the theme configuration with:

npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

Combining DESIGN.md with Claude Code’s frontend‑design skill lets AI generate code that respects the exact design tokens.

Conclusion

Design.md provides a lightweight, markdown‑based way to codify visual standards for AI agents. By separating machine‑readable tokens from human‑readable rationale, it solves the core problem of reliably transmitting “good design” to AI, turning design knowledge into a new hard skill for developers and designers alike.