diff

Token-level diff between two DESIGN.md files.

Synopsis

design-md diff <a> <b> [--format=text|json]

Description

Compare two DESIGN.md files token-by-token across colors, radii, typography, spacing, and components. Output shows what was added, removed, or modified between the two files. Useful for tracking design evolution, validating updates before merge, or generating changelogs.

Both <a> and  can be local file paths or relative paths; they’re resolved from the current working directory.

Options

Flag	Default	Description
`--format`	`text`	Output format. `text` for colored terminal output; `json` for piping to tools.

What gets diffed

The diff compares five token categories:

Colors

All colors in the colors section, including nested palettes. Flattened to palette.shade keys (e.g., brand.900, neutral.50). Shows hex values.

Radii

All radius tokens under radius (e.g., sm, md, lg, xl). Shows pixel or rem values.

Typography

All typography tokens under typography (e.g., body, heading, label). Includes nested properties like family, size, weight, lineHeight. Shown flattened as body.family, body.size, etc.

Spacing

All spacing tokens under spacing (e.g., xs, sm, md, lg). Shows pixel or rem values.

Components

All component definitions under components (e.g., button, card, input). Shown flattened to show individual property changes.

Examples

Compare two local DESIGN.md files

design-md diff DESIGN.md DESIGN.backup.md

Terminal output (colored):

Colors
  + brand-new = #ff6b35
  − brand-old (was #0055de)
  ~ primary #635bff → #5b50ff

Radii
  no changes

Typography
  ~ body.size 16px → 15px
  + label.family "Inter", sans-serif
  − heading.weight 600

Spacing
  no changes

Components
  + button.padding [12px, 16px]
  ~ card.shadow 0 2px 8px → 0 2px 12px

Compare with custom paths

design-md diff ./tokens/stripe.md ./tokens/stripe-v2.md

Output shows only the sections that have changes; unchanged sections are marked “no changes”.

Export to JSON for piping

design-md diff DESIGN.md updated.md --format=json | jq '.colors.modified'

JSON output:

{
  "colors": {
    "added": {
      "surface-alt": "#f0f2f5"
    },
    "removed": {
      "border-light": "#e6ebf1"
    },
    "modified": {
      "primary": {
        "from": "#635bff",
        "to": "#5b50ff"
      }
    }
  },
  "radii": {
    "added": {},
    "removed": {},
    "modified": {}
  },
  "typography": {
    "added": {},
    "removed": {},
    "modified": {
      "body.size": {
        "from": "16px",
        "to": "15px"
      }
    }
  },
  "spacing": {
    "added": {},
    "removed": {},
    "modified": {}
  },
  "components": {
    "added": {},
    "removed": {},
    "modified": {}
  }
}

Use in CI to validate token updates

# Check if a PR changes more than spacing
design-md diff main.md feature.md --format=json | jq '
  if (.colors.modified | length) > 0 or
     (.typography.modified | length) > 0
  then "Colors or typography changed — review required"
  else "Only spacing changed — auto-approve"
  end
'

Output

Text format

Terminal output is colored by category and change type:

Green + — token added in 
Red − — token removed (exists in <a>, not in )
Yellow ~ — token modified (value changed between <a> and )

Each token shows its value or, for modified tokens, the from → to transition. Unchanged sections print “no changes”.

JSON format

Structured output with nested added, removed, and modified objects for each category:

added — keys that exist in  but not in <a>
removed — keys that exist in <a> but not in 
modified — keys in both, with { from, to } pairs showing the value change

Both formats exit with status code 0 on success, regardless of whether changes were found.

lint — validate a DESIGN.md against the schema
export — convert tokens to Tailwind, CSS vars, DTCG, or Figma JSON
add — fetch a brand’s DESIGN.md from the catalog