FirstCheck

agents/llm_agents.py

@@ -688,17 +688,8 @@ You are Agent 3 of 4 in the Design System Analysis pipeline.
 - Type Scale Standard Ratio: 10 points
 - Base Size Accessible: 15 points
 - Spacing Grid: 15 points
-- Color Count: 5 points
-- No Near-Duplicates: 5 points
-- Shadow System: 10 points (elevation hierarchy, consistency)
-
-## SHADOW SYSTEM BEST PRACTICES:
-- Use 3-6 elevation levels (xs, sm, md, lg, xl, 2xl)
-- Consistent Y-offset progression (shadows should grow with elevation)
-- Blur radius should increase with elevation (more blur = higher elevation)
-- Shadow colors should be neutral (black/gray with alpha) or brand-colored with low opacity
-- Avoid shadows with 0 blur (looks harsh/flat)
-- Avoid excessive blur (>32px for most use cases)"""
+- Color Count: 10 points
+- No Near-Duplicates: 10 points"""
 
     PROMPT_TEMPLATE = """Validate the following design tokens against best practices and prioritize fixes.
 
@@ -725,10 +716,6 @@ You are Agent 3 of 4 in the Design System Analysis pipeline.
 - Duplicates: {duplicates}
 - Near-Duplicates: {near_duplicates}
 
-### Shadow System
-- Total Shadows: {shadow_count}
-- Shadow Values: {shadow_values}
-
 ## BEST PRACTICES CHECKLIST (check each one)
 
 1. Type scale uses standard ratio (1.2, 1.25, 1.333, 1.5, 1.618)
@@ -738,7 +725,6 @@ You are Agent 3 of 4 in the Design System Analysis pipeline.
 5. Spacing uses consistent grid (4px or 8px base)
 6. Limited color palette (< 20 unique semantic colors)
 7. No near-duplicate colors (< 3 delta-E apart)
-8. Shadow system has consistent elevation hierarchy (blur/Y-offset increase together)
 
 ## YOUR TASK
 
@@ -758,8 +744,7 @@ You are Agent 3 of 4 in the Design System Analysis pipeline.
     "aa_compliance": {{"status": "...", "note": "..."}},
     "spacing_grid": {{"status": "...", "note": "..."}},
     "color_count": {{"status": "...", "note": "..."}},
-    "near_duplicates": {{"status": "...", "note": "..."}},
-    "shadow_system": {{"status": "...", "note": "Elevation hierarchy, blur consistency, color appropriateness"}}
+    "near_duplicates": {{"status": "...", "note": "..."}}
   }},
   "priority_fixes": [
     {{
@@ -788,47 +773,35 @@ Return ONLY valid JSON."""
     async def analyze(
         self,
         rule_engine_results: Any,
-        shadow_tokens: dict = None,
         log_callback: Callable = None,
     ) -> BestPracticesResult:
         """
         Validate against best practices.
-
+        
         Args:
             rule_engine_results: Results from rule engine
-            shadow_tokens: Shadow tokens dict {name: {value: "..."}}
             log_callback: Progress logging function
-
+            
         Returns:
             BestPracticesResult with validation
         """
         def log(msg: str):
             if log_callback:
                 log_callback(msg)
-
+        
         log("")
         log("   ✅ SENTINEL — Best Practices Validator (Qwen 72B)")
         log("   └─ Checking against design system standards...")
-
+        
         # Extract data from rule engine
         typo = rule_engine_results.typography
         spacing = rule_engine_results.spacing
         color_stats = rule_engine_results.color_stats
         accessibility = rule_engine_results.accessibility
-
+        
         failures = [a for a in accessibility if not a.passes_aa_normal]
         failing_colors_str = ", ".join([f"{a.hex_color} ({a.contrast_on_white:.1f}:1)" for a in failures[:5]])
