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

The diff command detects token-level regressions by linting both 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 repository provides granular visibility into design system changes by analyzing token-level differences between two versions of a 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 (lines 46–48), the command calls the lint function for each file:

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, the command converts these maps into plain objects:

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

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

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

The output provides a structured view of all changes:

{
  "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 lints both files to extract structured DesignSystemState objects containing token maps.
• The diffMaps utility in 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 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 (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. 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, which orchestrates the linting, serialization, and regression detection workflow. The map comparison algorithm is defined in packages/cli/src/utils.ts as the diffMaps function. The linting functionality itself is imported from packages/cli/src/linter/index.ts, which parses DESIGN.md content into the structured token maps used throughout the diff process.

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