# How the Diff Command Detects Token and Prose Regressions Between DESIGN.md Files

> Learn how the diff command detects token and prose regressions in DESIGN.md files. It extracts token maps, compares them, and flags increased lint errors in newer versions.

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

---

**The `diff` command lints two DESIGN.md files to extract structured token maps, compares them using the `diffMaps` utility to categorize changes as added, removed, or modified, and flags a regression when the newer file contains more lint errors or warnings than the previous version.**

The `diff` command in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository provides granular visibility into design system changes by comparing both the semantic token structure and the prose quality between two versions of a DESIGN.md file. This CLI tool runs a specialized linter to extract color palettes, typography scales, spacing values, and component definitions, then analyzes differences to detect structural token changes while monitoring for quality regressions through lint summary comparisons.

## The Linting and Comparison Pipeline

The diffing process operates in three distinct phases: extracting structured data from both files, normalizing component definitions for comparison, and running a granular map difference algorithm.

### Extracting Token Maps with the Linter

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 invokes the `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)) on both the before and after file contents:

```typescript
const beforeReport = lint(beforeContent);
const afterReport  = lint(afterContent);

```

The linter produces a `DesignSystemState` object containing categorized **token maps** for colors, typography, rounded corners, spacing, and components. These maps serve as the canonical representation of the design system's tokens, enabling precise structural comparison rather than simple text diffing.

### Normalizing Component Definitions

Before the diff algorithm runs, component definitions stored as `Map<string, ComponentDef>` are serialized into plain JavaScript objects. According to lines 55-58 in [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts), this conversion ensures the generic map-diff routine can traverse and compare component structures without Map-specific iteration logic interfering with the comparison algorithm.

### Granular Diff Analysis with diffMaps

The core comparison logic resides in the `diffMaps` helper function within [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) (lines 58-84). This utility walks both token maps simultaneously and categorizes differences into three distinct buckets:

- **Added**: Keys present only in the "after" map
- **Removed**: Keys present only in the "before" map  
- **Modified**: Keys present in both maps whose values differ (compared via `JSON.stringify`)

This categorization is applied individually to every token type—including colors, typography scales, and spacing values—yielding a granular view of exactly which design tokens changed between versions.

## Regression Detection Strategy

Beyond tracking structural token changes, the command detects **quality regressions** by comparing the lint summaries of both files.

### Comparing Lint Summaries

After diffing the token maps, the command inspects the error and warning counts from both lint reports. According to lines 68-70 in [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts), a regression is flagged when:

```typescript
regression: afterReport.summary.errors > beforeReport.summary.errors
             || afterReport.summary.warnings > beforeReport.summary.warnings,

```

This logic treats any increase in lint errors or warnings as a prose or structural quality regression, indicating that the newer version introduces more issues than the previous version.

### Exit Codes and CI Integration

The process exit code is set to `1` when a regression is detected and `0` otherwise (lines 72-74 in [`diff.ts`](https://github.com/google-labs-code/design.md/blob/main/diff.ts)). This behavior enables seamless integration with CI/CD pipelines, allowing automated builds to fail when design system quality degrades.

## Reading the Diff Output

The command supports both JSON and Markdown output formats, with JSON providing the most detailed programmatic access to token-level changes.

### JSON Structure

The output includes separate sections for token changes and quality metrics:

```json
{
  "tokens": {
    "colors": {
      "added": ["brand-primary"],
      "removed": [],
      "modified": ["neutral-100"]
    },
    "typography": { "added": [], "removed": [], "modified": [] }
  },
  "findings": {
    "before": { "errors": 0, "warnings": 1, "infos": 2 },
    "after":  { "errors": 1, "warnings": 1, "infos": 2 },
    "delta":   { "errors": 1, "warnings": 0 }
  },
  "regression": true
}

```

The `added`, `removed`, and `modified` arrays under each token category provide developers with exact visibility into which specific tokens changed, while the `findings` object tracks the error and warning delta between versions.

### CLI Usage

Run the comparison with the following command structure:

```bash
design-cli diff path/to/old/DESIGN.md path/to/new/DESIGN.md --format json

```

## Summary

- The `diff` command operates by linting both DESIGN.md files to generate structured `DesignSystemState` objects containing token maps for colors, typography, and components.
- The `diffMaps` utility in [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) categorizes changes into **added**, **removed**, and **modified** tokens by comparing serialized map structures.
- A regression is flagged when the after file contains more lint errors or warnings than the before file, indicating a quality degradation in prose or token definitions.
- The command exits with code `1` when regressions are detected, making it suitable for CI/CD integration.
- Output includes granular token-level changes and summary statistics in JSON or Markdown formats.

## Frequently Asked Questions

### What triggers a regression flag in the diff command?

A regression is triggered when the lint summary of the newer DESIGN.md file shows an increase in either error count or warning count compared to the older file. According to the logic in [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts) lines 68-70, the command compares `afterReport.summary.errors` against `beforeReport.summary.errors` (and similarly for warnings) to determine if quality has degraded.

### How does diffMaps determine if a token was modified?

The `diffMaps` function in [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) uses `JSON.stringify` to compare values for keys present in both maps. If the serialized string representation of a token's value differs between the before and after maps, the key is categorized as **modified** rather than unchanged. This approach handles nested objects and arrays reliably while maintaining strict equality checks.

### Can the diff command output Markdown instead of JSON?

Yes, the `diff` command supports multiple output formats via the `--format` flag. While JSON provides the most detailed programmatic output for token-level analysis, Markdown formatting is available for human-readable reports. The exit code behavior (returning `1` on regression) remains consistent regardless of the chosen output format.

### Which token categories are compared by the diff command?

The command compares all token maps extracted by the linter, including **colors**, **typography**, **rounded corners**, **spacing**, and **components**. Each category is diffed independently using the same `diffMaps` algorithm, producing separate added/removed/modified lists for every token type defined in the DESIGN.md specification.