-
-        # Format shadow data for the prompt
-        shadow_count = len(shadow_tokens) if shadow_tokens else 0
-        shadow_values_str = "None detected"
-        if shadow_tokens and shadow_count > 0:
-            shadow_list = []
-            for name, s in list(shadow_tokens.items())[:6]:
-                val = s.get("value", "") if isinstance(s, dict) else str(s)
-                shadow_list.append(f"{name}: {val[:50]}")
-            shadow_values_str = "; ".join(shadow_list)
-
+        
         prompt = self.PROMPT_TEMPLATE.format(
             type_ratio=f"{typo.detected_ratio:.3f}",
             type_consistent="consistent" if typo.is_consistent else f"inconsistent, variance={typo.variance:.2f}",
@@ -844,8 +817,6 @@ Return ONLY valid JSON."""
             unique_colors=color_stats.unique_count,
             duplicates=color_stats.duplicate_count,
             near_duplicates=len(color_stats.near_duplicates),
-            shadow_count=shadow_count,
-            shadow_values=shadow_values_str,
         )
         
         try:

app.py

@@ -391,10 +391,9 @@ async def extract_tokens(pages_data, progress=gr.Progress()):
                             confidence=Confidence.MEDIUM,
                         )
                         
-                        # Generate name based on color characteristics (not garbage like firecrawl.34)
-                        # This will be a fallback; semantic analysis may override later
-                        new_token.suggested_name = None  # Let consolidation generate proper name
-
+                        # Generate name
+                        new_token.suggested_name = f"color.firecrawl.{len(state.desktop_normalized.colors)}"
+                        
                         state.desktop_normalized.colors[hex_val] = new_token
                         new_colors_count += 1
                 
@@ -1224,11 +1223,8 @@ async def run_stage2_analysis_v2(
                 async def _run_sentinel():
                     """Run SENTINEL (Best Practices Validator) agent."""
                     try:
-                        # Get shadow tokens from desktop_dict for analysis
-                        shadow_tokens = desktop_dict.get("shadows", {})
                         result = await best_practices_agent.analyze(
                             rule_engine_results=rule_results,
-                            shadow_tokens=shadow_tokens,
                             log_callback=state.log,
                         )
                         if result:
@@ -2912,29 +2908,17 @@ def _get_radius_token_name(value_str, seen_names: dict = None) -> str:
     except (ValueError, TypeError):
         return "radius.md"
 
-    # Handle percentage values (e.g., "50%" for circular)
-    if "%" in str(value_str):
-        base_name = "radius.full"
-    # "none" is ONLY for exactly 0px
-    elif px == 0:
-        base_name = "radius.none"
-    elif px >= 9999:
-        # Large values (like 9999px) are essentially "full"
+    if "%" in str(value_str) or px >= 50:
         base_name = "radius.full"
     else:
-        # Semantic naming based on pixel ranges (inclusive both ends for clarity)
         mapping = [
-            (1, 1, "radius.xs"),      # 1px = xs
-            (2, 3, "radius.sm"),      # 2-3px = sm
-            (4, 7, "radius.md"),      # 4-7px = md
-            (8, 11, "radius.lg"),     # 8-11px = lg
-            (12, 19, "radius.xl"),    # 12-19px = xl
-            (20, 31, "radius.2xl"),   # 20-31px = 2xl
-            (32, 99, "radius.3xl"),   # 32-99px = 3xl
+            (0, 2, "radius.none"), (2, 4, "radius.xs"), (4, 6, "radius.sm"),
+            (6, 10, "radius.md"), (10, 16, "radius.lg"), (16, 32, "radius.xl"),
+            (32, 100, "radius.2xl"),
         ]
         base_name = "radius.md"
         for low, high, name in mapping:
-            if low <= px <= high:
+            if low <= px < high:
                 base_name = name
                 break
 
@@ -2958,92 +2942,6 @@ def _get_shadow_blur(value_str: str) -> float:
     return 0
 
 
-def _parse_shadow_to_tokens_studio(value_str: str) -> dict:
-    """Parse CSS shadow string to Figma Tokens Studio boxShadow format.
-
-    Input: "rgba(0, 0, 0, 0.5) 0px 2px 4px 0px" or "0px 2px 4px 0px rgba(0,0,0,0.5)"
-    Output: {"x": "0", "y": "2", "blur": "4", "spread": "0", "color": "rgba(0,0,0,0.5)", "type": "dropShadow"}
-    """
-    import re
-    value_str = str(value_str).strip()
-
-    # Extract color (rgba/rgb/hex)
-    color_match = re.search(r'(rgba?\([^)]+\)|#[0-9a-fA-F]{3,8})', value_str)
-    color = color_match.group(1) if color_match else "rgba(0,0,0,0.25)"
-
-    # Extract px values
-    px_values = re.findall(r'(-?[\d.]+)px', value_str)
-
-    # Standard order: x y blur spread
-    x = px_values[0] if len(px_values) > 0 else "0"
-    y = px_values[1] if len(px_values) > 1 else "0"
-    blur = px_values[2] if len(px_values) > 2 else "0"
-    spread = px_values[3] if len(px_values) > 3 else "0"
-
-    # Determine if inset
-    shadow_type = "innerShadow" if "inset" in value_str.lower() else "dropShadow"
-
-    return {
-        "x": x,
-        "y": y,
-        "blur": blur,
-        "spread": spread,
-        "color": color,
-        "type": shadow_type,
-    }
-
-
-# =============================================================================
-# W3C DTCG FORMAT HELPERS
-# =============================================================================
-
-def _flat_key_to_nested(flat_key: str, value: dict, root: dict):
-    """Convert 'color.brand.primary' into nested dict structure.
-
-    Example: _flat_key_to_nested('color.brand.primary', token, {})
-    Result: {'color': {'brand': {'primary': token}}}
-    """
-    parts = flat_key.split('.')
-    current = root
-    for part in parts[:-1]:
-        if part not in current:
-            current[part] = {}
-        current = current[part]
-    current[parts[-1]] = value
-
-
-def _to_dtcg_token(value, token_type: str, description: str = None, source: str = None) -> dict:
-    """Wrap value in W3C DTCG format with $value, $type, $description.
-
-    Args:
-        value: The token value
-        token_type: W3C DTCG type (color, typography, dimension, shadow)
-        description: Optional human-readable description
-        source: Optional source indicator (extracted, recommended, semantic)
-    """
-    token = {"$type": token_type, "$value": value}
-    if description:
-        token["$description"] = description
-    if source:
-        token["$description"] = f"[{source}] {description or ''}"
-    return token
-
-
-def _shadow_to_dtcg(shadow_dict: dict) -> dict:
-    """Convert our internal shadow format to W3C DTCG shadow spec.
-
-    Input: {"x": "0", "y": "2", "blur": "4", "spread": "0", "color": "rgba(...)"}
-    Output: {"color": "...", "offsetX": "0px", "offsetY": "2px", "blur": "4px", "spread": "0px"}
-    """
-    return {
-        "color": shadow_dict.get("color", "rgba(0,0,0,0.25)"),
-        "offsetX": str(shadow_dict.get("x", "0")) + "px",
-        "offsetY": str(shadow_dict.get("y", "0")) + "px",
-        "blur": str(shadow_dict.get("blur", "0")) + "px",
-        "spread": str(shadow_dict.get("spread", "0")) + "px",
-    }
-
-
 def _get_semantic_color_overrides() -> dict:
     """Build color hex→semantic name map from semantic analysis + LLM results."""
     overrides = {}  # hex → semantic_name
@@ -3117,104 +3015,6 @@ def _get_semantic_color_overrides() -> dict:
     return overrides
 
 
-def _is_valid_hex_color(value: str) -> bool:
-    """Validate that a string is a proper hex color (not CSS garbage)."""
-    import re
-    if not value or not isinstance(value, str):
-        return False
-    # Must be exactly #RGB, #RRGGBB, or #RRGGBBAA
-    clean = value.strip().lower()
-    return bool(re.match(r'^#([a-f0-9]{3}|[a-f0-9]{6}|[a-f0-9]{8})$', clean))
-
-
-def _generate_color_name_from_hex(hex_val: str, used_names: set = None) -> str:
-    """Generate a semantic color name based on the color's HSL characteristics.
-
-    Returns names like: color.neutral.400, color.blue.500, color.red.300
-    Uses standard design system naming conventions.
-    """
-    import colorsys
-
-    used_names = used_names or set()
-
-    # Parse hex to RGB
-    hex_clean = hex_val.lstrip('#').lower()
-    if len(hex_clean) == 3:
-        hex_clean = ''.join([c*2 for c in hex_clean])
-
-    try:
-        r = int(hex_clean[0:2], 16) / 255
-        g = int(hex_clean[2:4], 16) / 255
-        b = int(hex_clean[4:6], 16) / 255
-    except (ValueError, IndexError):
-        return "color.other.base"
-
-    # Convert to HSL
-    h, l, s = colorsys.rgb_to_hls(r, g, b)
-    hue = h * 360
-    saturation = s
-    lightness = l
-
-    # Determine color family based on hue (for saturated colors)
-    if saturation < 0.1:
-        # Grayscale / neutral
-        color_family = "neutral"
-    else:
-        # Map hue to color name
-        if hue < 15 or hue >= 345:
-            color_family = "red"
-        elif hue < 45:
-            color_family = "orange"
-        elif hue < 75:
-            color_family = "yellow"
-        elif hue < 150:
-            color_family = "green"
-        elif hue < 195:
-            color_family = "teal"
-        elif hue < 255:
-            color_family = "blue"
-        elif hue < 285:
-            color_family = "purple"
-        elif hue < 345:
-            color_family = "pink"
-        else:
-            color_family = "red"
-
-    # Determine shade based on lightness (100-900 scale)
-    if lightness >= 0.95:
-        shade = "50"
-    elif lightness >= 0.85:
-        shade = "100"
-    elif lightness >= 0.75:
-        shade = "200"
-    elif lightness >= 0.65:
-        shade = "300"
-    elif lightness >= 0.50:
-        shade = "400"
-    elif lightness >= 0.40:
-        shade = "500"
-    elif lightness >= 0.30:
-        shade = "600"
-    elif lightness >= 0.20:
-        shade = "700"
-    elif lightness >= 0.10:
-        shade = "800"
-    else:
-        shade = "900"
-
-    # Generate base name
-    base_name = f"color.{color_family}.{shade}"
-
-    # Handle conflicts by adding suffix
-    final_name = base_name
-    suffix = 1
-    while final_name in used_names:
-        suffix += 1
-        final_name = f"{base_name}_{suffix}"
-
-    return final_name
-
-
 def _consolidate_colors(colors_dict: dict, overrides: dict, max_colors: int = 30) -> dict:
     """Consolidate colors: semantic first, then top by frequency, capped."""
     if not colors_dict:
@@ -3222,15 +3022,9 @@ def _consolidate_colors(colors_dict: dict, overrides: dict, max_colors: int = 30
 
     result = {}
     remaining = []
-    used_generated_names = set()  # Track generated names to avoid conflicts
 
     for name, c in colors_dict.items():
         hex_val = c.value.lower() if hasattr(c, 'value') else str(c.get('value', '')).lower()
-
-        # IMPORTANT: Skip invalid/garbage color values (CSS parsing errors)
-        if not _is_valid_hex_color(hex_val):
-            continue
-
         freq = c.frequency if hasattr(c, 'frequency') else c.get('frequency', 0)
 
         # Check if this color has a semantic override
@@ -3242,24 +3036,11 @@ def _consolidate_colors(colors_dict: dict, overrides: dict, max_colors: int = 30
                 "source": "semantic",
             }
         else:
-            # Check for garbage names (firecrawl.N, numeric-only, etc.)
+            # Use normalizer's suggested name
             base_name = (c.suggested_name if hasattr(c, 'suggested_name') else name) or name
             clean_name = base_name.replace(" ", ".").replace("_", ".").lower()
-
-            # Detect garbage names and generate proper color-based names
-            is_garbage_name = (
-                'firecrawl' in clean_name.lower() or
-                clean_name.split('.')[-1].isdigit() or  # Ends with just a number
-                len(clean_name.split('.')) == 2 and clean_name.split('.')[-1].isdigit()  # color.34
-            )
-
-            if is_garbage_name:
-                # Generate proper name based on color characteristics
-                clean_name = _generate_color_name_from_hex(hex_val, used_generated_names)
-                used_generated_names.add(clean_name)
-            elif not clean_name.startswith("color."):
+            if not clean_name.startswith("color."):
                 clean_name = f"color.{clean_name}"
-
             remaining.append((clean_name, hex_val, freq))
 
     # Sort remaining by frequency (highest first), take up to max
@@ -3277,7 +3058,7 @@ def _consolidate_colors(colors_dict: dict, overrides: dict, max_colors: int = 30
 
 
 def export_stage1_json():
-    """Export Stage 1 tokens (as-is extraction) to W3C DTCG format."""
+    """Export Stage 1 tokens (as-is extraction) to JSON - FLAT structure for Figma Tokens Studio."""
     if not state.desktop_normalized:
         gr.Warning("No tokens extracted yet. Complete Stage 1 extraction first.")
         return json.dumps({
@@ -3285,29 +3066,44 @@ def export_stage1_json():
             "how_to_fix": "Go to Step 1, enter a URL, discover pages, and extract tokens first.",
             "stage": "Stage 1 required"
         }, indent=2)
-
-    # W3C DTCG format: nested structure, no wrapper, $value/$type
-    result = {}
-    token_count = 0
-
+    
+    # FLAT structure for Figma Tokens Studio compatibility
+    result = {
+        "metadata": {
+            "source_url": state.base_url,
+            "extracted_at": datetime.now().isoformat(),
+            "version": "v1-stage1-as-is",
+            "stage": "extraction",
+            "description": "Raw extracted tokens before upgrades - Figma Tokens Studio compatible",
+        },
+        "fonts": {},
+        "colors": {},
+        "typography": {},      # FLAT: font.display.xl.desktop, font.display.xl.mobile
+        "spacing": {},         # FLAT: space.1.desktop, space.1.mobile
+        "radius": {},
+        "shadows": {},
+    }
+    
+    # =========================================================================
+    # FONTS
     # =========================================================================
-    # COLORS — Nested structure with $value, $type, $description
+    fonts_info = get_detected_fonts()
+    result["fonts"] = {
+        "primary": fonts_info.get("primary", "Unknown"),
+        "weights": fonts_info.get("weights", [400]),
+    }
+    
+    # =========================================================================
+    # COLORS — Consolidated with semantic names (capped ~30)
     # =========================================================================
     if state.desktop_normalized and state.desktop_normalized.colors:
         overrides = _get_semantic_color_overrides()
-        consolidated = _consolidate_colors(
+        result["colors"] = _consolidate_colors(
             state.desktop_normalized.colors, overrides, max_colors=30,
         )
-        for flat_key, entry in consolidated.items():
-            # flat_key = "color.brand.primary"
-            source = entry.get("source", "extracted")
-            source_label = "LLM Semantic" if source == "semantic" else "Auto-Generated" if source == "detected" else "Extracted"
-            dtcg_token = _to_dtcg_token(entry["value"], "color", description=source_label)
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
 
     # =========================================================================
-    # TYPOGRAPHY — Nested structure with viewport suffix
+    # TYPOGRAPHY - FLAT structure with viewport suffix
     # =========================================================================
     # Desktop typography
     if state.desktop_normalized and state.desktop_normalized.typography:
@@ -3316,18 +3112,19 @@ def export_stage1_json():
             clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
             if not clean_name.startswith("font."):
                 clean_name = f"font.{clean_name}"
-
-            flat_key = f"{clean_name}.desktop"
-            typo_value = {
+            
+            # Add .desktop suffix
+            token_key = f"{clean_name}.desktop"
+            
+            result["typography"][token_key] = {
+                "value": t.font_size,
+                "type": "dimension",
                 "fontFamily": t.font_family,
-                "fontSize": t.font_size,
                 "fontWeight": str(t.font_weight),
                 "lineHeight": t.line_height or "1.5",
+                "source": "detected",
             }
-            dtcg_token = _to_dtcg_token(typo_value, "typography", description="Extracted from site")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
-
+    
     # Mobile typography
     if state.mobile_normalized and state.mobile_normalized.typography:
         for name, t in state.mobile_normalized.typography.items():
@@ -3335,20 +3132,21 @@ def export_stage1_json():
             clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
             if not clean_name.startswith("font."):
                 clean_name = f"font.{clean_name}"
-
-            flat_key = f"{clean_name}.mobile"
-            typo_value = {
+            
+            # Add .mobile suffix
+            token_key = f"{clean_name}.mobile"
+            
+            result["typography"][token_key] = {
+                "value": t.font_size,
+                "type": "dimension",
                 "fontFamily": t.font_family,
-                "fontSize": t.font_size,
                 "fontWeight": str(t.font_weight),
                 "lineHeight": t.line_height or "1.5",
+                "source": "detected",
             }
-            dtcg_token = _to_dtcg_token(typo_value, "typography", description="Extracted from site")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
-
+    
     # =========================================================================
-    # SPACING — Nested structure with viewport suffix
+    # SPACING - FLAT structure with viewport suffix
     # =========================================================================
     # Desktop spacing
     if state.desktop_normalized and state.desktop_normalized.spacing:
@@ -3357,12 +3155,16 @@ def export_stage1_json():
             clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
             if not clean_name.startswith("space."):
                 clean_name = f"space.{clean_name}"
-
-            flat_key = f"{clean_name}.desktop"
-            dtcg_token = _to_dtcg_token(s.value, "dimension", description="Extracted from site")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
-
+            
+            # Add .desktop suffix
+            token_key = f"{clean_name}.desktop"
+            
+            result["spacing"][token_key] = {
+                "value": s.value,
+                "type": "dimension",
+                "source": "detected",
+            }
+    
     # Mobile spacing
     if state.mobile_normalized and state.mobile_normalized.spacing:
         for name, s in state.mobile_normalized.spacing.items():
@@ -3370,46 +3172,49 @@ def export_stage1_json():
             clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
             if not clean_name.startswith("space."):
                 clean_name = f"space.{clean_name}"
-
-            flat_key = f"{clean_name}.mobile"
-            dtcg_token = _to_dtcg_token(s.value, "dimension", description="Extracted from site")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
-
+            
+            # Add .mobile suffix
+            token_key = f"{clean_name}.mobile"
+            
+            result["spacing"][token_key] = {
+                "value": s.value,
+                "type": "dimension",
+                "source": "detected",
+            }
+    
     # =========================================================================
-    # BORDER RADIUS — Nested structure (DTCG uses "dimension" type for radii)
+    # RADIUS — Semantic names (radius.sm, radius.md, radius.lg)
     # =========================================================================
     if state.desktop_normalized and state.desktop_normalized.radius:
         seen_radius = {}
         for name, r in state.desktop_normalized.radius.items():
             token_name = _get_radius_token_name(r.value, seen_radius)
-            # Convert "radius.md" to nested: radius.md (keep as "radius" for consistency)
-            flat_key = token_name
-            dtcg_token = _to_dtcg_token(r.value, "dimension", description="Extracted from site")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
+            result["radius"][token_name] = {
+                "value": r.value,
+                "type": "dimension",
+                "source": "detected",
+            }
 
     # =========================================================================
-    # SHADOWS — W3C DTCG shadow format
+    # SHADOWS — Semantic names (shadow.xs, shadow.sm, shadow.md)
     # =========================================================================
     if state.desktop_normalized and state.desktop_normalized.shadows:
-        shadow_names = ["xs", "sm", "md", "lg", "xl", "2xl"]
+        shadow_names = ["shadow.xs", "shadow.sm", "shadow.md", "shadow.lg", "shadow.xl", "shadow.2xl"]
         sorted_shadows = sorted(
             state.desktop_normalized.shadows.items(),
             key=lambda x: _get_shadow_blur(x[1].value),
         )
         for i, (name, s) in enumerate(sorted_shadows):
-            size_name = shadow_names[i] if i < len(shadow_names) else str(i + 1)
-            flat_key = f"shadow.{size_name}"
-            # Parse CSS shadow and convert to DTCG format
-            parsed = _parse_shadow_to_tokens_studio(s.value)
-            dtcg_shadow_value = _shadow_to_dtcg(parsed)
-            dtcg_token = _to_dtcg_token(dtcg_shadow_value, "shadow", description="Extracted from site")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
+            token_name = shadow_names[i] if i < len(shadow_names) else f"shadow.{i + 1}"
+            result["shadows"][token_name] = {
+                "value": s.value,
+                "type": "boxShadow",
+                "source": "detected",
+            }
 
     json_str = json.dumps(result, indent=2, default=str)
-    gr.Info(f"Stage 1 exported: {token_count} tokens (W3C DTCG format)")
+    token_count = sum(len(v) for k, v in result.items() if isinstance(v, dict) and k != "metadata")
+    gr.Info(f"Stage 1 exported: {token_count} tokens across {len(result) - 1} categories")
     return json_str
 
 
@@ -3447,11 +3252,36 @@ def export_tokens_json():
     elif "4px" in spacing_choice:
         spacing_base = 4
     
-    # W3C DTCG format: nested structure, no wrapper
-    result = {}
-    token_count = 0
-
+    # FLAT structure for Figma Tokens Studio compatibility
+    result = {
+        "metadata": {
+            "source_url": state.base_url,
+            "extracted_at": datetime.now().isoformat(),
+            "version": "v2-upgraded",
+            "stage": "final",
+            "description": "Upgraded tokens - Figma Tokens Studio compatible",
+            "upgrades_applied": {
+                "type_scale": type_scale_choice,
+                "spacing": spacing_choice,
+                "color_ramps": apply_ramps,
+            },
+        },
+        "fonts": {},
+        "colors": {},
+        "typography": {},      # FLAT: font.display.xl.desktop, font.display.xl.mobile
+        "spacing": {},         # FLAT: space.1.desktop, space.1.mobile
+        "radius": {},
+        "shadows": {},
+    }
+    
+    # =========================================================================
+    # FONTS
+    # =========================================================================
     fonts_info = get_detected_fonts()
+    result["fonts"] = {
+        "primary": fonts_info.get("primary", "Unknown"),
+        "weights": fonts_info.get("weights", [400]),
+    }
     primary_font = fonts_info.get("primary", "sans-serif")
     
     # =========================================================================
@@ -3465,26 +3295,23 @@ def export_tokens_json():
             state.desktop_normalized.colors, overrides, max_colors=30,
         )
 
-        for flat_key, entry in consolidated.items():
+        for clean_name, entry in consolidated.items():
             if apply_ramps:
                 try:
                     ramp = generate_color_ramp(entry["value"])
                     shades = ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900", "950"]
                     for i, shade in enumerate(shades):
                         if i < len(ramp):
-                            shade_key = f"{flat_key}.{shade}"
-                            color_val = ramp[i] if isinstance(ramp[i], str) else ramp[i].get("hex", entry["value"])
-                            dtcg_token = _to_dtcg_token(color_val, "color")
-                            _flat_key_to_nested(shade_key, dtcg_token, result)
-                            token_count += 1
+                            shade_key = f"{clean_name}.{shade}"
+                            result["colors"][shade_key] = {
+                                "value": ramp[i] if isinstance(ramp[i], str) else ramp[i].get("hex", entry["value"]),
+                                "type": "color",
+                                "source": "upgraded" if shade != "500" else entry.get("source", "detected"),
+                            }
                 except (ValueError, KeyError, TypeError, IndexError):
-                    dtcg_token = _to_dtcg_token(entry["value"], "color")
-                    _flat_key_to_nested(flat_key, dtcg_token, result)
-                    token_count += 1
+                    result["colors"][clean_name] = entry
             else:
-                dtcg_token = _to_dtcg_token(entry["value"], "color")
-                _flat_key_to_nested(flat_key, dtcg_token, result)
-                token_count += 1
+                result["colors"][clean_name] = entry
     
     # =========================================================================
     # TYPOGRAPHY - FLAT structure with viewport suffix
@@ -3513,137 +3340,145 @@ def export_tokens_json():
                 return tier
         return "body"
 
-    # Desktop typography — W3C DTCG format
+    # Desktop typography
     if ratio:
+        # Apply type scale
         scales = [int(round(base_size * (ratio ** (8-i)) / 2) * 2) for i in range(13)]
         for i, token_name in enumerate(token_names):
             tier = _tier_from_token(token_name)
-            flat_key = f"{token_name}.desktop"
-            typo_value = {
+            desktop_key = f"{token_name}.desktop"
+            result["typography"][desktop_key] = {
+                "value": f"{scales[i]}px",
+                "type": "dimension",
                 "fontFamily": primary_font,
-                "fontSize": f"{scales[i]}px",
                 "fontWeight": _weight_map.get(tier, "400"),
                 "lineHeight": _lh_map.get(tier, "1.5"),
+                "source": "upgraded",
             }
-            dtcg_token = _to_dtcg_token(typo_value, "typography")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
     elif state.desktop_normalized and state.desktop_normalized.typography:
+        # Keep original with flat structure
         for name, t in state.desktop_normalized.typography.items():
             base_name = t.suggested_name or name
             clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
             if not clean_name.startswith("font."):
                 clean_name = f"font.{clean_name}"
-
-            flat_key = f"{clean_name}.desktop"
-            typo_value = {
+            
+            desktop_key = f"{clean_name}.desktop"
+            result["typography"][desktop_key] = {
+                "value": t.font_size,
+                "type": "dimension",
                 "fontFamily": t.font_family,
-                "fontSize": t.font_size,
                 "fontWeight": str(t.font_weight),
                 "lineHeight": t.line_height or "1.5",
+                "source": "detected",
             }
-            dtcg_token = _to_dtcg_token(typo_value, "typography")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
-
-    # Mobile typography — W3C DTCG format
+    
+    # Mobile typography
     if ratio:
+        # Apply type scale with mobile factor
         mobile_factor = 0.875
         scales = [int(round(base_size * mobile_factor * (ratio ** (8-i)) / 2) * 2) for i in range(13)]
         for i, token_name in enumerate(token_names):
             tier = _tier_from_token(token_name)
-            flat_key = f"{token_name}.mobile"
-            typo_value = {
+            mobile_key = f"{token_name}.mobile"
+            result["typography"][mobile_key] = {
+                "value": f"{scales[i]}px",
+                "type": "dimension",
                 "fontFamily": primary_font,
-                "fontSize": f"{scales[i]}px",
                 "fontWeight": _weight_map.get(tier, "400"),
                 "lineHeight": _lh_map.get(tier, "1.5"),
+                "source": "upgraded",
             }
-            dtcg_token = _to_dtcg_token(typo_value, "typography")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
     elif state.mobile_normalized and state.mobile_normalized.typography:
         for name, t in state.mobile_normalized.typography.items():
             base_name = t.suggested_name or name
             clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
             if not clean_name.startswith("font."):
                 clean_name = f"font.{clean_name}"
-
-            flat_key = f"{clean_name}.mobile"
-            typo_value = {
+            
+            mobile_key = f"{clean_name}.mobile"
+            result["typography"][mobile_key] = {
+                "value": t.font_size,
+                "type": "dimension",
                 "fontFamily": t.font_family,
-                "fontSize": t.font_size,
                 "fontWeight": str(t.font_weight),
                 "lineHeight": t.line_height or "1.5",
+                "source": "detected",
             }
-            dtcg_token = _to_dtcg_token(typo_value, "typography")
-            _flat_key_to_nested(flat_key, dtcg_token, result)
-            token_count += 1
     
     # =========================================================================
-    # SPACING — W3C DTCG format with nested structure
+    # SPACING - FLAT structure with viewport suffix
     # =========================================================================
     spacing_token_names = [
         "space.1", "space.2", "space.3", "space.4", "space.5",
         "space.6", "space.8", "space.10", "space.12", "space.16"
     ]
-
+    
     if spacing_base:
         # Generate grid-aligned spacing for both viewports
         for i, token_name in enumerate(spacing_token_names):
             value = spacing_base * (i + 1)
-
+            
             # Desktop
             desktop_key = f"{token_name}.desktop"
-            dtcg_token = _to_dtcg_token(f"{value}px", "dimension")
-            _flat_key_to_nested(desktop_key, dtcg_token, result)
-            token_count += 1
-
+            result["spacing"][desktop_key] = {
+                "value": f"{value}px",
+                "type": "dimension",
+                "source": "upgraded",
+            }
+            
             # Mobile (same values)
             mobile_key = f"{token_name}.mobile"
-            dtcg_token = _to_dtcg_token(f"{value}px", "dimension")
-            _flat_key_to_nested(mobile_key, dtcg_token, result)
-            token_count += 1
+            result["spacing"][mobile_key] = {
+                "value": f"{value}px",
+                "type": "dimension",
+                "source": "upgraded",
+            }
     else:
-        # Keep original with nested structure
+        # Keep original with flat structure
         if state.desktop_normalized and state.desktop_normalized.spacing:
             for name, s in state.desktop_normalized.spacing.items():
                 base_name = s.suggested_name or name
                 clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
                 if not clean_name.startswith("space."):
                     clean_name = f"space.{clean_name}"
-
+                
                 desktop_key = f"{clean_name}.desktop"
-                dtcg_token = _to_dtcg_token(s.value, "dimension")
-                _flat_key_to_nested(desktop_key, dtcg_token, result)
-                token_count += 1
-
+                result["spacing"][desktop_key] = {
+                    "value": s.value,
+                    "type": "dimension",
+                    "source": "detected",
+                }
+        
         if state.mobile_normalized and state.mobile_normalized.spacing:
             for name, s in state.mobile_normalized.spacing.items():
                 base_name = s.suggested_name or name
                 clean_name = base_name.replace(" ", ".").replace("_", ".").replace("-", ".").lower()
                 if not clean_name.startswith("space."):
                     clean_name = f"space.{clean_name}"
-
+                
                 mobile_key = f"{clean_name}.mobile"
-                dtcg_token = _to_dtcg_token(s.value, "dimension")
-                _flat_key_to_nested(mobile_key, dtcg_token, result)
-                token_count += 1
-
+                result["spacing"][mobile_key] = {
+                    "value": s.value,
+                    "type": "dimension",
+                    "source": "detected",
+                }
+    
     # =========================================================================
-    # BORDER RADIUS — W3C DTCG format (uses "dimension" type per spec)
+    # RADIUS — Semantic names (radius.sm, radius.md, radius.lg)
     # =========================================================================
     if state.desktop_normalized and state.desktop_normalized.radius:
         seen_radius = {}
         for name, r in state.desktop_normalized.radius.items():
             token_name = _get_radius_token_name(r.value, seen_radius)
-            # DTCG uses "dimension" for radii, not "borderRadius"
-            dtcg_token = _to_dtcg_token(r.value, "dimension")
-            _flat_key_to_nested(token_name, dtcg_token, result)
-            token_count += 1
+            result["radius"][token_name] = {
+                "value": r.value,
+                "type": "dimension",
+                "source": "detected",
+            }
 
     # =========================================================================
-    # SHADOWS — W3C DTCG format with shadow spec
+    # SHADOWS — Semantic names (shadow.xs, shadow.sm, shadow.md)
     # =========================================================================
     if state.desktop_normalized and state.desktop_normalized.shadows:
         shadow_names = ["shadow.xs", "shadow.sm", "shadow.md", "shadow.lg", "shadow.xl", "shadow.2xl"]
@@ -3653,15 +3488,16 @@ def export_tokens_json():
         )
         for i, (name, s) in enumerate(sorted_shadows):
             token_name = shadow_names[i] if i < len(shadow_names) else f"shadow.{i + 1}"
-            # Convert to DTCG shadow format
-            shadow_value = _shadow_to_dtcg(_parse_shadow_to_tokens_studio(s.value))
-            dtcg_token = _to_dtcg_token(shadow_value, "shadow")
-            _flat_key_to_nested(token_name, dtcg_token, result)
-            token_count += 1
+            result["shadows"][token_name] = {
+                "value": s.value,
+                "type": "boxShadow",
+                "source": "detected",
+            }
 
     json_str = json.dumps(result, indent=2, default=str)
+    token_count = sum(len(v) for k, v in result.items() if isinstance(v, dict) and k != "metadata")
     upgrades_note = " (with upgrades)" if upgrades else " (no upgrades applied)"
-    gr.Info(f"Final export: {token_count} tokens{upgrades_note}")
+    gr.Info(f"Final export: {token_count} tokens across {len(result) - 1} categories{upgrades_note}")
     return json_str
 
 

core/rule_engine.py

@@ -404,11 +404,7 @@ def analyze_type_scale(typography_tokens: dict) -> TypeScaleAnalysis:
     sizes_px = sorted(set(sizes))
     
     if len(sizes_px) < 2:
-        # Use the size if valid (>= 10px), otherwise default to 16px
-        if sizes_px and sizes_px[0] >= 10:
-            base_size = sizes_px[0]
-        else:
-            base_size = 16.0
+        base_size = sizes_px[0] if sizes_px else 16.0
         return TypeScaleAnalysis(
             detected_ratio=1.0,
             closest_standard_ratio=1.25,
@@ -432,17 +428,8 @@ def analyze_type_scale(typography_tokens: dict) -> TypeScaleAnalysis:
     
     if not ratios:
         # Detect base size even if no valid ratios
-        # Filter out tiny sizes (< 10px) which are likely captions/icons
-        valid_body_sizes = [s for s in sizes_px if s >= 10]
-        base_candidates = [s for s in valid_body_sizes if 14 <= s <= 18]
-        if base_candidates:
-            base_size = min(base_candidates, key=lambda x: abs(x - 16))
-        elif valid_body_sizes:
-            base_size = min(valid_body_sizes, key=lambda x: abs(x - 16))
-        elif sizes_px:
-            base_size = max(sizes_px)  # Last resort: largest of tiny sizes
-        else:
-            base_size = 16.0
+        base_candidates = [s for s in sizes_px if 14 <= s <= 18]
+        base_size = min(base_candidates, key=lambda x: abs(x - 16)) if base_candidates else (min(sizes_px, key=lambda x: abs(x - 16)) if sizes_px else 16.0)
         return TypeScaleAnalysis(
             detected_ratio=1.0,
             closest_standard_ratio=1.25,
@@ -469,23 +456,16 @@ def analyze_type_scale(typography_tokens: dict) -> TypeScaleAnalysis:
     
     # Detect base size (closest to 16px, or 14-18px range typical for body)
     # The base size is typically the most common body text size
-    # IMPORTANT: Filter out tiny sizes (< 10px) which are likely captions/icons
-    valid_body_sizes = [s for s in sizes_px if s >= 10]
-
-    base_candidates = [s for s in valid_body_sizes if 14 <= s <= 18]
+    base_candidates = [s for s in sizes_px if 14 <= s <= 18]
     if base_candidates:
         # Prefer 16px if present, otherwise closest to 16
         if 16 in base_candidates:
             base_size = 16.0
         else:
             base_size = min(base_candidates, key=lambda x: abs(x - 16))
-    elif valid_body_sizes:
-        # Fallback: find size closest to 16px from valid sizes (>= 10px)
-        # This avoids picking tiny caption/icon sizes like 7px
-        base_size = min(valid_body_sizes, key=lambda x: abs(x - 16))
     elif sizes_px:
-        # Last resort: just use the largest size if all are tiny
-        base_size = max(sizes_px)
+        # Fallback: find size closest to 16px
+        base_size = min(sizes_px, key=lambda x: abs(x - 16))
     else:
         base_size = 16.0