design-md-validator

Files (3)

• SKILL.md
• linting-rules.md · references/
• token-schema.md · references/

SKILL.md (first lines)

# design-md-validator

Validate, lint, diff, and export DESIGN.md files using the official Google
`@google/design.md` CLI. Always uses the latest published version from npm —
no vendored copy, always up-to-date with the spec.

---

## When to Use

| Trigger | Action |
|---|---|
| User has a DESIGN.md file and wants validation | `lint` |
| User wants to compare two versions | `diff` |
| User wants to export tokens to Tailwind/DTCG | `export` |
| User wants to see the current spec | `spec` |
| User shares a URL to a raw DESIGN.md | Download locally first |
| User asks "is my design.md valid?" | `lint` + interpret findings |

---

## Core Commands

All commands use `npx @google/design.md` to ensure the latest version is always
used. Never install globally — `npx` resolves from the public npm registry.

### Lint (validate)

```bash
npx @google/design.md lint DESIGN.md
```

Output: JSON with `findings[]` and `summary { errors, warnings, infos }`.
Exit code 1 if errors found, 0 otherwise.

### Diff (compare versions)

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

Output: JSON with token-level changes (added, removed, modified) and regression flag.
Exit codes: `0` no regression, `1` regression (errors in "after" > errors in "before"),
`2` input failure (file not found or unreadable).

### Export (to other formats)

```bash
# Tailwind v3 config
npx @google/design.md export --format json-tailwind DESIGN.md

# Tailwind v4 CSS theme
npx @google/design.md export --format css-tailwind DESIGN.md

# W3C Design Tokens (DTCG)
npx @google/design.md export --format dtcg DESIGN.md

# CSS custom properties (optional --prefix)
npx @google/design.md export --format css-vars DESIGN.md
npx @google/design.md export --format css-vars --prefix ds DESIGN.md
```

`css-vars` shipped in npm 0.4.0 (2026-07-27). Pin with
`npx @google/design.md@0.4.0` only if you must freeze the CLI; default `npx`
already resolves 0.4.0+.

### Spec (output the format specification)

```bash
npx @google/design.md spec
npx @google/design.md spec --rules
npx @google/design.md spec --rules-only --format json
```

---

## Workflow

### 1. Obtain the DESIGN.md

**Local file:**
```bash
npx @google/design.md lint ./DESIGN.md
```

**From URL:**
If the user provides a URL to a remote DESIGN.md file, download it
locally first before validation. 

**From stdin:**
```bash
cat DESIGN.md | npx @google/design.md lint -
```

### 2. Discover the Active Rule Set

Before interpreting anything, check which rules the installed CLI actually
runs — the rule set changes between releases, and the bundled references are
a fallback, not the authoritative source:

```bash
npx @google/design.md spec --rules-only --format json
```

### 3. Run Lint

```bash
npx @google/design.md lint --format json DESIGN.md
```

### 4. Interpret Findings

Parse the JSON output and report to the user:

| Severity | Meaning | Action |
|---|---|---|
| `error` | Spec violation — file is invalid | Must fix |
| `warning` | Best practice violation — file is valid but suboptimal | Should fix |
| `info` | Informational — suggestions for improvement | Nice to fix |

From fabricioctelles/skills, Apache-2.0.

More from fabricioctelles/skills