Layout vs Google's design.md
Google just open-sourced design.md: a YAML and Markdown format for describing design systems to AI coding agents. It is a clean, well-scoped spec, and it validates the category publicly. Here is how it compares to Layout, with credit where credit is due.
TL;DR
design.md is a well-crafted format. Layout is the productaround a superset of it — with multi-source extraction, bidirectional Figma sync, a 14-tool MCP server, an AI variant generator, a Kit Gallery, and full interoperability with Google's format through a companion export and matching DTCG tokens.
Where Layout and design.md agree
- Dual-layer format: machine-readable tokens plus human-readable prose
- W3C DTCG tokens.json as a portable export target
- Tailwind config as an export target
- Agent-first positioning
- Open-source CLI (@layoutdesign/context on npm, @google/design.md on npm)
- Covers colours, typography, spacing, shapes, elevation, components, do's and don'ts
- Community kit collections
- Preserved extensibility — unknown sections survive round-trips
Where Layout goes further
Full product, not just a format
Layout ships a browser Studio (AGPL-3.0), a CLI and MCP server (MIT), a Figma plugin, and a Chrome extension. Google shipped a spec and a CLI.
Multi-source extraction
Figma REST API, live Playwright websites, an inspect-as-you-browse Chrome extension, and a codebase scanner that reads Storybook CSF3 stories. design.md relies on hand-writing or a Google-only stitch-skills path.
Bidirectional Figma sync
Layout's Figma plugin pushes and pulls tokens, subscribes to FILE_UPDATE webhooks, and auto-regenerates the design system on change. design.md has no Figma integration.
Multi-mode tokens shipped
Light and dark tokens co-exist in Layout's layout.md, tokens.json ($extensions.mode), tokens.css ([data-theme="dark"]), and Tailwind config (darkMode). In design.md this is still open issue #13.
14-tool MCP server
get-design-system, get-tokens, get-component, check-compliance, preview, push-to-figma, design-in-figma, url-to-figma, update-tokens, scan-project, check-setup, and more. Works in Claude Code, Cursor, Windsurf, Copilot. design.md distributes through Google's Agent Skills standard only.
Live preview + AI variant generation
Layout's Explorer generates 2–6 variants per prompt, refines via image uploads, scores compliance, promotes to a component library, and pushes to Figma. A local preview server renders transpiled TSX at :4321. design.md has no generation or preview surface.
Three-tier token system
Primitive → Semantic → Component tokens, each with confidence annotations (/* extracted: high */ vs /* reconstructed: moderate */). design.md is flat: one level, no provenance.
Richer component format
Layout components carry props, variants, states, tokensUsed, versioning, status (draft|approved|deprecated), and source (manual|explorer|extraction|figma). design.md components are variant names in YAML.
Design-in-Figma and URL-to-Figma
Prompt → editable Figma frames with auto-layout and token-mapped styles. Capture a live URL as a Figma frame. Neither exists in design.md.
Community Kit Gallery
Layout's gallery at layout.design/gallery is a first-party platform where anyone can publish a kit from a Studio project and anyone else can import it in one click. design.md relies on an external awesome-list repo and PR-driven contributions.
What design.md does well
Seven-rule CLI linter
Broken refs, missing primaries, WCAG AA contrast, orphans, circular aliases, section ordering, property validation. Layout's check-compliance runs on generated code; design.md's lint runs on the file itself. We're adopting this.
diff command in the CLI
Token-level change detection between versions, JSON output for agents. Layout has extraction-diff in the UI but not the CLI. We're adopting this.
import command (DTCG → DESIGN.md)
Reverse of export, so existing DTCG-only projects can migrate. Layout exports but doesn't yet import the same way. We're adopting this.
Formal published spec
Google shipped a clean docs/spec.md. Layout's spec lives inside a synthesise.ts system prompt today, which is fine for generation and weak for SEO. We're publishing a formal spec.
Distribution via awesome-design-md
64k stars on a curated list of 69 brand DESIGN.md files. Layout has three kits and a gallery; we're building an adjacent awesome-layout-md repo with nightly sync from the gallery.
What we are adopting from them
- layout lint — CLI linter with the same seven rules plus a contrast-ratio annotator
- layout diff — version-to-version token diffing with CI-friendly JSON output
- layout import --from tokens.json — fully interoperable with DTCG
- Formal spec page at layout.design/spec
- uselayout/awesome-layout-md — curated public kit index
- Companion design.md in the export bundle so agents trained on Google's format pick us up too
design.md is a good spec. Layout is a product.
If you want to hand-author a file that describes your design system to an agent, design.md will serve you well. If you want the design system extracted from your Figma, inspected live in Chrome, synced bidirectionally, generated into variants, exported to every agent ecosystem, and published in a community gallery — that is Layout.