design-md

Write a Markdown file with YAML frontmatter containing version, name, colors, typography, rounded, spacing, and components tokens, followed by canonical sections like Overview, Colors, and Components. Use token references like {colors.primary} in component definitions instead of repeating hex values.

Run npx -y @google/design.md lint DESIGN.md to check component textColor against backgroundColor for WCAG AA 4.5:1 contrast. The lint command also catches broken token references, missing primary colors, and out-of-order sections.

Yes, the CLI exports to Tailwind v3 theme JSON via --format json-tailwind and to a Tailwind v4 CSS @theme block via --format css-tailwind. It also supports W3C DTCG JSON via --format dtcg for cross-tool token pipelines.

On Windows the design.md bin name collides with the .md file association, causing a silent no-op or opening the file in an editor. Use the dot-free alias instead: npx -y -p @google/design.md designmd lint DESIGN.md.

Common pitfalls include nesting component variants instead of using sibling keys like button-primary-hover, leaving hex colors unquoted so YAML misparses them, and typo-ing typography sub-properties which are silently dropped from exports. Token references must use full dotted paths like {colors.primary}.