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

> Easily validate your DESIGN.md files with the CLI using the design.md lint command. Get instant feedback on structure and rules for better documentation.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-07-04

---

**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`](https://github.com/google-labs-code/design.md/blob/main/design.md) CLI from the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash
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)](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)](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)](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)](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)](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:

```bash
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**:

```bash
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)](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:

```bash
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)](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)](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)](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`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash
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)](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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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)](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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md).