ui-mirror-skill 1.0.0

package/skill/scripts/extract_design_tokens.py

@@ -0,0 +1,617 @@
+#!/usr/bin/env python3
+"""
+extract_design_tokens.py — Parse raw computed styles JSON into normalized design tokens.
+
+Usage:
+    python3 extract_design_tokens.py <input.json>
+
+Input:  JSON file with browser-extracted computed styles (body, headings, buttons, cards, etc.)
+Output: Normalized design tokens JSON to stdout.
+
+Dependencies: Python 3 standard library only.
+"""
+
+import json
+import math
+import re
+import sys
+from collections import OrderedDict
+
+
+# ---------------------------------------------------------------------------
+# 1. Color conversion: sRGB → linear RGB → XYZ → Oklab → OKLCH
+# ---------------------------------------------------------------------------
+
+def _srgb_transfer(c: float) -> float:
+    """Inverse sRGB companding: sRGB [0,1] → linear [0,1]."""
+    if c <= 0.04045:
+        return c / 12.92
+    return ((c + 0.055) / 1.055) ** 2.4
+
+
+def srgb_to_linear(r: float, g: float, b: float):
+    """Convert sRGB [0,255] to linear RGB [0,1]."""
+    return _srgb_transfer(r / 255.0), _srgb_transfer(g / 255.0), _srgb_transfer(b / 255.0)
+
+
+def linear_rgb_to_xyz(lr: float, lg: float, lb: float):
+    """Linear sRGB → CIE XYZ (D65) using the standard 3×3 matrix."""
+    x = 0.4124564 * lr + 0.3575761 * lg + 0.1804375 * lb
+    y = 0.2126729 * lr + 0.7151522 * lg + 0.0721750 * lb
+    z = 0.0193339 * lr + 0.1191920 * lg + 0.9503041 * lb
+    return x, y, z
+
+
+def xyz_to_oklab(x: float, y: float, z: float):
+    """CIE XYZ → Oklab via the Björn Ottosson method."""
+    # XYZ → LMS (using Ottosson's M1 matrix)
+    l_ = 0.8189330101 * x + 0.3618667424 * y - 0.1288597137 * z
+    m_ = 0.0329845436 * x + 0.9293118715 * y + 0.0361456387 * z
+    s_ = 0.0482003018 * x + 0.2643662691 * y + 0.6338517070 * z
+
+    # Cube root (handle negatives gracefully)
+    def cbrt(v):
+        if v >= 0:
+            return v ** (1.0 / 3.0)
+        return -((-v) ** (1.0 / 3.0))
+
+    l_c = cbrt(l_)
+    m_c = cbrt(m_)
+    s_c = cbrt(s_)
+
+    # LMS′ → Oklab (M2 matrix)
+    L = 0.2104542553 * l_c + 0.7936177850 * m_c - 0.0040720468 * s_c
+    a = 1.9779984951 * l_c - 2.4285922050 * m_c + 0.4505937099 * s_c
+    b = 0.0259040371 * l_c + 0.7827717662 * m_c - 0.8086757660 * s_c
+    return L, a, b
+
+
+def oklab_to_oklch(L: float, a: float, b: float):
+    """Oklab → OKLCH (Lightness, Chroma, Hue in degrees)."""
+    C = math.sqrt(a * a + b * b)
+    H = math.degrees(math.atan2(b, a)) % 360
+    return L, C, H
+
+
+def rgb_to_oklch(r: int, g: int, b: int):
+    """Full pipeline: sRGB [0,255] → OKLCH."""
+    lr, lg, lb = srgb_to_linear(r, g, b)
+    x, y, z = linear_rgb_to_xyz(lr, lg, lb)
+    L, a, ob = xyz_to_oklab(x, y, z)
+    return oklab_to_oklch(L, a, ob)
+
+
+def rgb_to_hex(r: int, g: int, b: int) -> str:
+    return "#{:02X}{:02X}{:02X}".format(r, g, b)
+
+
+def format_oklch(L: float, C: float, H: float) -> str:
+    return "oklch({:.3f} {:.3f} {:.1f})".format(L, C, H)
+
+
+# ---------------------------------------------------------------------------
+# 2. Parse CSS color strings
+# ---------------------------------------------------------------------------
+
+_RGB_RE = re.compile(
+    r"rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+)?\s*\)"
+)
+_HEX_RE = re.compile(r"#([0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})\b")
+
+
+def parse_rgb(s: str):
+    """Return (r, g, b) tuple from 'rgb(...)' or 'rgba(...)' string, or None."""
+    if not s:
+        return None
+    m = _RGB_RE.search(s)
+    if m:
+        return int(m.group(1)), int(m.group(2)), int(m.group(3))
+    m = _HEX_RE.search(s)
+    if m:
+        h = m.group(1)
+        if len(h) == 3:
+            h = h[0] * 2 + h[1] * 2 + h[2] * 2
+        return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+    return None
+
+
+def color_entry(rgb_str: str, tailwind_name: str = ""):
+    """Build a normalized color entry dict from an rgb string."""
+    parsed = parse_rgb(rgb_str)
+    if parsed is None:
+        return {"raw": rgb_str, "tailwind": tailwind_name}
+    r, g, b = parsed
+    L, C, H = rgb_to_oklch(r, g, b)
+    return {
+        "oklch": format_oklch(L, C, H),
+        "rgb": "rgb({},{},{})".format(r, g, b),
+        "hex": rgb_to_hex(r, g, b),
+        "tailwind": tailwind_name,
+    }
+
+
+# ---------------------------------------------------------------------------
+# 3. Tailwind mapping tables
+# ---------------------------------------------------------------------------
+
+FONT_SIZE_MAP = {
+    12: "xs", 13: "xs", 14: "sm", 15: "sm", 16: "base",
+    18: "lg", 20: "xl", 24: "2xl", 28: "2xl", 30: "3xl",
+    36: "4xl", 48: "5xl", 60: "6xl", 72: "7xl", 96: "8xl", 128: "9xl",
+}
+
+RADIUS_MAP = {
+    0: "none", 1: "sm", 2: "sm", 3: "DEFAULT", 4: "DEFAULT",
+    5: "md", 6: "md", 7: "lg", 8: "lg", 10: "xl", 12: "xl",
+    14: "2xl", 16: "2xl", 20: "3xl", 24: "3xl", 9999: "full",
+}
+
+MAX_WIDTH_MAP = {
+    320: "xs", 384: "sm", 448: "md", 512: "lg", 576: "xl",
+    672: "2xl", 768: "3xl", 896: "4xl", 1024: "5xl", 1152: "6xl",
+    1280: "7xl",
+}
+
+SPACING_MULTIPLES = [0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10,
+                     11, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56,
+                     60, 64, 72, 80, 96]
+
+
+def parse_px(s: str) -> float | None:
+    """Extract numeric px value from a CSS string like '16px'."""
+    if not s:
+        return None
+    m = re.search(r"([\d.]+)\s*px", str(s))
+    return float(m.group(1)) if m else None
+
+
+def px_to_tailwind_spacing(px_val: float) -> str:
+    """Map a px value to the nearest Tailwind spacing unit (4px = 1)."""
+    tw_unit = px_val / 4.0
+    best = min(SPACING_MULTIPLES, key=lambda v: abs(v - tw_unit))
+    # Tailwind uses integer-like labels: 0.5, 1, 1.5 etc.
+    if best == int(best):
+        return str(int(best))
+    return str(best)
+
+
+def px_to_tailwind_font_size(px_val: float) -> str:
+    rounded = round(px_val)
+    if rounded in FONT_SIZE_MAP:
+        return FONT_SIZE_MAP[rounded]
+    # Find nearest
+    closest = min(FONT_SIZE_MAP.keys(), key=lambda k: abs(k - rounded))
+    return FONT_SIZE_MAP[closest]
+
+
+def px_to_tailwind_radius(px_val: float) -> str:
+    rounded = round(px_val)
+    if rounded >= 9999:
+        return "full"
+    if rounded in RADIUS_MAP:
+        return RADIUS_MAP[rounded]
+    closest = min(RADIUS_MAP.keys(), key=lambda k: abs(k - rounded))
+    return RADIUS_MAP[closest]
+
+
+def px_to_tailwind_max_width(px_val: float) -> str:
+    rounded = round(px_val)
+    if rounded in MAX_WIDTH_MAP:
+        return MAX_WIDTH_MAP[rounded]
+    closest = min(MAX_WIDTH_MAP.keys(), key=lambda k: abs(k - rounded))
+    return MAX_WIDTH_MAP[closest]
+
+
+# ---------------------------------------------------------------------------
+# 4. Font family identification
+# ---------------------------------------------------------------------------
+
+GENERIC_FAMILIES = {
+    "serif", "sans-serif", "monospace", "cursive", "fantasy",
+    "system-ui", "ui-serif", "ui-sans-serif", "ui-monospace", "ui-rounded",
+    "math", "emoji", "fangsong",
+}
+
+# Well-known Google Fonts (non-exhaustive; covers common ones)
+GOOGLE_FONTS = {
+    "Inter", "Roboto", "Open Sans", "Lato", "Montserrat", "Poppins",
+    "Nunito", "Raleway", "Ubuntu", "Playfair Display", "Merriweather",
+    "Source Sans Pro", "Noto Sans", "Oswald", "Quicksand", "Pretendard",
+    "Noto Sans KR", "IBM Plex Sans", "DM Sans", "Manrope", "Outfit",
+    "Plus Jakarta Sans", "Space Grotesk", "Figtree", "Geist",
+}
+
+
+def identify_font(font_family_str: str) -> dict:
+    """Extract the first non-generic font name and identify if Google Font."""
+    if not font_family_str:
+        return {"name": "system-ui", "isGoogleFont": False}
+    parts = [p.strip().strip("'\"") for p in font_family_str.split(",")]
+    for part in parts:
+        lower = part.lower()
+        if lower not in {g.lower() for g in GENERIC_FAMILIES}:
+            is_google = any(part.lower() == gf.lower() for gf in GOOGLE_FONTS)
+            return {"name": part, "isGoogleFont": is_google}
+    return {"name": parts[0] if parts else "system-ui", "isGoogleFont": False}
+
+
+# ---------------------------------------------------------------------------
+# 5. Padding parsing (handles "8px 16px" shorthand)
+# ---------------------------------------------------------------------------
+
+def parse_padding(s: str) -> dict:
+    """Parse CSS padding shorthand into a dict with px and tailwind values."""
+    if not s:
+        return {}
+    px_values = re.findall(r"([\d.]+)\s*px", str(s))
+    if not px_values:
+        return {"raw": s}
+    nums = [float(v) for v in px_values]
+    # Use the first value as representative (vertical padding typically)
+    representative = nums[0]
+    return {
+        "raw": s,
+        "px": representative,
+        "tailwind": px_to_tailwind_spacing(representative),
+    }
+
+
+# ---------------------------------------------------------------------------
+# 6. Color clustering by usage context
+# ---------------------------------------------------------------------------
+
+def classify_color_role(context: str, rgb_tuple) -> str:
+    """Heuristic: assign a semantic role based on where the color was found."""
+    r, g, b = rgb_tuple
+    lightness = (0.299 * r + 0.587 * g + 0.114 * b) / 255.0
+
+    ctx = context.lower()
+
+    if "button" in ctx and "bg" in ctx:
+        return "primary"
+    if "button" in ctx and "color" in ctx:
+        return "primary-foreground"
+    if "body" in ctx and "bg" in ctx:
+        return "background"
+    if "body" in ctx and "color" in ctx:
+        return "foreground"
+    if "card" in ctx and "bg" in ctx:
+        return "card"
+    if "card" in ctx and "border" in ctx:
+        return "border"
+    if "nav" in ctx and "bg" in ctx:
+        return "card"  # nav bg is typically card-like
+    if "input" in ctx and "bg" in ctx:
+        return "input"
+    if "input" in ctx and "border" in ctx:
+        return "border"
+    if "heading" in ctx:
+        return "foreground"
+
+    # Fallback by lightness
+    if lightness > 0.9:
+        return "background"
+    if lightness < 0.2:
+        return "foreground"
+    if lightness < 0.5:
+        return "secondary"
+    return "muted"
+
+
+# ---------------------------------------------------------------------------
+# 7. Main extraction logic
+# ---------------------------------------------------------------------------
+
+def extract_tokens(data: dict) -> dict:
+    """Transform raw computed styles into normalized design tokens."""
+
+    tokens = {
+        "colors": {},
+        "typography": {},
+        "spacing": {},
+        "radius": {},
+        "shadows": {},
+        "components": {},
+        "layout": {},
+    }
+
+    # Track all extracted colors for clustering
+    all_colors = []  # [(role, rgb_str, rgb_tuple)]
+
+    # ---- Body ----
+    body = data.get("body", {})
+    if body:
+        body_bg = body.get("bg", "")
+        body_color = body.get("color", "")
+        body_font = body.get("fontFamily", "")
+        body_size = body.get("fontSize", "")
+        body_lh = body.get("lineHeight", "")
+
+        if body_bg:
+            parsed = parse_rgb(body_bg)
+            if parsed:
+                all_colors.append(("body.bg", body_bg, parsed))
+                tokens["colors"]["background"] = color_entry(body_bg, "background")
+
+        if body_color:
+            parsed = parse_rgb(body_color)
+            if parsed:
+                all_colors.append(("body.color", body_color, parsed))
+                tokens["colors"]["foreground"] = color_entry(body_color, "foreground")
+
+        font_info = identify_font(body_font)
+        size_px = parse_px(body_size)
+        tokens["typography"]["body"] = {
+            "family": font_info["name"],
+            "isGoogleFont": font_info["isGoogleFont"],
+            "size": px_to_tailwind_font_size(size_px) if size_px else "base",
+            "sizePx": size_px,
+            "weight": "400",
+            "lineHeight": body_lh or "1.5",
+        }
+
+    # ---- Headings ----
+    headings = data.get("headings", [])
+    for i, h in enumerate(headings):
+        tag = h.get("tag", "H{}".format(i + 1)).upper()
+        level = tag.replace("H", "") if tag.startswith("H") else str(i + 1)
+        key = "heading{}".format(level)
+
+        size_px = parse_px(h.get("fontSize", ""))
+        font_info = identify_font(h.get("fontFamily", ""))
+
+        tokens["typography"][key] = {
+            "family": font_info["name"],
+            "size": px_to_tailwind_font_size(size_px) if size_px else "base",
+            "sizePx": size_px,
+            "weight": h.get("fontWeight", "700"),
+            "lineHeight": h.get("lineHeight", "1.2"),
+            "letterSpacing": h.get("letterSpacing", "normal"),
+        }
+
+        heading_color = h.get("color", "")
+        if heading_color:
+            parsed = parse_rgb(heading_color)
+            if parsed:
+                all_colors.append(("heading.color", heading_color, parsed))
+
+        # Heading spacing
+        mb_px = parse_px(h.get("marginBottom", ""))
+        mt_px = parse_px(h.get("marginTop", ""))
+        if mb_px is not None:
+            tokens["spacing"]["heading{}_mb".format(level)] = {
+                "px": mb_px,
+                "tailwind": px_to_tailwind_spacing(mb_px),
+            }
+        if mt_px is not None:
+            tokens["spacing"]["heading{}_mt".format(level)] = {
+                "px": mt_px,
+                "tailwind": px_to_tailwind_spacing(mt_px),
+            }
+
+    # ---- Buttons ----
+    buttons = data.get("buttons", [])
+    button_variants = []
+    for i, btn in enumerate(buttons):
+        variant = {}
+        btn_bg = btn.get("bg", "")
+        btn_color = btn.get("color", "")
+
+        if btn_bg:
+            parsed = parse_rgb(btn_bg)
+            if parsed:
+                all_colors.append(("button.bg", btn_bg, parsed))
+                variant["bg"] = color_entry(btn_bg)
+                # First button bg is likely "primary"
+                if i == 0 and "primary" not in tokens["colors"]:
+                    tokens["colors"]["primary"] = color_entry(btn_bg, "primary")
+
+        if btn_color:
+            parsed = parse_rgb(btn_color)
+            if parsed:
+                all_colors.append(("button.color", btn_color, parsed))
+                variant["color"] = color_entry(btn_color)
+                if i == 0 and "primary-foreground" not in tokens["colors"]:
+                    tokens["colors"]["primary-foreground"] = color_entry(btn_color, "primary-foreground")
+
+        radius_px = parse_px(btn.get("borderRadius", ""))
+        if radius_px is not None:
+            variant["radius"] = {"px": radius_px, "tailwind": px_to_tailwind_radius(radius_px)}
+            tokens["radius"]["button"] = variant["radius"]
+
+        variant["padding"] = parse_padding(btn.get("padding", ""))
+
+        size_px = parse_px(btn.get("fontSize", ""))
+        if size_px:
+            variant["fontSize"] = px_to_tailwind_font_size(size_px)
+
+        variant["fontWeight"] = btn.get("fontWeight", "500")
+        variant["border"] = btn.get("border", "none")
+        variant["boxShadow"] = btn.get("boxShadow", "none")
+        variant["text"] = btn.get("text", "")
+
+        button_variants.append(variant)
+
+    if button_variants:
+        tokens["components"]["button"] = {"variants": button_variants}
+
+    # ---- Cards ----
+    cards = data.get("cards", [])
+    if cards:
+        card = cards[0]  # Use first card as canonical
+        card_bg = card.get("bg", "")
+        if card_bg:
+            parsed = parse_rgb(card_bg)
+            if parsed:
+                all_colors.append(("card.bg", card_bg, parsed))
+                tokens["colors"]["card"] = color_entry(card_bg, "card")
+
+        radius_px = parse_px(card.get("borderRadius", ""))
+        if radius_px is not None:
+            tokens["radius"]["card"] = {"px": radius_px, "tailwind": px_to_tailwind_radius(radius_px)}
+
+        padding = parse_padding(card.get("padding", ""))
+        if padding:
+            tokens["spacing"]["card_padding"] = padding if "px" in padding else padding
+
+        shadow = card.get("boxShadow", "")
+        if shadow:
+            tokens["shadows"]["card"] = shadow
+
+        border = card.get("border", "")
+        if border:
+            parsed_border_color = parse_rgb(border)
+            if parsed_border_color:
+                all_colors.append(("card.border", border, parsed_border_color))
+                tokens["colors"]["border"] = color_entry(
+                    "rgb({},{},{})".format(*parsed_border_color), "border"
+                )
+
+        tokens["components"]["card"] = {
+            "bg": tokens["colors"].get("card", {}).get("tailwind", "card"),
+            "radius": tokens["radius"].get("card", {}).get("tailwind", "lg"),
+            "padding": tokens["spacing"].get("card_padding", {}).get("tailwind", "4"),
+            "shadow": shadow,
+            "border": border,
+        }
+
+    # ---- Inputs ----
+    inputs = data.get("inputs", [])
+    if inputs:
+        inp = inputs[0]
+        inp_bg = inp.get("bg", "")
+        if inp_bg:
+            parsed = parse_rgb(inp_bg)
+            if parsed:
+                all_colors.append(("input.bg", inp_bg, parsed))
+                tokens["colors"]["input"] = color_entry(inp_bg, "input")
+
+        radius_px = parse_px(inp.get("borderRadius", ""))
+        if radius_px is not None:
+            tokens["radius"]["input"] = {"px": radius_px, "tailwind": px_to_tailwind_radius(radius_px)}
+
+        inp_border = inp.get("border", "")
+        if inp_border:
+            parsed_border = parse_rgb(inp_border)
+            if parsed_border:
+                all_colors.append(("input.border", inp_border, parsed_border))
+                if "border" not in tokens["colors"]:
+                    tokens["colors"]["border"] = color_entry(
+                        "rgb({},{},{})".format(*parsed_border), "border"
+                    )
+
+        tokens["components"]["input"] = {
+            "bg": tokens["colors"].get("input", {}).get("tailwind", "input"),
+            "radius": tokens["radius"].get("input", {}).get("tailwind", "md"),
+            "padding": parse_padding(inp.get("padding", "")),
+            "border": inp_border,
+            "fontSize": px_to_tailwind_font_size(parse_px(inp.get("fontSize", "14px")) or 14),
+        }
+
+    # ---- Nav ----
+    nav = data.get("nav", {})
+    if nav:
+        nav_bg = nav.get("bg", "")
+        if nav_bg:
+            parsed = parse_rgb(nav_bg)
+            if parsed:
+                all_colors.append(("nav.bg", nav_bg, parsed))
+
+        nav_shadow = nav.get("boxShadow", "")
+        if nav_shadow:
+            tokens["shadows"]["nav"] = nav_shadow
+
+        nav_border = nav.get("borderBottom", "")
+        if nav_border:
+            tokens["components"].setdefault("nav", {})["borderBottom"] = nav_border
+
+        height_px = parse_px(nav.get("height", ""))
+        if height_px is not None:
+            tokens["layout"]["navHeight"] = {
+                "px": height_px,
+                "tailwind": px_to_tailwind_spacing(height_px),
+            }
+
+        tokens["components"].setdefault("nav", {}).update({
+            "bg": nav_bg,
+            "position": nav.get("position", "sticky"),
+        })
+
+    # ---- Layout ----
+    layout = data.get("layout", {})
+    if layout:
+        max_width = layout.get("maxWidth", "")
+        mw_px = parse_px(max_width)
+        if mw_px is not None:
+            tokens["layout"]["maxWidth"] = {
+                "px": mw_px,
+                "tailwind": px_to_tailwind_max_width(mw_px),
+            }
+
+        grid_cols = layout.get("gridColumns", "")
+        if grid_cols:
+            tokens["layout"]["gridColumns"] = grid_cols
+
+    # ---- Explicit colors section ----
+    colors_section = data.get("colors", {})
+    if colors_section:
+        bgs = colors_section.get("backgrounds", [])
+        for c_str in bgs:
+            parsed = parse_rgb(c_str)
+            if parsed:
+                all_colors.append(("colors.bg", c_str, parsed))
+        txts = colors_section.get("texts", [])
+        for c_str in txts:
+            parsed = parse_rgb(c_str)
+            if parsed:
+                all_colors.append(("colors.text", c_str, parsed))
+
+    # ---- Color clustering for any remaining unclassified colors ----
+    seen_roles = set(tokens["colors"].keys())
+    for context, rgb_str, rgb_tuple in all_colors:
+        role = classify_color_role(context, rgb_tuple)
+        if role not in seen_roles:
+            tokens["colors"][role] = color_entry(rgb_str, role)
+            seen_roles.add(role)
+
+    # ---- Page padding (from body/layout heuristic) ----
+    # If we don't have explicit page padding, try to infer from cards
+    if "page_padding" not in tokens["spacing"]:
+        # Default project page padding is 24px (p-6)
+        tokens["spacing"]["page_padding"] = {"px": 24, "tailwind": "6"}
+
+    return tokens
+
+
+# ---------------------------------------------------------------------------
+# 8. Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: {} <input.json>".format(sys.argv[0]), file=sys.stderr)
+        print("  Parses raw computed styles JSON into normalized design tokens.", file=sys.stderr)
+        sys.exit(1)
+
+    input_path = sys.argv[1]
+
+    try:
+        with open(input_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        print("Error: File not found: {}".format(input_path), file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print("Error: Invalid JSON in {}: {}".format(input_path, e), file=sys.stderr)
+        sys.exit(1)
+
+    if not isinstance(data, dict):
+        print("Error: Expected top-level JSON object, got {}".format(type(data).__name__), file=sys.stderr)
+        sys.exit(1)
+
+    tokens = extract_tokens(data)
+    print(json.dumps(tokens, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()