# How the Diff Command Detects Token-Level Regressions Between DESIGN.md Files

> Discover how the diff command detects token level regressions in DESIGN.md files by linting and comparing token maps, flagging changes that introduce more errors. Learn about regression detection.

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

---

**The `diff` command detects token-level regressions by linting both [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) files, comparing their extracted token maps for changes, and flagging regressions when the newer file introduces 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 analyzing token-level differences between two versions of a [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file. By parsing both documents into structured token maps and comparing them systematically, the command identifies exactly which design tokens changed, were added, or were removed, while also detecting quality regressions through lint error analysis.

## Linting Both Files to Extract Token Maps

The diff process begins by running the linter on both the **before** and **after** versions of the design document. In [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts) (lines 46–48), the command calls the `lint` function for each file:

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

```

Each call returns a `DesignSystemState` object containing structured token maps for **colors**, **typography**, **rounded corners**, **spacing**, and **components**. These maps represent the complete design system state extracted from the markdown files, providing the foundation for granular comparison.

## Serializing Component Definitions

Before the comparison routine can execute, the command normalizes the component data structure. Components are stored internally as `Map<string, ComponentDef>` objects, which the diffing algorithm cannot compare directly. 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), the command converts these maps into plain objects:

```typescript
const beforeComponents = Object.fromEntries(beforeReport.components);
const afterComponents  = Object.fromEntries(afterReport.components);

```

This serialization step enables the generic `diffMaps` utility to perform deep equality checks on component definitions alongside other token types.

## Granular Token Comparison 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 through two `Map` objects and categorizes differences into three distinct buckets:

- **Added** – Keys present only in the *after* map (new tokens)
- **Removed** – Keys present only in the *before* map (deleted tokens)
- **Modified** – Keys present in both maps whose values differ, checked via `JSON.stringify` comparison

This granular categorization applies to every token type in the design system, yielding a detailed breakdown of exactly which colors, typography scales, spacing values, or component properties changed between versions.

## Detecting Quality Regressions

Beyond tracking token changes, the `diff` command detects **quality regressions** by comparing the lint summary statistics. As implemented in lines 68–70 of [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts):

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

```

A regression is flagged when the *after* file contains more errors or warnings than the *before* file. This indicates that the proposed changes introduce new validation failures or degrade design system quality, even if the tokens themselves are syntactically valid.

## Output Format and Exit Codes

The final diff result includes both the token-level changes and the regression flag. The command formats this data as either JSON or Markdown based on CLI flags, then exits with code `1` when a regression is detected or `0` when no regression exists (lines 72–74 in [`diff.ts`](https://github.com/google-labs-code/design.md/blob/main/diff.ts)). This behavior enables integration into CI/CD pipelines, where non-zero exit codes can block merges that introduce design system regressions.

## Practical Usage Example

Execute the diff command from the CLI to compare two design files:

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

```

The output provides a structured view of all changes:

```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 show exactly which tokens changed, while the `regression` boolean indicates whether quality degraded.

## Summary

- The `diff` command in [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts) **lints both files** to extract structured `DesignSystemState` objects containing token maps.
- The `diffMaps` utility in [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) performs **granular comparisons** of token maps, categorizing changes as added, removed, or modified.
- **Quality regressions** are detected when the newer file contains more lint errors or warnings than the previous version.
- The command exits with code `1` when regressions are detected, making it suitable for **CI/CD integration**.
- All component definitions are **serialized from Map to plain objects** before comparison to enable generic diffing logic.

## Frequently Asked Questions

### What is a token-level regression in DESIGN.md?

A token-level regression occurs when changes to a [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file introduce new validation errors or warnings, or when design tokens are removed or modified in ways that break existing design system contracts. The `diff` command specifically flags regressions when the *after* state contains more lint errors or warnings than the *before* state, indicating a quality degradation even if the syntax remains valid.

### How does the diff command compare token maps?

The command uses the `diffMaps` utility function in [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) (lines 58–84) to compare two `Map` objects. It walks both maps simultaneously to identify keys that exist only in the new version (**added**), only in the old version (**removed**), or in both with different values (**modified**). Value comparison uses `JSON.stringify` to detect changes in complex token definitions.

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

The regression flag is set to `true` when `afterReport.summary.errors > beforeReport.summary.errors` or when `afterReport.summary.warnings > beforeReport.summary.warnings`, 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). This comparison of lint summary statistics ensures that any increase in validation failures marks the change as a regression, regardless of whether the underlying tokens were added, removed, or modified.

### Where is the diff logic implemented in the source code?

The primary implementation resides in [`packages/cli/src/commands/diff.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/commands/diff.ts), which orchestrates the linting, serialization, and regression detection workflow. The map comparison algorithm is defined in [`packages/cli/src/utils.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/utils.ts) as the `diffMaps` function. The linting functionality itself is imported from [`packages/cli/src/linter/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/index.ts), which parses [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) content into the structured token maps used throughout the diff process.