DESIGN.md

DESIGN.md is an open-source format specification that gives AI coding agents a persistent, structured understanding of a design system. It combines machine-readable YAML front matter (design tokens) with human-readable Markdown prose (design rationale), enabling agents to produce consistent UIs with exact color, typography, spacing, and component values. The project ships a CLI (@google/design.md) for linting, diffing, exporting, and inspecting DESIGN.md files, as well as a programmatic TypeScript API. It is published under the Apache License 2.0 by Google Labs.

• YAML + Markdown format — Define design tokens (colors, typography, spacing, rounded, components) in YAML front matter and explain their intent in Markdown sections.
• lint command — Validate a DESIGN.md file for structural correctness, broken token references, WCAG contrast ratios, and orphaned tokens; outputs structured JSON findings.
• diff command — Compare two DESIGN.md versions to detect token-level changes and prose regressions, with a regression flag for CI pipelines.
• export command — Convert DESIGN.md tokens to Tailwind theme config or W3C DTCG tokens.json format for interoperability with other toolchains.
• spec command — Output the full format specification as Markdown or JSON, useful for injecting spec context directly into agent prompts.
• Programmatic API — Import the lint function from @google/design.md/linter in TypeScript/JavaScript projects to integrate validation into custom workflows.
• Token references — Use {path.to.token} syntax to reference tokens within component definitions, keeping the design system DRY and consistent.
• Component tokens — Map named components (e.g., button-primary) to sub-token properties like backgroundColor, textColor, rounded, and padding, including hover/active variants.
• WCAG contrast checking — The linter automatically checks backgroundColor/textColor pairs in components against the WCAG AA minimum contrast ratio of 4.5:1.
• W3C Design Token interoperability — Token schema is inspired by the W3C Design Token Format Module, with direct export support for DTCG-compliant tokens.json.