Repolode
Submit
google-labs-code

google-labs-code/design.md

A format spec and CLI for describing a visual identity (design tokens plus prose) so coding agents can build consistent UIs.

View on GitHubWebsite
Stars
28,435
Forks
2,250
Open issues
42
Last commit
5 days ago

What is it?

DESIGN.md is a file format for describing a design system to coding agents. Each file combines machine-readable design tokens, written as YAML front matter, with markdown prose that explains why those values exist and how to apply them. The tokens give exact colors, typography, spacing, rounded corners and component properties, while the prose covers intent such as tone, palette roles and usage rules.

The project ships an npm package, @google/design.md, with a command-line tool. Its lint command validates a file against the spec, flags broken token references, and checks WCAG contrast ratios for component color pairs, returning structured JSON. The diff command compares two versions of a design system and reports token-level changes and lint regressions. The export command converts tokens to Tailwind v3 config JSON, Tailwind v4 CSS @theme blocks, or W3C DTCG token files. A programmatic linter API is also available for TypeScript projects.

The format is at version alpha, and the spec and CLI are still under active development.

Key features

  • 01Combines YAML design tokens with markdown rationale in a single file.
  • 02Lint command validates structure, broken token references and WCAG contrast ratios.
  • 03Diff command reports token-level changes between two design system versions.
  • 04Exports tokens to Tailwind v3 and v4 configs and to W3C DTCG JSON.
  • 05Provides a TypeScript linter API and a spec command for prompt context.

Use cases

  • Giving a coding agent a persistent description of a brand's colors, type and component styles.
  • Checking a design system in CI for broken token references and low-contrast component colors.
  • Syncing design tokens into a Tailwind project through the export command.

Quick start

  1. 1

    Install the CLI package

    npm install @google/design.md
  2. 2

    Validate a DESIGN.md file

    npx @google/design.md lint DESIGN.md

Things to know

  • The format is at alpha version and may change as it matures.
  • The project is not eligible for Google's open source vulnerability rewards program.

Topics

#design-tokens#design-system#coding-agents#llm#tailwind#css#linting#typescript

FAQ

What is design.md?
A format spec and CLI for describing a visual identity (design tokens plus prose) so coding agents can build consistent UIs. DESIGN.md is a file format for describing a design system to coding agents. Each file combines machine-readable design tokens, written as YAML front matter, with markdown prose that explains why those values exist and how to apply them. The tokens give exact colors, typography, spacing, rounded corners and component properties, while the prose covers intent such as tone, palette roles and usage rules.
Is design.md free to use? What license does it have?
design.md is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is design.md still maintained?
Actively maintained. The last commit to design.md was on Oct 16, 2026.
What can I use design.md for?
Giving a coding agent a persistent description of a brand's colors, type and component styles. Checking a design system in CI for broken token references and low-contrast component colors. Syncing design tokens into a Tailwind project through the export command.
How do I install design.md?
Install the CLI package: npm install @google/design.md Validate a DESIGN.md file: npx @google/design.md lint DESIGN.md
Where can I get design.md?
The source code and installation instructions are on GitHub: https://github.com/google-labs-code/design.md

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects