Semantic Diffing
primitree diff matches variables and reports breaking changes.
primitree diff matches collections, modes, and variables by their Figma IDs. A string diff cannot distinguish a rename from a removal plus an addition.
Rename detection
The report identifies a rename when the same ID has a different name. It marks the change as breaking because consumers may use the old path.
Value changes
The report identifies a value change when the same variable ID has a different raw valuesByMode entry. It labels the row with the current collection and mode name.
Breaking vs non-breaking
Breaking (exit code 2 with --fail-on-breaking):
- Removed variables
- Renamed variables (path consumers may break)
- Variables moved between collections
- Variable type changes
- Removed or renamed collections
- Removed or renamed modes
Reported without a breaking flag:
- New variables
- New collections or modes
- Per-mode value changes
- Description changes
Markdown output
Markdown is the default. Write it to a file for a pull request description:
primitree diff main/variables.json pr/variables.json --out PR_BODY.md--out <file> writes the selected format to a file instead of standard output.
Use --json for machine-readable output:
primitree diff main/variables.json pr/variables.json --json --out diff.jsonMCP
The diff_tokens MCP tool accepts paths to an earlier and a later variables JSON file. It returns the same Markdown report.
Library API
diffVariables and formatDiffMarkdown live in @primitree/core. The normalizer converts supported input shapes before the comparison.