Sibling contract

Compare

Compare is the diff engine: fetch two URLs, extract their :root token systems, and produce a structured diff. "What actually changed between our old token system and the new one?" — answered deterministically from live production URLs, not from file uploads. Also serves as the diff engine inside /monitor (m08 token-set mutation).

Version 0.1.0 · provisional · machine export

Source authority

Primary source

Designesy design intelligence research 2026-08-02

File-level diff

Adobe token-diff-generator v2.5.3 — detects added/deleted/renamed/deprecated/updated across schema versions

Hosted diff

Tokens Studio diff + codemod — upload two token files, get a diff + ast-grep migration

Slug-level diff

designlang diff_designs MCP tool — compares two DESIGN.md brand slugs at the color-token level

URL gap

No competitor fetches two live URLs, extracts their token contracts, and diffs the contracts — the designesy pattern

Diff method

How it works

Fetch both URLs, extract all CSS + :root custom properties from each. Parse token names and values. Compare the two token maps: tokens present in A but not B (added), present in B but not A (removed), present in both with different values (value-changed). Heuristic rename detection: tokens with similar names (Levenshtein distance ≤ 2) and different values are flagged as potential renames. Scale analysis: compare the distinct value sets for spacing, radius, and color to detect scale-stop changes. Optionally run /score on both URLs to compute a score delta.

Diff dimensions

01token addedTokens present in URL A but not in URL B — new tokens introduced

02token removedTokens present in URL B but not in URL A — tokens deleted

03token renamedTokens with similar names (Levenshtein ≤ 2) but different values — heuristic rename detection

04token value changedSame token name, different value between A and B — the core drift signal

05scale stop changedSpacing/radius/color scale steps added or removed — the system grew or shrank

06contrast drift per pairFor color tokens present in both: did the contrast ratio against a reference background change?

07structure deltaToken count, category distribution, and naming convention changes — structural health of the system

08score deltaIf /score is run on both URLs: the score and grade difference between the two sites

Verification

8 checks — 8 checks. PASS=1, WARN=0.5, FAIL=0. Score = (points/8) × 100. A≥90, B≥80, C≥70, D≥60, F<60. Note: the compare score reflects diff completeness (did the engine produce a full diff), not design quality — design quality is the /score surface. The diff result itself is the product; the score is secondary.

01c01 · Both URLs fetched — HTML + CSS extracted from both targetsPASS: Both URLs fetched successfully with CSS content · FAIL: One or both URLs could not be fetched — check accessibility

02c02 · Token extraction — :root custom properties captured from bothPASS: Tokens extracted from both URLs (A: N, B: M) · FAIL: No :root custom properties found in one or both URLs — nothing to compare · WARN: One URL has significantly fewer tokens than the other — may indicate an incomplete token system

03c03 · Token-set diff computed — added, removed, value-changedPASS: Diff computed: N added, M removed, K value-changed · FAIL: Could not compute diff — token maps are empty or malformed

04c04 · Rename detection — heuristic name-similarity matchingPASS: Rename candidates identified (or no renames detected) · FAIL: Rename detection failed — token name parsing error

05c05 · Scale diff — spacing/radius/color scale-stop comparisonPASS: Scale diff computed for spacing, radius, and color · FAIL: Could not compute scale diff — insufficient value data

06c06 · Structure delta — token count and category distributionPASS: Structure delta computed (count, categories, naming) · FAIL: Could not compute structure delta — token parsing incomplete

07c07 · Contrast drift — color pair contrast comparisonPASS: Contrast drift computed for shared color tokens · FAIL: No shared color tokens between A and B — cannot compute contrast drift · WARN: Few shared color tokens — contrast drift is partial

08c08 · Score delta — /score run on both URLs, delta computedPASS: Score delta computed (A: score, B: score, delta: diff) · FAIL: Could not run /score on one or both URLs · WARN: Score delta computed but one or both scores are low — diff may be less meaningful

Validation: Designesy compare engine — dual-URL fetch + token extraction + set diff + scale analysis. Method: Fetch both URLs, extract :root tokens, compute set diff (added/removed/renamed/value-changed), compare scales, run /score on both for score delta. Browser-only checks: None — all checks are static CSS analysis + set operations, no browser needed.

Open questions

Rename detection (c04) is heuristic — Levenshtein distance ≤ 2 may produce false positives for short token names
Contrast drift (c07) uses WCAG contrast ratio against a fixed reference background — teams with multiple themes need per-theme comparison
Score delta (c08) runs /score on both URLs, which doubles the fetch time — caching is essential
The diff does not detect semantic drift — same value but different role (e.g. --primary changed from blue to red but the role is still "primary")
Cross-origin token comparison may surface third-party CSS tokens (analytics, embeds) as part of the diff — a suppression list may be needed

Run it

Compare two URLs to see how their design systems differ:

Compare two URLs →API endpoint

The compare contract is the diff engine — it answers “what actually changed between two design systems” deterministically from live production URLs. Machine export.