How to Validate a DESIGN.md File Using the CLI: The Complete Guide

You can validate a DESIGN.md file using the design.md lint command, which parses the file, applies a default rule set, and returns a structured JSON or Markdown report with exit code 1 on failure.

The design.md CLI from the google-labs-code/design.md repository provides a built-in lint sub-command for programmatically checking DESIGN.md files against the formal specification. This tool ensures your design system documentation follows proper front-matter structure, token references, and contrast requirements.

Installing the CLI

Before you can validate DESIGN.md files, install the @google/design.md package globally using your preferred package manager:

npm i -g @google/design.md

# or

pnpm add -g @google/design.md

# or  

yarn global add @google/design.md

The lint Command Architecture

The lint functionality is implemented in [packages/cli/src/commands/lint.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/lint.ts), which orchestrates the validation pipeline. This command is registered in the main entry point at [packages/cli/src/index.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/index.ts#L23-L35) alongside other sub-commands like diff, export, and spec.

When you run design.md lint, the CLI executes a four-stage pipeline defined in the source code:

1. Input ingestion via [packages/cli/src/utils.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts#L38-L55) (accepts file paths or stdin)
2. Lint execution via the lint function in [packages/cli/src/linter/index.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts#L15-L17)
3. Report formatting using formatOutput in [packages/cli/src/utils.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts#L62-L68)
4. Exit code management for CI integration (returns 1 on errors, 0 on success)

Validating DESIGN.md Files

Basic File Validation

To validate a single DESIGN.md file and receive a JSON report of any violations:

design.md lint path/to/DESIGN.md

The command reads the file using the readInput utility, which throws a FileReadError with a descriptive message if the file cannot be accessed.

Validating from Stdin

For programmatic workflows or piped content, the CLI accepts - as an input source to read from stdin:

cat path/to/DESIGN.md | design.md lint -

This is handled in the input logic at [packages/cli/src/utils.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts#L38-L55), enabling integration with build scripts and other CLI tools.

Output Formats

By default, the linter outputs JSON for machine parsing. For human-readable reports during development, use the --format markdown flag:

design.md lint path/to/DESIGN.md --format markdown

The formatOutput helper in [packages/cli/src/utils.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts#L62-L68) handles the transformation between formats.

How the Validation Works

The linter applies the DEFAULT_RULES set defined in [packages/cli/src/linter/rules/index.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/rules/index.ts). These rules validate:

• Front-matter structure and required fields
• Token references for consistency
• Contrast ratios for accessibility compliance

The public lint function exported from [packages/cli/src/linter/index.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts#L15-L17) loads the formal specification from docs/spec.md, builds a DesignSystemState, and executes the rule set against your markdown content.

CI/CD Integration

The CLI returns exit code 1 when any lint errors are detected, making it ideal for continuous integration pipelines. Use the command in shell scripts to fail builds on validation errors:

if ! design.md lint path/to/DESIGN.md; then
  echo "❌ DESIGN.md validation failed"
  exit 1
fi

This behavior is explicitly implemented in [packages/cli/src/commands/lint.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/lint.ts) to support automated quality gates.

Summary

• Install the @google/design.md package globally to access the CLI.
• Run design.md lint <file> to validate DESIGN.md files against the formal specification.
• Use - as the input path to validate content streamed via stdin.
• Format output as JSON (default) or Markdown using the --format flag.
• Integrate into CI pipelines by checking the exit code (1 for errors, 0 for success).
• Reference the source implementation in packages/cli/src/commands/lint.ts for custom tooling.

Frequently Asked Questions

What package do I need to install to validate DESIGN.md files?

You need to install @google/design.md globally using npm, pnpm, yarn, or bun. This package provides the design.md executable with the lint sub-command.

Can I validate DESIGN.md content from stdin instead of a file?

Yes. Pass - as the file argument to read from stdin: cat design.md | design.md lint -. The input handling logic in packages/cli/src/utils.ts supports both file paths and standard input streams.

What exit code does the linter return when validation fails?

The CLI exits with code 1 when lint errors are found and 0 when the file passes all checks. This enables straightforward integration into CI/CD scripts and pre-commit hooks.

Where are the lint rules defined in the source code?

The default rule set is exported as DEFAULT_RULES from [packages/cli/src/linter/rules/index.ts](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/rules/index.ts). These rules check front-matter validity, token references, and contrast requirements against the specification in docs/spec.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}