design.md: A format specification for describing a visual identity to coding agents.
What problem it solves
Coding agents need both exact design values and the rationale for applying them consistently. Without a structured, persistent representation of a design system, agents may miss design context or interpret visual guidance inconsistently.
Key features
Structured tokens and design rationale — The format combines machine-readable design tokens with human-readable Markdown rationale. YAML values define the normative appearance, while prose explains their intended use.
Source: README
Validation and structured findings — The CLI validates files against the specification, checks token references and WCAG contrast ratios, and returns findings as structured JSON.
Source: README
Version comparison — The diff command compares two versions of a design system and reports token-level changes, prose regressions, and changes in finding counts.
Source: README
Design token export — Tokens can be exported to Tailwind v3 JSON, Tailwind v4 CSS, or W3C Design Tokens Format JSON for use in downstream workflows.
Source: README
CLI and programmatic API — The project provides commands for linting, diffing, exporting, and reading the specification, plus a programmatic linting API for library use.
Source: README, packages
Quick start
Copied verbatim from the project's README.
npm install @google/design.mdnpx @google/design.md lint DESIGN.mdWho it may suit
This may suit teams that maintain design systems and coding agents, as well as developers who need a persistent, structured representation of a visual identity.
Topics to discuss
How should the format evolve as the alpha specification matures?
Which design-system details are still missing from the token schema and section model?
What linting and regression checks should be required in a production workflow?
Written by ReadmeX AI from the project's README, source and public GitHub data; it may contain mistakes.
Read the original README https://github.com/google-labs-code/design.md#readme
ReadmeX opened this community for a trending project; it is not run by the project. Maintainers can claim it from the community page.
Comments
…