design-md-validator

DESIGN.md Validator

Overview

Validate DESIGN.md files before using them as design-system source of truth. Prefer the bundled script for repeatable checks, then interpret the JSON findings into concrete fixes.

Quick Start

Run the validator against one file:

node .codex/skills/design-md-validator/scripts/validate_design_md.mjs DESIGN.md

Scan the current tree for likely DESIGN.md files:

node .codex/skills/design-md-validator/scripts/validate_design_md.mjs --discover .

Compare two versions for regressions:

node .codex/skills/design-md-validator/scripts/validate_design_md.mjs DESIGN.md --diff-before DESIGN.old.md

The script is a Node/npx wrapper around npx --yes @google/design.md, so Node/npm must be available. It returns nonzero when errors exist, or when warnings exist with --strict-warnings.

Workflow

1. Locate the target file. Use --discover when the user says "check design.md" without naming a path.
2. Run the bundled validator. Use raw npx @google/design.md lint --format json <file> only if the wrapper is unavailable.
3. Treat summary.errors > 0 as blocking. Fix errors before addressing warnings.
4. Explain warnings as design-system quality risks, not syntax failures.
5. Re-run validation after edits and report the final error/warning/info counts.
6. For migrations or updates, run --diff-before and treat regression: true as blocking unless the user explicitly accepts it.

Finding Triage

• broken-ref error: define the missing token or update the reference path.
• Unknown component sub-token warning: rename to one of backgroundColor, textColor, typography, rounded, padding, size, height, or width, unless preserving a domain-specific extension is intentional.
• missing-primary warning: add colors.primary or document why another color role is the main brand color.
• missing-typography warning: add at least one typography token with fontFamily and fontSize.
• contrast-ratio warning: adjust component backgroundColor or textColor to meet WCAG AA 4.5:1 for normal text.
• section-order warning: reorder known ## sections to match the canonical sequence.
• orphaned-tokens warning: either reference the token from components or remove it if unused.

Reference

• references/design-md-spec-summary.md — schema, canonical section order, accepted component properties, CLI command reference.
• references/lint-rules.md — per-rule fix recipes for each of the eight lint rules.
• references/spec-checklist.md — manual review checklist for offline / sandboxed environments where npx cannot reach the registry.

Known CLI quirks

• The summary block keys observed from the live CLI are errors, warnings, and infos (plural). The upstream README documents this as info (singular). Read both keys defensively when parsing JSON directly: summary.infos ?? summary.info ?? 0.
• Color values inside components.* may be rgba(...) literals (used for glass surfaces). Don't treat these as broken — they're accepted there even though colors.* only allows #RRGGBB.
• npx --yes @google/design.md does the install on first run; expect a 5-30s delay on a cold cache. The bundled wrapper waits for completion; if a caller hits a fixed timeout, retry once before treating the CLI as unreachable.

Output

When reporting results, include:

• File path checked.
• Error, warning, and info counts.
• The highest-severity findings with paths.
• Exact fixes made, if any.
• Verification command rerun after edits.