DESIGN.md: Giving Coding Agents a Persistent, Structured View of Your Visual Identity

What DESIGN.md Actually Solves

Coding agents generate UI from natural language prompts, but they have no persistent memory of your design system. Every new session starts from scratch, and the agent guesses at colors, spacing, and type. DESIGN.md is a file format that gives the agent a structured reference. The README describes it as giving agents a persistent, structured understanding of a design system. The file combines YAML front matter for machine-readable tokens and Markdown prose for the why behind those values. The target user is a team that wants consistent agent output across many prompts and sessions, without retraining or fine-tuning. The format is not a design tool. It is a contract between humans and agents, stored in a single file that can sit in a repository next to the code.

The Two-Layer File Structure

The format is deliberately split in two. The YAML front matter, delimited by `---` fences, holds the normative values: colors, typography, rounded corners, spacing, and component tokens. The Markdown body, organized into `##` sections, holds the rationale. The README says the tokens are the normative values, and the prose provides context for how to apply them. That split matters because an agent can read the exact hex value for primary color, but it also gets a sentence like "The UI evokes a premium matte finish." The prose is not decorative. It is the part that tells the agent why a color exists, which changes how the agent applies it in an unfamiliar layout. The section order is fixed. Sections can be omitted, but those present must appear in that order. That constraint keeps the file predictable for parsers.

Token Schema and Component Properties

The token schema covers colors as any CSS color value, including hex, `rgb()`, `oklch()`, and named colors. Dimensions require a number plus a unit like `px` or `em`. Typography is an object with `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, and `fontVariation`. The component block maps a component name to sub-token properties. The README lists valid properties: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, and `width`. Variants like hover or active are expressed as separate component entries with related key names, such as `button-primary-hover`. Token references use the `{path.to.token}` syntax, so a component can point to `{colors.tertiary}`. This is a compact way to express relationships between tokens, and the lint tool catches broken references. But the fixed property list is narrow. The listed component properties do not include borders, shadows or gradients.

The Lint and Diff CLI Tools

The repository ships a command-line tool that validates a DESIGN.md file and compares two versions. The lint command is `npx @google/design.md lint DESIGN.md`. It returns structured JSON with findings that include severity, path, and a message. The example output shows a warning for a button's text color on background color, with a computed contrast ratio of 15.42:1 and a note that it passes WCAG AA. That is a concrete, useful check for accessibility. The diff command is `npx @google/design.md diff DESIGN.md DESIGN-v2.md`. It reports added, removed, and modified tokens per category, plus a `regression` boolean that is `false` in the example. The regression flag is a simple way to catch accidental changes in a design system review. Both commands accept a file path or `-` for stdin, and output defaults to JSON, which makes it easy to pipe into other tools.

Windows Quirks and npm Registry Issues

The CLI has a known problem on Windows. The package's bin name is `design.md`, and the `.md` suffix collides with the Windows Markdown file association during command resolution. The README warns that `npx @google/design.md lint DESIGN.md` on PowerShell can produce no output or even open `DESIGN.md` in a Markdown editor. The workaround is to use the dot-free alias `designmd` with `npx -p @google/design.md designmd lint DESIGN.md`. That shim resolves to the same entrypoint. There is also a common npm error, `ENOVERSIONS`, which the README attributes to npm not querying the public registry. That happens when a custom `registry=` in `.npmrc` or a corporate mirror has not synced the package. The fix is to run `npm config get registry` and ensure it returns `https://registry.npmjs.org/`. These are real friction points for enterprise adoption, and the README is honest about them.

Behavior with Unknown Content and Its Limits

The spec defines how a consumer should handle content it does not recognize. Unknown section headings are preserved without error. Unknown color token names are accepted if the value is valid. Unknown typography token names are accepted as valid typography. Unknown component properties are accepted with a warning. Duplicate section headings cause an error and the file is rejected. This lenient approach is practical for a format that will evolve, but it also means a typo in a token name might pass silently. The lint tool is supposed to catch broken token references. Check docs/spec.md before relying on motion or responsive design support.

Maintenance, License, and an Alternative Approach

The project is under the Apache-2.0 license, which permits commercial use and modification. The spec is still in an alpha version, as indicated by the `version` field example. The last push is dated 2026-10-16 and the latest release, 0.4.0, 2026-07-27, so the project is actively maintained. The CLI is published on npm as `@google/design.md`, and the lint and diff tools are the primary maintenance surface. The alternative is to write your own structured design token file, for example a JSON or YAML file with a custom schema, and have agents read that. That approach gives you full control over the token types and validation, but it lacks the built-in lint and diff tools. Another alternative is to use existing design token formats like Style Dictionary, but those are geared toward generating platform-specific code, not toward describing rationale for agents. DESIGN.md's differentiator is the combination of prose and tokens in a single file, plus the CLI tools that enforce structure and catch regressions.

Editorial conclusion

Adopt DESIGN.md if you are building agent-driven UI generation and need a single, versionable file that encodes both exact token values and the rationale behind them. Skip it if your design system relies on complex conditional states, motion, or responsive behavior, since the current schema covers only a fixed set of component properties. Before committing, verify that your npm registry can resolve @google/design.md, check the spec version (currently alpha) for breaking changes, and confirm your team can live with the Windows CLI workaround. The diff command's regression flag is a concrete reason to adopt it for design-system reviews, but the format's value depends on agents actually reading the file, which no tooling in this repository guarantees.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes