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

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 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, 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 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 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:

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:

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:

#!/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 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 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 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.

Can the diff command handle missing files gracefully?

Yes, the readInput function (lines 45-52 in 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 (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.

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