DESIGN.md Validator

Visão Geral

Valida arquivos DESIGN.md contra a especificação oficial do Google usando o CLI @google/design.md. Funciona com arquivos locais e URLs remotas. Sempre usa npx para rodar a versão mais recente — nunca desatualizado.

Quando Usar

• Validar um DESIGN.md contra a spec (lint)
• Verificar contraste WCAG entre cores de componentes
• Encontrar referências de tokens quebradas ({colors.X} inexistente)
• Comparar duas versões de um design system (diff)
• Exportar tokens para Tailwind v3/v4 ou W3C DTCG
• Auditar schema do frontmatter YAML
• Verificar ordem canônica das seções

Instalação

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

Comandos Principais

Lint (validar)

npx @google/design.md lint DESIGN.md

Saída JSON com findings[] e summary { errors, warnings, infos }.

Diff (comparar versões)

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

Export (converter tokens)

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

Regras de Linting

Regra	Severidade	Verifica
broken-ref	error	Token references que não existem
missing-primary	warning	Sem cor primary definida
contrast-ratio	warning	Contraste abaixo de WCAG AA (4.5:1)
orphaned-tokens	warning	Tokens definidos mas não referenciados
missing-typography	warning	Sem tokens de tipografia
section-order	warning	Seções fora da ordem canônica
unknown-key	warning	Possível typo em chaves YAML

Ferramentas Oficiais Referenciadas

Ferramenta	Fonte	Propósito
@google/design.md CLI	npm / Google Labs	Linter oficial
stitch-design-taste	google-labs-code/stitch-skills	Gerador de DESIGN.md
design-md plugin	google-labs-code/stitch-skills	Extração de tokens

📄 Documentação completa no GitHub