DESIGN.md Validator

Overview

Validates DESIGN.md files against the official Google design.md specification using the @google/design.md CLI linter. Works with local files and remote URLs. Always uses npx to run the latest published version — never stale.

When to Use

• Lint a DESIGN.md for spec compliance
• Check WCAG contrast ratios between component colors
• Find broken token references ({colors.X} that don’t exist)
• Diff two design system versions for regressions
• Export tokens to Tailwind v3/v4 or W3C DTCG format
• Audit YAML frontmatter schema
• Verify canonical section order

Installation

npx skills add https://github.com/fabricioctelles/skills -s design-md-validator

Core Commands

Lint (validate)

npx @google/design.md lint DESIGN.md

Outputs JSON with findings[] and summary { errors, warnings, infos }.

Diff (compare versions)

npx @google/design.md diff DESIGN.md DESIGN-v2.md

Export (convert tokens)

npx @google/design.md export --format css-tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

Linting Rules

Rule	Severity	What it checks
broken-ref	error	Token references that don’t resolve
missing-primary	warning	No primary color defined
contrast-ratio	warning	Below WCAG AA minimum (4.5:1)
orphaned-tokens	warning	Tokens defined but never referenced
missing-typography	warning	No typography tokens present
section-order	warning	Sections out of canonical order
unknown-key	warning	Possible typo in YAML keys

Official Tools Referenced

Tool	Source	Purpose
@google/design.md CLI	npm / Google Labs	Official linter
stitch-design-taste	google-labs-code/stitch-skills	DESIGN.md generator
design-md plugin	google-labs-code/stitch-skills	Token extraction

📄 Full documentation on GitHub