ui-mirror-skill 1.0.0

package/skill/scripts/compare_tokens.py

@@ -0,0 +1,741 @@
+#!/usr/bin/env python3
+"""
+compare_tokens.py — Produce a structured diff between benchmark and current project design tokens.
+
+Usage:
+    python3 compare_tokens.py <benchmark_tokens.json> <current_tokens.json> [--format human]
+
+Input:  Two normalized token JSON files (output of extract_design_tokens.py)
+Output: Structured diff JSON to stdout (default), or human-readable text (--format human).
+
+Dependencies: Python 3 standard library only.
+"""
+
+import json
+import math
+import re
+import sys
+
+
+# ---------------------------------------------------------------------------
+# 1. OKLCH parsing and deltaE calculation
+# ---------------------------------------------------------------------------
+
+_OKLCH_RE = re.compile(
+    r"oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*\)"
+)
+
+
+def parse_oklch(s: str):
+    """Parse 'oklch(L C H)' string into (L, C, H) tuple, or None."""
+    if not s:
+        return None
+    m = _OKLCH_RE.search(s)
+    if m:
+        return float(m.group(1)), float(m.group(2)), float(m.group(3))
+    return None
+
+
+def oklch_delta_e(a_str: str, b_str: str) -> float | None:
+    """
+    Compute perceptual color difference using simplified Oklab Euclidean distance.
+
+    We convert OKLCH back to Oklab (L, a, b) and compute Euclidean distance.
+    This is a standard simplified deltaE for Oklab.
+    """
+    a = parse_oklch(a_str)
+    b = parse_oklch(b_str)
+    if a is None or b is None:
+        return None
+
+    L1, C1, H1 = a
+    L2, C2, H2 = b
+
+    # OKLCH → Oklab
+    a1 = C1 * math.cos(math.radians(H1))
+    b1 = C1 * math.sin(math.radians(H1))
+    a2 = C2 * math.cos(math.radians(H2))
+    b2 = C2 * math.sin(math.radians(H2))
+
+    dL = L1 - L2
+    da = a1 - a2
+    db = b1 - b2
+
+    return math.sqrt(dL * dL + da * da + db * db)
+
+
+def classify_delta(delta_e: float) -> str:
+    """Classify a color deltaE into match/close/different."""
+    if delta_e < 0.02:
+        return "match"
+    if delta_e <= 0.1:
+        return "close"
+    return "different"
+
+
+# ---------------------------------------------------------------------------
+# 2. FRONTEND_CONSISTENCY.md conflict rules
+# ---------------------------------------------------------------------------
+
+# Rules we can detect conflicts for from token values
+RULES = {
+    "R4": {
+        "description": "rounded-xl 이상 사용 금지",
+        "check_field": "radius",
+        "max_px": 8,
+        "max_tailwind": "lg",
+    },
+    "C2": {
+        "description": "라이트모드 전용 — dark: 접두사 금지",
+        "check_field": "colors",
+        "detect": "dark_mode",
+    },
+    "A1": {
+        "description": "tw-animate-css만 사용 — framer-motion 금지",
+        "check_field": "animations",
+        "detect": "complex_animation",
+    },
+    "T2": {
+        "description": "Tailwind 크기 스케일만 사용 (xs~4xl)",
+        "check_field": "typography",
+        "valid_sizes": {"xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"},
+    },
+}
+
+VIOLATING_RADIUS_TAILWIND = {"xl", "2xl", "3xl", "full"}
+
+
+def check_radius_conflict(benchmark_tokens: dict) -> list:
+    """Check if benchmark has border-radius > 8px (rounded-lg), violating R4."""
+    conflicts = []
+    radius = benchmark_tokens.get("radius", {})
+    for name, entry in radius.items():
+        if isinstance(entry, dict):
+            px_val = entry.get("px")
+            tw_val = entry.get("tailwind", "")
+            if px_val is not None and px_val > 8:
+                conflicts.append({
+                    "ruleId": "R4",
+                    "rule": "rounded-xl+ 사용 금지",
+                    "benchmarkValue": "rounded-{} ({}px)".format(tw_val, int(px_val)),
+                    "component": name,
+                    "resolution": "Clamp to rounded-lg (8px) or update R4 to allow rounded-{} for {}".format(
+                        tw_val, name
+                    ),
+                })
+            elif tw_val in VIOLATING_RADIUS_TAILWIND:
+                conflicts.append({
+                    "ruleId": "R4",
+                    "rule": "rounded-xl+ 사용 금지",
+                    "benchmarkValue": "rounded-{}".format(tw_val),
+                    "component": name,
+                    "resolution": "Clamp to rounded-lg or update R4 to allow rounded-{} for {}".format(
+                        tw_val, name
+                    ),
+                })
+    return conflicts
+
+
+def check_typography_conflict(benchmark_tokens: dict) -> list:
+    """Check if benchmark uses non-standard font sizes, violating T2."""
+    conflicts = []
+    valid = RULES["T2"]["valid_sizes"]
+    typography = benchmark_tokens.get("typography", {})
+    for name, entry in typography.items():
+        if isinstance(entry, dict):
+            size = entry.get("size", "")
+            if size and size not in valid:
+                conflicts.append({
+                    "ruleId": "T2",
+                    "rule": "Tailwind 크기 스케일만 사용 (xs~4xl)",
+                    "benchmarkValue": "text-{} (in {})".format(size, name),
+                    "resolution": "Map to nearest standard size or update T2 to allow text-{}".format(size),
+                })
+    return conflicts
+
+
+# ---------------------------------------------------------------------------
+# 3. Token comparison logic
+# ---------------------------------------------------------------------------
+
+def compare_colors(bench_colors: dict, current_colors: dict) -> dict:
+    """Compare color tokens between benchmark and current project."""
+    result = {"match": [], "modify": [], "add": []}
+
+    all_names = set(list(bench_colors.keys()) + list(current_colors.keys()))
+
+    for name in sorted(all_names):
+        bench_val = bench_colors.get(name)
+        current_val = current_colors.get(name)
+
+        if bench_val and current_val:
+            # Both exist — compare
+            b_oklch = bench_val.get("oklch", "") if isinstance(bench_val, dict) else ""
+            s_oklch = current_val.get("oklch", "") if isinstance(current_val, dict) else ""
+
+            delta = oklch_delta_e(b_oklch, s_oklch)
+            entry = {
+                "name": name,
+                "benchmark": b_oklch or str(bench_val),
+                "current": s_oklch or str(current_val),
+                "deltaE": round(delta, 4) if delta is not None else None,
+            }
+
+            if delta is not None and delta < 0.02:
+                result["match"].append(entry)
+            else:
+                entry["action"] = "Update --{} in globals.css".format(name)
+                if delta is not None:
+                    entry["classification"] = classify_delta(delta)
+                result["modify"].append(entry)
+
+        elif bench_val and not current_val:
+            b_oklch = bench_val.get("oklch", "") if isinstance(bench_val, dict) else str(bench_val)
+            result["add"].append({
+                "name": name,
+                "benchmark": b_oklch,
+                "action": "Add new --mirror-{} token".format(name),
+            })
+        # current-only tokens are informational — we skip them in the diff
+        # (they exist in current but not in benchmark, no action needed)
+
+    return result
+
+
+def compare_simple_category(bench_data: dict, current_data: dict, category_name: str) -> dict:
+    """Compare simple dict-of-dict token categories (spacing, radius, shadows, layout)."""
+    result = {"match": [], "modify": [], "add": []}
+
+    all_keys = set(list(bench_data.keys()) + list(current_data.keys()))
+
+    for key in sorted(all_keys):
+        bench_val = bench_data.get(key)
+        current_val = current_data.get(key)
+
+        if bench_val is not None and current_val is not None:
+            # Both exist
+            if _values_match(bench_val, current_val):
+                result["match"].append({
+                    "name": key,
+                    "benchmark": _summarize_value(bench_val),
+                    "current": _summarize_value(current_val),
+                })
+            else:
+                result["modify"].append({
+                    "name": key,
+                    "benchmark": _summarize_value(bench_val),
+                    "current": _summarize_value(current_val),
+                    "action": "Update {} {}".format(category_name, key),
+                })
+
+        elif bench_val is not None and current_val is None:
+            result["add"].append({
+                "name": key,
+                "benchmark": _summarize_value(bench_val),
+                "action": "Add {} {}".format(category_name, key),
+            })
+
+    return result
+
+
+def compare_typography(bench_typo: dict, current_typo: dict) -> dict:
+    """Compare typography tokens with detailed field-level diff."""
+    result = {"match": [], "modify": [], "add": []}
+
+    all_keys = set(list(bench_typo.keys()) + list(current_typo.keys()))
+
+    for key in sorted(all_keys):
+        bench_val = bench_typo.get(key)
+        current_val = current_typo.get(key)
+
+        if bench_val is not None and current_val is not None:
+            if isinstance(bench_val, dict) and isinstance(current_val, dict):
+                diffs = {}
+                for field in set(list(bench_val.keys()) + list(current_val.keys())):
+                    bv = bench_val.get(field)
+                    sv = current_val.get(field)
+                    if bv != sv:
+                        diffs[field] = {"benchmark": bv, "current": sv}
+
+                if not diffs:
+                    result["match"].append({
+                        "name": key,
+                        "benchmark": bench_val,
+                        "current": current_val,
+                    })
+                else:
+                    result["modify"].append({
+                        "name": key,
+                        "diffs": diffs,
+                        "action": "Update typography for {}".format(key),
+                    })
+            else:
+                if bench_val == current_val:
+                    result["match"].append({"name": key, "value": bench_val})
+                else:
+                    result["modify"].append({
+                        "name": key,
+                        "benchmark": bench_val,
+                        "current": current_val,
+                        "action": "Update typography {}".format(key),
+                    })
+
+        elif bench_val is not None:
+            result["add"].append({
+                "name": key,
+                "benchmark": bench_val,
+                "action": "Add typography definition for {}".format(key),
+            })
+
+    return result
+
+
+def compare_components(bench_comp: dict, current_comp: dict) -> dict:
+    """Compare component tokens."""
+    result = {"match": [], "modify": [], "add": []}
+
+    all_keys = set(list(bench_comp.keys()) + list(current_comp.keys()))
+
+    for key in sorted(all_keys):
+        bench_val = bench_comp.get(key)
+        current_val = current_comp.get(key)
+
+        if bench_val is not None and current_val is not None:
+            if _values_match(bench_val, current_val):
+                result["match"].append({"name": key})
+            else:
+                diffs = _diff_dicts(bench_val, current_val) if isinstance(bench_val, dict) and isinstance(current_val, dict) else {"benchmark": bench_val, "current": current_val}
+                result["modify"].append({
+                    "name": key,
+                    "diffs": diffs,
+                    "action": "Update component {}".format(key),
+                })
+        elif bench_val is not None:
+            result["add"].append({
+                "name": key,
+                "benchmark": _summarize_value(bench_val),
+                "action": "Add component definition for {}".format(key),
+            })
+
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 4. Helpers
+# ---------------------------------------------------------------------------
+
+def _values_match(a, b) -> bool:
+    """Check if two token values are effectively identical."""
+    if a == b:
+        return True
+    if isinstance(a, dict) and isinstance(b, dict):
+        # Compare tailwind values if both have them
+        if "tailwind" in a and "tailwind" in b:
+            return a["tailwind"] == b["tailwind"]
+        # Compare all shared keys
+        shared = set(a.keys()) & set(b.keys())
+        if shared:
+            return all(a[k] == b[k] for k in shared)
+    return False
+
+
+def _summarize_value(v):
+    """Produce a compact summary of a token value."""
+    if isinstance(v, dict):
+        # Prefer tailwind representation
+        if "tailwind" in v:
+            return v["tailwind"]
+        if "oklch" in v:
+            return v["oklch"]
+        return v
+    return v
+
+
+def _diff_dicts(a: dict, b: dict) -> dict:
+    """Return fields that differ between two dicts."""
+    result = {}
+    all_keys = set(list(a.keys()) + list(b.keys()))
+    for k in sorted(all_keys):
+        av = a.get(k)
+        bv = b.get(k)
+        if av != bv:
+            result[k] = {"benchmark": av, "current": bv}
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 5. Main comparison logic
+# ---------------------------------------------------------------------------
+
+def compare_tokens(benchmark: dict, current: dict) -> dict:
+    """Produce a full structured diff between benchmark and current project tokens."""
+
+    categories = ["colors", "typography", "spacing", "radius", "shadows", "components", "layout"]
+
+    diff = {
+        "summary": {"total": 0, "match": 0, "modify": 0, "add": 0, "conflicts": 0},
+    }
+
+    # Compare each category
+    bench_colors = benchmark.get("colors", {})
+    current_colors = current.get("colors", {})
+    diff["colors"] = compare_colors(bench_colors, current_colors)
+
+    bench_typo = benchmark.get("typography", {})
+    current_typo = current.get("typography", {})
+    diff["typography"] = compare_typography(bench_typo, current_typo)
+
+    bench_spacing = benchmark.get("spacing", {})
+    current_spacing = current.get("spacing", {})
+    diff["spacing"] = compare_simple_category(bench_spacing, current_spacing, "spacing")
+
+    bench_radius = benchmark.get("radius", {})
+    current_radius = current.get("radius", {})
+    diff["radius"] = compare_simple_category(bench_radius, current_radius, "radius")
+
+    bench_shadows = benchmark.get("shadows", {})
+    current_shadows = current.get("shadows", {})
+    diff["shadows"] = compare_simple_category(bench_shadows, current_shadows, "shadows")
+
+    bench_comp = benchmark.get("components", {})
+    current_comp = current.get("components", {})
+    diff["components"] = compare_components(bench_comp, current_comp)
+
+    bench_layout = benchmark.get("layout", {})
+    current_layout = current.get("layout", {})
+    diff["layout"] = compare_simple_category(bench_layout, current_layout, "layout")
+
+    # Detect conflicts with FRONTEND_CONSISTENCY.md
+    conflicts = []
+    conflicts.extend(check_radius_conflict(benchmark))
+    conflicts.extend(check_typography_conflict(benchmark))
+    diff["conflicts"] = conflicts
+
+    # Compute summary
+    total = 0
+    match_count = 0
+    modify_count = 0
+    add_count = 0
+
+    for cat in categories:
+        cat_data = diff.get(cat, {})
+        if isinstance(cat_data, dict) and "match" in cat_data:
+            match_count += len(cat_data.get("match", []))
+            modify_count += len(cat_data.get("modify", []))
+            add_count += len(cat_data.get("add", []))
+
+    total = match_count + modify_count + add_count
+
+    diff["summary"] = {
+        "total": total,
+        "match": match_count,
+        "modify": modify_count,
+        "add": add_count,
+        "conflicts": len(conflicts),
+    }
+
+    return diff
+
+
+# ---------------------------------------------------------------------------
+# 6. Human-readable formatting
+# ---------------------------------------------------------------------------
+
+CATEGORY_LABELS = {
+    "colors": "Colors",
+    "typography": "Typography",
+    "spacing": "Spacing",
+    "radius": "Radius",
+    "shadows": "Shadows",
+    "components": "Components",
+    "layout": "Layout",
+}
+
+
+def _fmt_value(v) -> str:
+    """Format a token value for display."""
+    if v is None:
+        return "(none)"
+    if isinstance(v, dict):
+        parts = []
+        for pref in ("oklch", "tailwind", "hex", "px", "value"):
+            if pref in v:
+                parts.append(str(v[pref]))
+        if parts:
+            return " / ".join(parts)
+        # Fallback: compact key=value pairs
+        return ", ".join("{}={}".format(k, v2) for k, v2 in sorted(v.items()) if v2 is not None)
+    return str(v)
+
+
+def _fmt_diff_field(field: str, bench, current) -> str:
+    """Format a single differing field as a line."""
+    bv = _fmt_value(bench) if not isinstance(bench, str) else bench
+    sv = _fmt_value(current) if not isinstance(current, str) else current
+    return "  {} {:<18s} {} -> {}".format("|", field + ":", bv, sv)
+
+
+def _fmt_color_entry(entry: dict, kind: str) -> list:
+    """Format a color diff entry."""
+    lines = []
+    name = entry.get("name", "?")
+    if kind == "match":
+        bench = entry.get("benchmark", entry.get("current", ""))
+        lines.append("  {} MATCH   {:<20s} {}".format(chr(0x2713), name, bench))
+    elif kind == "modify":
+        bench = entry.get("benchmark", "")
+        current = entry.get("current", "")
+        delta = entry.get("deltaE")
+        cls = entry.get("classification", "")
+        delta_str = "  dE={:.4f} ({})".format(delta, cls) if delta is not None else ""
+        lines.append("  {} MODIFY  {}".format(chr(0x270E), name))
+        lines.append("  |   benchmark: {}".format(bench))
+        lines.append("  |   current:   {}".format(current))
+        if delta_str:
+            lines.append("  |   delta:     {}".format(delta_str.strip()))
+    elif kind == "add":
+        bench = entry.get("benchmark", "")
+        lines.append("  {} ADD     {:<20s} {}".format(chr(0x271A), name, bench))
+    return lines
+
+
+def _fmt_simple_entry(entry: dict, kind: str) -> list:
+    """Format a simple category entry (spacing, radius, shadows, layout)."""
+    lines = []
+    name = entry.get("name", "?")
+    if kind == "match":
+        val = _fmt_value(entry.get("benchmark", entry.get("current", entry.get("value", ""))))
+        lines.append("  {} MATCH   {:<20s} {}".format(chr(0x2713), name, val))
+    elif kind == "modify":
+        bench = _fmt_value(entry.get("benchmark", ""))
+        current = _fmt_value(entry.get("current", ""))
+        lines.append("  {} MODIFY  {}".format(chr(0x270E), name))
+        lines.append("  |   benchmark: {}".format(bench))
+        lines.append("  |   current:   {}".format(current))
+    elif kind == "add":
+        bench = _fmt_value(entry.get("benchmark", ""))
+        lines.append("  {} ADD     {:<20s} {}".format(chr(0x271A), name, bench))
+    return lines
+
+
+def _fmt_typo_entry(entry: dict, kind: str) -> list:
+    """Format a typography entry with field-level diffs."""
+    lines = []
+    name = entry.get("name", "?")
+    if kind == "match":
+        lines.append("  {} MATCH   {}".format(chr(0x2713), name))
+    elif kind == "modify":
+        lines.append("  {} MODIFY  {}".format(chr(0x270E), name))
+        diffs = entry.get("diffs", {})
+        if isinstance(diffs, dict) and all(isinstance(v, dict) for v in diffs.values()):
+            for field, vals in sorted(diffs.items()):
+                bv = vals.get("benchmark", "(none)")
+                sv = vals.get("current", "(none)")
+                lines.append(_fmt_diff_field(field, bv, sv))
+        else:
+            bench = _fmt_value(entry.get("benchmark", ""))
+            current = _fmt_value(entry.get("current", ""))
+            lines.append("  |   benchmark: {}".format(bench))
+            lines.append("  |   current:   {}".format(current))
+    elif kind == "add":
+        bench = _fmt_value(entry.get("benchmark", ""))
+        lines.append("  {} ADD     {:<20s} {}".format(chr(0x271A), name, bench))
+    return lines
+
+
+def _fmt_component_entry(entry: dict, kind: str) -> list:
+    """Format a component entry with detailed field-by-field diffs."""
+    lines = []
+    name = entry.get("name", "?")
+    if kind == "match":
+        lines.append("  {} MATCH   {}".format(chr(0x2713), name))
+    elif kind == "modify":
+        lines.append("  {} MODIFY  {}".format(chr(0x270E), name))
+        diffs = entry.get("diffs", {})
+        if isinstance(diffs, dict):
+            for field, vals in sorted(diffs.items()):
+                if isinstance(vals, dict) and "benchmark" in vals and "current" in vals:
+                    bv = _fmt_value(vals["benchmark"])
+                    sv = _fmt_value(vals["current"])
+                    lines.append(_fmt_diff_field(field, bv, sv))
+                elif isinstance(vals, dict):
+                    # Nested dict — flatten one more level
+                    for subfield, subvals in sorted(vals.items()):
+                        if isinstance(subvals, dict) and "benchmark" in subvals:
+                            bv = _fmt_value(subvals["benchmark"])
+                            sv = _fmt_value(subvals.get("current", "(none)"))
+                            lines.append(_fmt_diff_field("{}.{}".format(field, subfield), bv, sv))
+                        else:
+                            lines.append("  |   {}.{}: {}".format(field, subfield, _fmt_value(subvals)))
+                else:
+                    lines.append("  |   {}: {}".format(field, _fmt_value(vals)))
+        else:
+            bench = _fmt_value(entry.get("benchmark", ""))
+            current = _fmt_value(entry.get("current", ""))
+            lines.append("  |   benchmark: {}".format(bench))
+            lines.append("  |   current:   {}".format(current))
+    elif kind == "add":
+        bench = _fmt_value(entry.get("benchmark", ""))
+        lines.append("  {} ADD     {:<20s} {}".format(chr(0x271A), name, bench))
+    return lines
+
+
+def format_human_readable(diff: dict) -> str:
+    """Format the full diff as human-readable text output."""
+    lines = []
+
+    # Summary header
+    summary = diff.get("summary", {})
+    lines.append("=" * 70)
+    lines.append("  DESIGN TOKEN COMPARISON")
+    lines.append("=" * 70)
+    lines.append("")
+    lines.append("  Total: {} | Match: {} | Modify: {} | Add: {} | Conflicts: {}".format(
+        summary.get("total", 0),
+        summary.get("match", 0),
+        summary.get("modify", 0),
+        summary.get("add", 0),
+        summary.get("conflicts", 0),
+    ))
+    lines.append("")
+
+    # Category formatters
+    formatters = {
+        "colors": _fmt_color_entry,
+        "typography": _fmt_typo_entry,
+        "spacing": _fmt_simple_entry,
+        "radius": _fmt_simple_entry,
+        "shadows": _fmt_simple_entry,
+        "components": _fmt_component_entry,
+        "layout": _fmt_simple_entry,
+    }
+
+    for cat_key in ["colors", "typography", "spacing", "radius", "shadows", "components", "layout"]:
+        cat_data = diff.get(cat_key)
+        if not cat_data or not isinstance(cat_data, dict):
+            continue
+
+        match_list = cat_data.get("match", [])
+        modify_list = cat_data.get("modify", [])
+        add_list = cat_data.get("add", [])
+
+        if not match_list and not modify_list and not add_list:
+            continue
+
+        label = CATEGORY_LABELS.get(cat_key, cat_key)
+        lines.append("{} {} (match: {} | modify: {} | add: {}) {}".format(
+            chr(0x2500) * 2,
+            label,
+            len(match_list),
+            len(modify_list),
+            len(add_list),
+            chr(0x2500) * 2,
+        ))
+        lines.append("")
+
+        fmt_fn = formatters.get(cat_key, _fmt_simple_entry)
+
+        for entry in match_list:
+            lines.extend(fmt_fn(entry, "match"))
+        if match_list and (modify_list or add_list):
+            lines.append("")
+        for entry in modify_list:
+            lines.extend(fmt_fn(entry, "modify"))
+            lines.append("")
+        for entry in add_list:
+            lines.extend(fmt_fn(entry, "add"))
+
+        lines.append("")
+
+    # Conflicts section
+    conflicts = diff.get("conflicts", [])
+    if conflicts:
+        lines.append("{} Conflicts ({}) {}".format(chr(0x2500) * 2, len(conflicts), chr(0x2500) * 2))
+        lines.append("")
+        for c in conflicts:
+            rule_id = c.get("ruleId", "?")
+            rule = c.get("rule", "")
+            component = c.get("component", "")
+            bench_val = c.get("benchmarkValue", "")
+            resolution = c.get("resolution", "")
+            lines.append("  {} [{}] {}".format(chr(0x26A0), rule_id, rule))
+            if component:
+                lines.append("  |   component:  {}".format(component))
+            lines.append("  |   benchmark:  {}".format(bench_val))
+            lines.append("  |   resolution: {}".format(resolution))
+            lines.append("")
+
+    lines.append("=" * 70)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# 7. Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    # Parse args: <benchmark> <current> [--format human]
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    flags = [a for a in sys.argv[1:] if a.startswith("--")]
+
+    output_format = "json"
+    for i, flag in enumerate(flags):
+        if flag == "--format" and i + 1 < len(flags):
+            output_format = flags[i + 1]
+            break
+    # Also check sys.argv directly for --format human
+    for i, a in enumerate(sys.argv[1:], 1):
+        if a == "--format" and i + 1 < len(sys.argv):
+            output_format = sys.argv[i + 1]
+
+    if len(args) < 2:
+        print(
+            "Usage: {} <benchmark_tokens.json> <current_tokens.json> [--format human]".format(sys.argv[0]),
+            file=sys.stderr,
+        )
+        print("  Produces a structured diff between benchmark and current project design tokens.", file=sys.stderr)
+        print("  --format human  Output human-readable text instead of JSON", file=sys.stderr)
+        sys.exit(1)
+
+    benchmark_path = args[0]
+    current_path = args[1]
+
+    # Load benchmark
+    try:
+        with open(benchmark_path, "r", encoding="utf-8") as f:
+            benchmark = json.load(f)
+    except FileNotFoundError:
+        print("Error: Benchmark file not found: {}".format(benchmark_path), file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print("Error: Invalid JSON in benchmark {}: {}".format(benchmark_path, e), file=sys.stderr)
+        sys.exit(1)
+
+    # Load current
+    try:
+        with open(current_path, "r", encoding="utf-8") as f:
+            current = json.load(f)
+    except FileNotFoundError:
+        print("Error: Current project file not found: {}".format(current_path), file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print("Error: Invalid JSON in current {}: {}".format(current_path, e), file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(benchmark, dict):
+        print("Error: Benchmark JSON must be an object, got {}".format(type(benchmark).__name__), file=sys.stderr)
+        sys.exit(1)
+    if not isinstance(current, dict):
+        print("Error: Current JSON must be an object, got {}".format(type(current).__name__), file=sys.stderr)
+        sys.exit(1)
+
+    diff = compare_tokens(benchmark, current)
+
+    if output_format == "human":
+        print(format_human_readable(diff))
+    else:
+        print(json.dumps(diff, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()