DESIGN.md Tools Compared
On this page
The DESIGN.md ecosystem has four kinds of tools: the reference library and CLI (@google/design.md) that validates and converts files, generators that create a DESIGN.md from a website or a design or a prompt, viewers that render an existing file so you can read it, and file libraries that offer ready-made DESIGN.md files to drop in. They solve different problems. This page maps the categories so you can pick the right one, and flags the tradeoffs (spec-compliance and privacy) to check before you rely on any of them.
Why categorize the tools#
"DESIGN.md tools" is a broad phrase. Some create files, some check files, some render files, and some hand you finished files. If you compare a generator against a viewer as if they were rivals, you end up comparing a factory to a window. The useful question is not "which tool is best?" but "which category do I need for what I am doing right now?"
There are four categories. Below is each one, what it does, and when it is the right choice.
The categories#
| Category | What it does | Reach for it when | Example |
|---|---|---|---|
| Reference library and CLI | Lints, diffs, and exports a DESIGN.md | You have a file and want to validate or convert it | @google/design.md |
| Generators | Create a DESIGN.md from a website, design, or prompt | You have a brand or a site but no file yet | Browser extensions, Figma plugins, URL-based web tools |
| Viewers and renderers | Render an existing file visually | You want to read or preview a file you already have | This site's viewer at /tool |
| File libraries | Offer ready-made DESIGN.md files to drop in | You want a proven starting point | Curated collections of pre-made files |
Reference library and CLI#
The anchor of the ecosystem is @google/design.md, the open-source package published by Google under the Apache 2.0 license (v0.3.0 at the time of writing). It is the reference implementation of the format, which makes it the tool other tools are measured against.
From the command line it does four things:
npx @google/design.md lint DESIGN.md # validate against the spec
npx @google/design.md diff v1.md v2.md # compare two versions
npx @google/design.md export DESIGN.md --format css-tailwind
npx @google/design.md spec # print the format spec for an agent
lint reports broken token references and WCAG AA contrast failures as structured findings. export converts a file to a Tailwind v4 @theme block or to W3C DTCG JSON. If you only adopt one tool, this is the one, because it is what makes a DESIGN.md verifiable rather than just a text file that looks about right. See the CLI reference for the full command set.
Generators#
Generators produce a DESIGN.md for you from some input you already have. The input varies by tool:
- From a website: browser extensions and URL-based web tools read a page's computed styles and format them into a DESIGN.md.
- From a design file: Figma plugins extract local styles and emit a DESIGN.md (and sometimes other agent files).
- From a prompt: hosted tools generate a file from a natural-language brief.
Generators are the fastest way to go from "I have a brand but no file" to a starting document. Two tradeoffs are worth checking before you trust the output:
- Spec-compliance is not guaranteed. A generated file can look plausible and still miss required keys or use values the spec does not accept. Always lint generator output:
npx @google/design.md lint DESIGN.md. Treat the generated file as a draft, not a finished spec-compliant document. - Hosted generators send your input to a server. A tool that extracts styles from a URL or a design usually processes that input remotely. If the brand is confidential, prefer a tool that runs locally, and read the tool's own privacy statement rather than assuming.
Because generator features and behavior change frequently, verify a specific tool's current capabilities against its own documentation rather than a comparison article.
Viewers and renderers#
A viewer takes a DESIGN.md you already have and renders it as something you can read: a navigable brand guideline with color swatches, type specimens, spacing scales, and component previews. It does not create a file and it does not change one. It shows you what is in the file.
This site's viewer at /tool is in this category. It is deliberately narrow: it renders a file and nothing else. Two properties define it:
- Render, not generate. It reads an existing DESIGN.md and displays it. If you want a file created from a brand, that is a generator's job, not this one's.
- Client-only, nothing uploaded. Parsing runs entirely in your browser. Your file never leaves your machine, which makes a viewer the safe way to inspect a confidential DESIGN.md.
A viewer is the right tool when you want to sanity-check a file: confirm the palette resolves, catch a missing color role, or read a system someone handed you before you build against it.
File libraries#
A file library is a curated collection of ready-made DESIGN.md files, often modeled on well-known design systems. You browse the collection, pick a style, and drop the file into your repository so an agent can start producing a matching UI immediately. Community-maintained lists, such as the awesome-design-md collection on GitHub, gather these files in one place.
Libraries are the right choice when you want a proven starting point rather than authoring from scratch or generating from your own brand. If you are searching for an alternative to a specific file library, the honest answer is that a library is not the same category as a viewer or a generator: pick the category by the job. Want to render a file you have? Use a viewer. Want to create one from your brand? Use a generator. Want a finished file to adapt? Use a library.
Whichever file you start from, lint it and render it before you build on it, so you know it is spec-compliant and says what you think it says.
Choosing by task#
- I have a brand but no file. Use a generator, then lint the output.
- I have a file and want to check or convert it. Use the
@google/design.mdCLI. - I want to read or preview a file. Use a viewer like the one at
/tool. - I want a ready-made file to adapt. Use a file library, then lint and render it.
The categories are complementary. A realistic workflow uses several: generate a first draft, lint it with the CLI, render it in a viewer to confirm it reads correctly, and keep the CLI in your pre-commit checks. See the spec guide for what a compliant file must contain.