design.md

DESIGN.md is a file format specification created by Google Labs for describing the visual identity of an app or website in a way that AI coding assistants can read and apply consistently. The core idea is that a single file placed in your project can tell an AI agent what colors, fonts, spacing values, and component styles to use whenever it generates or edits interface code. Without something like this, each time you ask an AI tool to build a new screen or component, you would need to repeat your design rules in the prompt.

The file format combines two sections. The first is a YAML block at the top of the file that lists the exact design values: specific color hex codes, font families, font sizes, corner radius values, and spacing measurements. This machine-readable block gives the AI precise numbers to work with. The second section is written prose in standard markdown that explains the reasoning behind those values, describing the intended aesthetic and how different design elements should relate to each other. Together, the two sections give an agent both the what and the why.

The project ships a command-line tool that can validate a DESIGN.md file against the specification, check that color combinations meet accessibility contrast requirements, and compare two versions of a design file to identify what changed between them. There is also an export command that converts the token values into formats used by other tools, such as Tailwind CSS configuration files.

The format supports token references, meaning a component's background color can point to a named color token rather than repeating a raw hex code. This keeps the design system internally consistent and makes it easier to update a value in one place.

The project is in an early stage, described as alpha in the specification. The README is detailed and covers the full token schema, section structure, CLI reference, and installation steps.