---
id: Mineru98/skills-store/design-md-validator
version: "afc38921"
license: MIT
install: manual
updated: 2026-07-28
---

# design-md-validator — This skill validates DESIGN.md files using Google's @google/design.md specification, catching structural errors, broken token references, and design-system quality issues. It runs a bundled Node script to lint YAML front matter, component properties, and WCAG contrast ratios, then reports findings with actionable fixes. Use it to verify design tokens before shipping or to compare versions for regressions.

Publisher: Mineru98 · Stars: 11 · Updated: 2026-07-28

Install (manual): `git clone https://github.com/Mineru98/skills-store`

## SKILL.md

# 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:

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

Scan the current tree for likely DESIGN.md files:

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

Compare two versions for regressions:

```bash
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.


[View on SkillFed](https://skillfed.io/Mineru98/skills-store/design-md-validator) · [View on GitHub](https://github.com/Mineru98/skills-store)