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

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 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, the command first invokes the lint function (exported from packages/cli/src/linter/index.ts) on both the before and after file contents:

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, 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 (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, a regression is flagged when:

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). 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:

{
  "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:

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 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 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 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.

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