The design.md repository is a format specification created by Google Labs for describing visual design systems in a way that coding agents can understand and act upon. The project addresses a specific need: enabling AI agents to maintain a persistent, structured understanding of design systems by combining machine-readable design tokens with human-readable design rationale in a single file format.
The core innovation of design.md is its two-layer structure. Files consist of YAML front matter containing machine-readable design tokens delimited by dashes, followed by markdown prose that explains the design rationale and application guidance. This hybrid approach allows agents to extract exact token values while understanding the context and reasoning behind design decisions. The specification supports multiple token types including colors in various CSS formats, dimensions with units, typography objects with properties like font family and line height, and component definitions that map names to groups of sub-token properties.
The repository is written in TypeScript and provides both a command-line interface and a programmatic API for working with design.md files. The CLI includes several key commands: lint validates files for structural correctness and runs nine distinct linting rules that check for issues like broken token references, missing primary colors, WCAG contrast ratio violations, and orphaned tokens. The diff command compares two design.md versions to detect token-level and prose regressions. The export command converts design tokens to other formats including Tailwind v3 and v4 configurations and the W3C Design Tokens Format Module, enabling interoperability with existing design tooling.
The repository is classified across multiple domains including design documentation, markdown, design system, collaborative editing, project planning, specification writing, design workflow, documentation tools, and team collaboration.
The specification is currently at alpha status, indicating that the format, token schema, and CLI remain under active development with expected changes as the project matures. The linting system is comprehensive, running nine rules at different severity levels to catch structural issues, missing design elements, accessibility problems, and organizational concerns. The project includes detailed documentation covering file structure, token schema definitions, section ordering requirements, and consumer behavior guidelines for handling unknown content. The repository also provides platform-specific guidance, particularly for Windows users who may encounter command resolution issues with the .md file extension, offering the designmd alias as a workaround.
