Illustration of what design.md does: A file format that tells coding agents your colors, fonts, and spacing, plus why

google-labs-code /

design.md

A file format that tells coding agents your colors, fonts, and spacing, plus why

  • 28.5k stars
  • 261 stars since 3 Oct
  • TypeScript
  • Updated 6 days ago
  • Beginner friendly
  • Design & UI
Open on GitHub (opens in a new tab) Website (opens in a new tab)

Coding agents often invent colors, fonts, and spacing when they build a UI. DESIGN.md gives them one file that describes the visual identity, so the output stays consistent from one session to the next.

The file has two layers. YAML front matter holds exact token values: colors, typography, rounded corners, spacing, and component styles. The markdown body explains the reasoning, such as why one accent color drives all interaction. Tokens can point to each other with references like {colors.primary}.

The project also ships a CLI, @google/design.md. It checks a file for broken references and low WCAG contrast, compares two versions to catch regressions, and exports tokens to Tailwind v3, Tailwind v4 CSS, or the W3C Design Tokens format. The format is at version alpha, so expect changes.

What it does

  • Tokens plus prose

    YAML front matter carries exact values. Markdown sections such as Overview, Colors, Typography, and Components explain how to use them. Sections must appear in a set order.

  • Linter with eleven rules

    Flags broken token references, a missing primary color, missing typography, out-of-order sections, and component color pairs below the WCAG AA 4.5:1 contrast ratio. Results come out as JSON.

  • Diff between versions

    Compares two DESIGN.md files and reports added, removed, and modified tokens. It exits with code 1 if the newer file has more errors or warnings.

  • Export to other formats

    Converts tokens to a Tailwind v3 theme object, a Tailwind v4 @theme CSS block, or W3C DTCG tokens.json.

  • Spec command and library API

    The spec command prints the format spec so you can put it in an agent prompt. A TypeScript lint() function is also available as a library.

What you could build

  • Write a DESIGN.md for your brand so coding agents build pages with the right colors and fonts.
  • Lint a design file in CI to catch broken token references and low-contrast button colors.
  • Compare two versions of a design system to see which tokens changed.
  • Export your tokens to a Tailwind theme or a W3C tokens.json for use in existing tooling.
  • Inject the spec into an agent prompt so it can write or update a DESIGN.md itself.

Get started

Create a DESIGN.md with YAML tokens at the top and markdown sections below, then run the lint command on it. On Windows PowerShell, use the designmd alias: npx -p @google/design.md designmd lint DESIGN.md.

npx @google/design.md lint DESIGN.md
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css

Commands are copied from the project's README. Read it on GitHub for the full setup.

More in Design & UI

See all
awesome-design-md A curated set of DESIGN.md files that capture the look of well-known websites 123k3.8k open-design Local-first workspace where coding agents build prototypes, decks, images and motion 103.4k diagram-design A skill that makes on-brand HTML and SVG diagrams from a plain-language request 60.1k17k pascalorg/editor Local-first 3D building editor you can use in a browser, a CLI, or through AI agents 25.1k542 openui A framework and compact language for letting LLMs stream live UI components 13.1k awesome-design-skills A registry of 67 ready-made design system files for AI coding agents 3.3k299

    ↑↓ to move, Enter to open, Esc to close