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?" is answered deterministically from live production URLs instead of file uploads. Also serves as the diff engine inside /monitor (m08 token-set mutation).

Version 0.1.1 · provisional · machine export

View as Markdown

Source authority

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

Primary source: Designesy design intelligence research 2026-08-02

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

01 token added Tokens present in URL A but not in URL B: new tokens introduced added[]

02 token removed Tokens present in URL B but not in URL A: tokens deleted removed[]

03 token renamed Tokens with similar names (Levenshtein ≤ 2) but different values: heuristic rename detection renamed[]

04 token value changed Same token name, different value between A and B: the core drift indicator valueChanged[]

05 scale stop changed Spacing/radius/color scale steps added or removed: the system grew or shrank scaleDiff

06 contrast drift per pair For color tokens present in both: did the contrast ratio against a reference background change? contrastDrift[]

07 structure delta Token count, category distribution, and naming convention changes: structural health of the system structureDelta

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

Verification

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) rather than design quality, which is the /score surface. The diff result itself is the product; the score is secondary.

01 c01 · Both URLs fetched: HTML + CSS extracted from both targets Pass Both URLs fetched successfully with CSS content Fail One or both URLs could not be fetched (check accessibility)

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

03 c03 · Token-set diff computed: added, removed, value-changed Pass Diff computed: N added, M removed, K value-changed Fail Could not compute diff (token maps are empty or malformed)

04 c04 · Rename detection: heuristic name-similarity matching Pass Rename candidates identified (or no renames detected) Fail Rename detection failed (token name parsing error)

05 c05 · Scale diff: spacing/radius/color scale-stop comparison Pass Scale diff computed for spacing, radius, and color Fail Could not compute scale diff (insufficient value data)

06 c06 · Structure delta: token count and category distribution Pass Structure delta computed (count, categories, naming) Fail Could not compute structure delta (token parsing incomplete)

07 c07 · Contrast drift: color pair contrast comparison Pass Contrast drift computed for shared color tokens Warn Few shared color tokens (contrast drift is partial) Fail No shared color tokens between A and B (cannot compute contrast drift)

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

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.