google-labs-code/design.md
Developer ToolsA Markdown-plus-YAML spec and linter that gives coding agents a structured, persistent design system to build UIs from.
What it is
DESIGN.md defines a file format for handing a visual identity to coding agents. Each file mixes machine-readable design tokens (colors, typography, spacing, rounding, motion, components) in YAML with human-readable rationale in Markdown, so an agent gets both exact values and the reasoning behind them.
The repo ships the format specification plus a TypeScript CLI for validating, comparing and exporting these files. It targets teams that want agents to produce visually consistent UI instead of guessing at styles on each task.
Quick start
Requires Node.js and npm with access to the public registry npm. Author a DESIGN.md with a YAML front-matter block of tokens and ## sections for rationale, following the example in the README.
Validate it:
npx @google/design.md lint DESIGN.md
Output defaults to JSON with findings and a summary of errors, warnings and infos. Compare two revisions and export tokens:
npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
lint returns exit code 1 on errors, diff returns 1 on regressions, and export supports Tailwind v3 JSON, Tailwind v4 CSS and DTCG JSON. The linter is also importable from @google/design.md/linter.
On Windows, the design.md bin name can collide with the Markdown file association, so the README recommends the dot-free designmd alias:
npx -p @google/design.md designmd lint DESIGN.md
Format essentials
Tokens live in YAML front matter or fenced YAML blocks; the Markdown body is organized into ordered ## sections (Overview, Colors, Typography, Layout, Elevation, Shapes, Motion, Voice, Components, Do's and Don'ts), which may be omitted but not reordered. Token references use {path.to.token} syntax. A linter rule flags broken references, missing primary colors or typography, WCAG AA contrast failures and out-of-order sections. Unknown sections and token names are preserved rather than rejected, so extension keys stay safe. The full specification is in docs/spec.md, with a condensed version in the online docs.
Constraints
The format is at version alpha; the spec, schema and CLI are under active development and may change. The CLI needs Node.js and npm, and npx resolves the package from the public registry, so corporate mirrors that have not synced @google/design.md will fail with ENOVERSIONS until the registry is fixed. Licensing is Apache-2.0. The project states it is not eligible for Google's OSS vulnerability rewards program.
HotRepo's take
The project entered the daily all-language list across late June 2026 with reported daily gains of roughly 500 to 2,300 stars, peaking at 2,319 on June 26, and reappeared in the TypeScript weekly list at 16th place in mid-November 2026 with 143 stars gained. That pattern suggests a strong initial burst followed by a much smaller sustained trickle.
The HN thread drew 37 points and 4 comments. Commenters questioned whether a durable design document belongs in the workflow at all, noting that themes and component files already encode the same values (discussion), and asked how DESIGN.md would relate to Figma tokens, tailwind.config.js and AGENTS.md (discussion). Those are real integration questions the alpha spec does not fully settle; the diff and export commands are the concrete answer to keeping the file consistent with existing token sources.
Written by AI from the project's README, updated . The project's own docs are the source of truth.
Hacker News
You might also like
- elayadesign/ai-design-skillsA markdown rules file that steers AI coding tools to build a landing page with structure, copy and visual system.
- emilkowalski/skillsAgent skills that give coding assistants concrete UI, animation, and interaction design guidance.
- humanlayer/skillsA collection of installable Claude Code and Codex skills for research, implementation, visual PRs, and agent-loop design.
- avenoxai/avenoxbeyinLocal Markdown memory system that lets AI coding agents save, retrieve and reuse notes across sessions.
- mattpocock/skillsA set of composable agent skills for planning, spec-writing, TDD, debugging and codebase design with coding agents.