Blurb: DESIGN.md is an open spec for encoding your visual identity in one repo file: YAML tokens plus Markdown rationale, a CLI for linting (including WCAG contrast) and exporting to Tailwind or DTCG, and a plain-text contract so coding agents stop improvising your design system from scratch.

Contents

• What problem it tries to fix
• How the file is structured
• Tooling: lint, diff, export, spec
• Why “one file” is the right unit
• Community: Awesome DESIGN.md
• Status and expectations

When you ask a coding agent to build or tweak a UI, it rarely knows your design system. It might guess a primary color, pick a random radius, or reuse whatever looked fine in the last chat. You end up re-explaining tokens, contrast, and component intent every time, or you accept UI drift.

DESIGN.md is an open format specification from Google’s google-labs-code org for describing a visual identity so agents can read it consistently: one file, plain text, no lock-in to a single editor or model.

What problem it tries to fix

Agents work best when “what to build” and “how it should feel” live in the repo, not only in Figma exports or tribal knowledge. Without that:

• Colors and type are treated as opaque hex and font names, not as roles (primary headline vs. caption vs. CTA).
• Accessibility checks become manual spot review.
• Moving the same rules to another repo or tool means re-describing everything.

DESIGN.md addresses that by combining normative token values with prose that explains intent, so both humans and agents get numbers and meaning.

How the file is structured

A valid DESIGN.md has two layers:

1. YAML front matter at the top (between --- fences): machine-readable tokens—colors, typography, rounded, spacing, optional components with properties like backgroundColor, textColor, typography, rounded, padding, and so on. Values can reference other tokens with {colors.primary} style paths.
2. Markdown body with ## sections: human-readable rationale (overview, palette story, when to use which token). The spec defines a canonical section order (Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts). Sections can be omitted, but those that appear should follow that order so tools and agents behave predictably.

The README’s example makes the idea concrete: tokens say “tertiary is #B8422E”; the prose says it is the sole interaction accent (“Boston Clay”). An agent that consumes both is far less likely to invent a second contradictory accent.

Tooling: lint, diff, export, spec

The project ships an npm CLI as @google/design.md.

lint validates structure, catches broken token references, flags contrast issues against WCAG AA for paired backgroundColor / textColor on components, and emits structured JSON findings agents or CI can act on, not just a pass/fail in the terminal.

diff compares two versions of a design system and reports token-level additions, removals, and changes, plus whether the newer file regressed on lint severity.

export targets real pipelines: Tailwind v3 theme.extend JSON, Tailwind v4 @theme CSS, and DTCG (W3C Design Tokens Format Module) JSON, so the same source file can feed Tailwind-heavy apps or token tooling without maintaining duplicate layouts.

spec dumps the format specification (and optional lint rules), which is useful for stuffing authoritative context into agent prompts instead of paraphrasing from memory.

There is also a programmatic API (import { lint } from '@google/design.md/linter') if you want reports inside your own scripts or services.

Why “one file” is the right unit

Portability here is literal: check in DESIGN.md, copy it to another product, or attach it to a task. Any tool that reads Markdown and YAML can participate. You are not betting on a proprietary canvas or a single vendor’s “agent memory.” The format is explicitly aimed at coding agents—persistent, structured identity they can re-read as the conversation moves on.

Community: Awesome DESIGN.md

VoltAgent/awesome-design-md is a curated collection of DESIGN.md files inspired by developer-focused websites. Each entry is a drop-in document (and often a small visual preview) you can copy into a repo and adapt, instead of inventing a whole system from zero while you are still learning the format.

Status and expectations

The format is alpha. The spec, schema, and CLI are under active development; breaking or additive changes are possible as it matures. That is worth planning for if you adopt it in production pipelines (pin versions, snapshot lint output, or treat exports as reviewed artifacts).

If you want to try it, the canonical repo is:

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

Clone it, add a DESIGN.md beside your app, run npx @google/design.md lint DESIGN.md, and iterate until the findings look like the system you actually intend. Then keep that file as the contract between design and whatever agent is editing the UI.