lint

Validate a DESIGN.md against the schema.

Synopsis

design-md lint <file> [--format=text|json]

Validate a DESIGN.md file against the schema. Checks required fields, color role coverage, section count, and frontmatter structure. Returns warnings (non-fatal) and errors (exit code 1).

Options

What gets checked

Required fields

The frontmatter must include name, tagline, spec, colors, and typography. Missing any field raises an error.

Example error message:

✗ error missing-field Required field "name" is missing.

Color roles

When a colors object exists, the linter looks for recommended roles:

• colors.bg — background color (recommended)
• colors.text — default text color (recommended)
• colors.brand or colors.primary — at least one primary brand color (recommended)

Missing these raises warnings, not errors — your file is valid without them, but explicit role assignment helps consumers understand intent.

Example warnings:

⚠ warn  missing-color-role colors.bg is recommended.
⚠ warn  missing-primary A primary brand color (colors.brand or colors.primary) is recommended.

Section count

The body must have at least 3 level-2 Markdown sections (## Section Title). Fewer than 3 raises a warning; the linter suggests 5+ for a full guide.

Example warning:

⚠ warn  few-sections Only 2 ## sections — recommend 5+.

Frontmatter structure

If the file has no YAML frontmatter block (delimited by ---), or if the YAML is invalid, you’ll get an error:

✗ error invalid-frontmatter YAML parse error: ...
✗ error missing-frontmatter No YAML frontmatter found.

Examples

Text output (no issues)

$ design-md lint ./stripe.md
✓ No issues found.
  4 sections · 8 colors · 3 type roles

Text output (with issues)

$ design-md lint ./draft.md
✗ error missing-field Required field "spec" is missing.
⚠ warn  missing-color-role colors.bg is recommended.
⚠ warn  few-sections Only 2 ## sections — recommend 5+.

JSON output

$ design-md lint ./stripe.md --format=json
{
  "file": "/path/to/stripe.md",
  "findings": [],
  "summary": {
    "errors": 0,
    "warnings": 0,
    "infos": 0
  },
  "sections": [
    "Visual Theme & Atmosphere",
    "Color Palette",
    "Typography"
  ]
}

With errors:

$ design-md lint ./draft.md --format=json
{
  "file": "/path/to/draft.md",
  "findings": [
    {
      "level": "error",
      "code": "missing-field",
      "field": "spec",
      "msg": "Required field \"spec\" is missing."
    },
    {
      "level": "warn",
      "code": "missing-color-role",
      "msg": "colors.bg is recommended."
    }
  ],
  "summary": {
    "errors": 1,
    "warnings": 1,
    "infos": 0
  },
  "sections": [
    "Overview",
    "Colors"
  ]
}

Output

Text format

Human-readable output with color-coded markers:

• ✓ No issues found. — success line, followed by a dimmed summary of section, color, and type role counts
• ✗ error <code> — fatal issue; exit code will be 1
• ⚠ warn <code> — non-fatal issue; doesn’t affect exit code
• Dimmed <code> label helps with filtering or CI integration

JSON format

Structured output for programmatic consumption:

• file — the resolved file path
• findings — array of objects with level (error, warn, info), code (e.g., missing-field), optional field or other context, and msg
• summary — count of errors, warnings, infos
• sections — list of ## section titles in the body

Exit codes

• 0 — Validation passed (no errors; warnings do not cause non-zero exit)
• 1 — One or more errors found
• 2 — Usage error (missing file argument)

Related

• extract — export tokens as JSON or TypeScript
• diff — compare two DESIGN.md files token-by-token
• CLI overview — all commands and workflows