# How to Use the design.md diff Command in CI/CD Pipelines

> Learn how to use the design.md diff command in CI/CD to automatically block pull requests with design regressions. Detect errors and warnings before they merge.

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

---

**The `diff` command exits with status code `1` when the "after" design file contains more errors or warnings than the baseline, enabling CI/CD pipelines to automatically block pull requests that introduce design regressions.**

The `@google/design.md` CLI provides a specialized `diff` command that parses two [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files, lints them, and produces a token-level diff highlighting changes to colors, typography, and spacing. Because it returns a non-zero exit code when regressions are detected, you can integrate it into CI/CD pipelines to enforce design system consistency before code merges.

## How the diff Command Detects Regressions

### Input Loading and Linting

In [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts), the command first loads both files using `readInput` (lines 45-52), which handles missing-file errors gracefully. It then invokes the shared `lint` library from [`packages/cli/src/linter/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts) to generate a `DesignSystemState` for each file and capture any linting findings (lines 56-58).

### Token Comparison and Serialization

The command uses the `diffMaps` utility from [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) to compare token maps and report added, removed, or changed entries (lines 60-68). For component-level tokens, it serializes components to ensure comparable states (lines 87-92).

### Exit Code Behavior for CI Gates

Crucially, the command sets the process exit code to `1` when the "after" file contains more errors or warnings than the "before" file (lines 78-84). This behavior allows CI systems to treat the diff as a failing test. The output format is controlled by `formatOutput` (lines 82-84) and defaults to JSON, with an optional human-readable text format.

## Implementing the diff Command in CI/CD Pipelines

### GitHub Actions Configuration

Configure a workflow step that fails automatically when design regressions are detected:

```yaml
name: Design Regression Test
on: [pull_request]

jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install design.md CLI
        run: npm install -g @google/design.md

      - name: Run diff
        id: diff
        run: |
          npx @google/design.md diff DESIGN.md DESIGN-v2.md \
            --format json > diff-report.json
        # The step fails automatically if exit code != 0

```

The step will **fail** (and block the merge) if the new design introduces more errors or warnings than the baseline.

### Azure Pipelines Integration

For Azure DevOps, set `continueOnError: false` to ensure the pipeline fails on regressions:

```yaml
steps:
- script: |
    npm i -g @google/design.md
    npx @google/design.md diff DESIGN.md DESIGN-pr.md
  displayName: 'Design diff check'
  continueOnError: false   # Fail pipeline on non-zero exit code

```

### Custom Scripting with JSON Output

Parse the JSON output for custom notifications or metrics collection:

```bash
#!/usr/bin/env bash
set -euo pipefail

# Run diff and capture JSON

DIFF_JSON=$(npx @google/design.md diff DESIGN.md DESIGN-pr.md --format json)

# Extract added colors (example using jq)

addedColors=$(echo "$DIFF_JSON" | jq -r '.tokens.colors.added[]?.key')
if [[ -n "$addedColors" ]]; then
  echo "New color tokens introduced: $addedColors"
fi

```

## Understanding Output Formats and Utilities

The `formatOutput` function in [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) serializes the diff results, while `diffMaps` handles the underlying comparison logic. By default, the command outputs JSON suitable for programmatic parsing, but you can specify `--format text` for human-readable output in local development or log inspection.

## Summary

- The `diff` command in `@google/design.md` compares two [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files and exits with code `1` when the target file has more lint errors than the baseline.
- Implementation in [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts) uses `readInput` (lines 45-52), the `lint` library (lines 56-58), and `diffMaps` (lines 60-68) to detect token changes.
- CI/CD pipelines can use this exit code behavior to block pull requests that introduce design regressions.
- JSON output enables automated parsing for custom notifications or metrics collection.
- Both GitHub Actions and Azure Pipelines can integrate the command using standard failure-on-exit-code semantics.

## Frequently Asked Questions

### What exit code does the design.md diff command return on success?

The command returns exit code `0` when the "after" file has no more errors or warnings than the baseline, and exit code `1` when regressions are detected, as implemented in lines 78-84 of [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts).

### Can the diff command handle missing files gracefully?

Yes, the `readInput` function (lines 45-52 in [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts)) specifically handles missing-file errors, allowing the command to fail gracefully with appropriate error messaging rather than unhandled exceptions.

### How does the diff command compare design tokens between files?

The command uses the `diffMaps` utility from [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) (referenced at lines 60-68) to compare token maps and identify added, removed, or changed entries for colors, typography, and spacing values.

### Is it possible to customize the output format for CI logs?

Yes, the `formatOutput` function (lines 82-84) supports both JSON (default) and human-readable text formats via the `--format` flag, allowing you to optimize output for machine parsing or human review in pipeline logs.