What is DESIGN.md? Google's design system file: how to write it, lint it and export it to Tailwind

You put a DESIGN.md file in your project, and your AI coding agent reads the brand's visual identity from it: machine-readable color, font, corner and spacing values at the top, and plain prose below explaining why those values were chosen. It is an open format from Google Labs; the repository is Apache-2.0-licensed and free, and the command-line tool in the same repository checks the file with npx @google/design.md lint DESIGN.md (Node.js 18 or later). The format is still in "alpha" and may change. The official documentation does not list which agents read this file.

What it does: Describes a brand's visual identity to agents in a single file
Type: File format + command-line tool
Requirements: Node.js 18 or later (CLI only)
Latest version: 0.4.0 (July 27, 2026)
Status: Format is "alpha" and may change
Price: Free, Apache-2.0

What does DESIGN.md do?

When you tell an AI agent "build a page for this brand", it guesses the colors and fonts again every time. DESIGN.md keeps this information in one file: tokens at the top (named design values such as color, font, corner radius and spacing), and below them markdown sections explaining why those values were chosen and how to use them. The official documentation says the tokens are the exact values and the prose is the context.

Describe a design system in one fileWhat you get: DESIGN.md fileNeeds a separate setup Check the file against the rulesWhat you get: JSON findings reportNeeds a separate setup Export tokens to TailwindWhat you get: JSON or CSS to standard outputNeeds a separate setup

Who it helps: agencies and developers who work with several agents or tools for the same client and want the same identity on every page. The file does not produce an interface on its own; it needs an agent that reads it.

A tool close to the same topic but different: Frontend Design is a plugin that gives Claude Code design instructions. DESIGN.md is a file format that describes a brand's values. One does not replace the other.

How to set up the DESIGN.md file and the lint tool

Creating the file needs no installation: you put a markdown file named DESIGN.md in the project. Running the lint and export tool requires Node.js 18 or later.

Lint the file› npx @google/design.md lint DESIGN.md

If you don't specify a version, npx pulls the latest one; for a specific version, add @0.4.0 to the end of the package name.

Add to the project› npm install @google/design.md

On Windows, if your shell misreads the @ sign, put the package name in quotes: npm install "@google/design.md".

With the dotless alias› npx -p @google/design.md designmd lint DESIGN.md

According to the README, the command may produce no output in PowerShell because the name design.md gets mixed up with the Markdown file association; the designmd alias runs the same program.

If you get npm error ENOVERSIONS, the README says npm is querying a corporate mirror rather than the public registry; the output of npm config get registry should be https://registry.npmjs.org/.

How to write and use DESIGN.md

The file has two layers: YAML tokens between --- lines, and markdown sections with ## headings below. The sections are optional, but if present they must be in this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. For colors you write any CSS color, for sizes px, em or rem, and to reference another token {colors.primary}. A shortened skeleton from the README example:

DESIGN.md skeleton

› ---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
spacing:
  md: 16px
---

## Overview

A clean look with the gravity of a newspaper.

## Colors

- **Primary (#1A1C1E):** Headlines and body text.
- **Tertiary (#B8422E):** Interaction color only.

Having the agent read the file"Read the DESIGN.md file in the project and build the new pricing page to match this design system. Don't use any color or font that isn't in the file."This is an example prompt; the official documentation does not say which agents read the file on their own, so point the agent to the file explicitly.

Task	Command
Lint the file	`npx @google/design.md lint DESIGN.md`
Compare two versions	`npx @google/design.md diff DESIGN.md DESIGN-v2.md`
Convert to a Tailwind v3 config	`npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json`
Convert to a Tailwind v4 CSS theme	`npx @google/design.md export --format css-tailwind DESIGN.md > theme.css`
Convert to a W3C token file	`npx @google/design.md export --format dtcg DESIGN.md > tokens.json`
Print the format rules to give to an agent	`npx @google/design.md spec`

The tool outputs JSON. If lint finds errors, the exit code is 1; the check looks at: broken token references, a missing primary color, WCAG AA contrast (4.5:1) of component text/background color pairs, colors not used in any component, and section order.

The file is read by the agent like instructions. Don't use ready-made DESIGN.md files extracted from someone else's brand as they are; that can raise brand and copyright issues. Write your own for your own brand.

Which agents does DESIGN.md work with?

Command-line tool (lint, diff, export, spec)Yes	Node.js 18 or later; runs without installing via npx.
Coding agents that read the fileUnclear	The official documentation names no agents; it describes it as an open format usable across "different AI agents and tools".
Tailwind v3 / v4 and W3C DTCGYes	The `export` command outputs these three formats.

"Not in the docs" does not mean it doesn't work. Have the agent you use read the file explicitly.

What does the lint tool read and write?

Reads

The DESIGN.md file you pass to the command (or standard input). diff reads two files.

Writes

Prints JSON or CSS to standard output; to write to a file, you add the shell redirect (>) yourself.

Install script

In the npm registry, version 0.4.0 shows no script that runs before or after install (only build scripts).

Published security advisory

As of October 15, 2026, no advisory is listed in the GitHub advisory list (repository and global) or in OSV for npm. This does not mean it is secure: the README says the project is not covered by Google's vulnerability reward program, and there is no SECURITY.md in the repository.

Is DESIGN.md free?

Yes. The format and the command-line tool are published on Google Labs' open repository under the Apache-2.0 license; the documentation mentions no paid plan, account or key. "The software is free" does not mean the agent or model that uses your file is free; those are paid separately.

Allowed

Use, modify and distribute under the Apache-2.0 terms (including commercial use)

Not allowed

Remove the license text and notices from copies

Source: repository license and README. This is not legal advice.

Common problems and fixes

What happens	What to do
In PowerShell the command produces no output, or DESIGN.md opens in a text editor	Use the command `npx -p @google/design.md designmd lint DESIGN.md`.
`npm error ENOVERSIONS`	Check the npm registry address (`npm config get registry`); a corporate mirror may not be in sync.
Reported by users The `spec` command errors in version 0.3.0 (#153)	Open report on GitHub; whether it is fixed in 0.4.0 is unclear; check the release notes.
Reported by users The `dtcg` export leaves out font properties (#172)	Open report on GitHub; check the output by eye before passing it to another tool.

Frequently asked questions

What is DESIGN.md?

An open file format that tells coding agents a brand's color, font, corner and spacing values and the reasons behind them. YAML tokens sit at the top, markdown explanations below.

Is DESIGN.md free?

Yes. Google Labs' open repository publishes the format and the command-line tool under the Apache-2.0 license; the documentation mentions no paid plan. The agent that reads the file is paid separately.

How do I lint a DESIGN.md file?

With Node.js 18 or later, run npx @google/design.md lint DESIGN.md. The tool reports findings such as broken token references, WCAG contrast and section order as JSON.

Can DESIGN.md be used with Tailwind?

The README says the export command outputs a Tailwind v3 JSON config, a Tailwind v4 CSS theme and a W3C DTCG tokens.json.

Which AI agents read DESIGN.md?

The official documentation names no agents. The format is designed to be used across different agents and tools; the safest approach is to have the agent you use read the file explicitly.

Is the DESIGN.md format stable?

No. The README says the format is in "alpha" and that the schema and the tool may change. Pin the version (for example @0.4.0) before tying it to a critical workflow.

Related guides

Stitch

Frontend Design Genjutsu

Hallmark

Impeccable

shadcn/ui skill

Sources

Not clear in the official sources: Which coding agents read DESIGN.md on their own · the details of exchanging files with Google Stitch · whether the reported bugs are fixed in 0.4.0 · documentation in Turkish. Each is covered in the relevant section along with what you can do.