Delete core/rule_engine.py

core/rule_engine.py

@@ -1,900 +0,0 @@
-"""
-Rule Engine — Deterministic Design System Analysis
-===================================================
-
-This module handles ALL calculations that don't need LLM reasoning:
-- Type scale detection
-- AA/AAA contrast checking
-- Algorithmic color fixes
-- Spacing grid detection
-- Color statistics and deduplication
-
-LLMs should ONLY be used for:
-- Brand color identification (requires context understanding)
-- Palette cohesion (subjective assessment)
-- Design maturity scoring (holistic evaluation)
-- Prioritized recommendations (business reasoning)
-"""
-
-import colorsys
-import re
-from dataclasses import dataclass, field
-from functools import reduce
-from math import gcd
-from typing import Optional
-
-
-# =============================================================================
-# DATA CLASSES
-# =============================================================================
-
-@dataclass
-class TypeScaleAnalysis:
-    """Results of type scale analysis."""
-    detected_ratio: float
-    closest_standard_ratio: float
-    scale_name: str
-    is_consistent: bool
-    variance: float
-    sizes_px: list[float]
-    ratios_between_sizes: list[float]
-    recommendation: float
-    recommendation_name: str
-    base_size: float = 16.0  # Detected base/body font size
-    
-    def to_dict(self) -> dict:
-        return {
-            "detected_ratio": round(self.detected_ratio, 3),
-            "closest_standard_ratio": self.closest_standard_ratio,
-            "scale_name": self.scale_name,
-            "is_consistent": self.is_consistent,
-            "variance": round(self.variance, 3),
-            "sizes_px": self.sizes_px,
-            "base_size": self.base_size,
-            "recommendation": self.recommendation,
-            "recommendation_name": self.recommendation_name,
-        }
-
-
-@dataclass
-class ColorAccessibility:
-    """Accessibility analysis for a single color."""
-    hex_color: str
-    name: str
-    contrast_on_white: float
-    contrast_on_black: float
-    passes_aa_normal: bool  # 4.5:1
-    passes_aa_large: bool   # 3.0:1
-    passes_aaa_normal: bool # 7.0:1
-    best_text_color: str    # White or black
-    suggested_fix: Optional[str] = None
-    suggested_fix_contrast: Optional[float] = None
-    
-    def to_dict(self) -> dict:
-        return {
-            "color": self.hex_color,
-            "name": self.name,
-            "contrast_white": round(self.contrast_on_white, 2),
-            "contrast_black": round(self.contrast_on_black, 2),
-            "aa_normal": self.passes_aa_normal,
-            "aa_large": self.passes_aa_large,
-            "aaa_normal": self.passes_aaa_normal,
-            "best_text": self.best_text_color,
-            "suggested_fix": self.suggested_fix,
-            "suggested_fix_contrast": round(self.suggested_fix_contrast, 2) if self.suggested_fix_contrast else None,
-        }
-
-
-@dataclass
-class SpacingGridAnalysis:
-    """Results of spacing grid analysis."""
-    detected_base: int
-    is_aligned: bool
-    alignment_percentage: float
-    misaligned_values: list[int]
-    recommendation: int
-    recommendation_reason: str
-    current_values: list[int]
-    suggested_scale: list[int]
-    
-    def to_dict(self) -> dict:
-        return {
-            "detected_base": self.detected_base,
-            "is_aligned": self.is_aligned,
-            "alignment_percentage": round(self.alignment_percentage, 1),
-            "misaligned_values": self.misaligned_values,
-            "recommendation": self.recommendation,
-            "recommendation_reason": self.recommendation_reason,
-            "current_values": self.current_values,
-            "suggested_scale": self.suggested_scale,
-        }
-
-
-@dataclass
-class ColorStatistics:
-    """Statistical analysis of color palette."""
-    total_count: int
-    unique_count: int
-    duplicate_count: int
-    gray_count: int
-    saturated_count: int
-    near_duplicates: list[tuple[str, str, float]]  # (color1, color2, similarity)
-    hue_distribution: dict[str, int]  # {"red": 5, "blue": 3, ...}
-    
-    def to_dict(self) -> dict:
-        return {
-            "total": self.total_count,
-            "unique": self.unique_count,
-            "duplicates": self.duplicate_count,
-            "grays": self.gray_count,
-            "saturated": self.saturated_count,
-            "near_duplicates_count": len(self.near_duplicates),
-            "hue_distribution": self.hue_distribution,
-        }
-
-
-@dataclass 
-class RuleEngineResults:
-    """Complete rule engine analysis results."""
-    typography: TypeScaleAnalysis
-    accessibility: list[ColorAccessibility]
-    spacing: SpacingGridAnalysis
-    color_stats: ColorStatistics
-    
-    # Summary
-    aa_failures: int
-    consistency_score: int  # 0-100
-    
-    def to_dict(self) -> dict:
-        return {
-            "typography": self.typography.to_dict(),
-            "accessibility": [a.to_dict() for a in self.accessibility if not a.passes_aa_normal],
-            "accessibility_all": [a.to_dict() for a in self.accessibility],
-            "spacing": self.spacing.to_dict(),
-            "color_stats": self.color_stats.to_dict(),
-            "summary": {
-                "aa_failures": self.aa_failures,
-                "consistency_score": self.consistency_score,
-            }
-        }
-
-
-# =============================================================================
-# COLOR UTILITIES
-# =============================================================================
-
-def hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
-    """Convert hex to RGB tuple."""
-    hex_color = hex_color.lstrip('#')
-    if len(hex_color) == 3:
-        hex_color = ''.join([c*2 for c in hex_color])
-    return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))
-
-
-def rgb_to_hex(r: int, g: int, b: int) -> str:
-    """Convert RGB to hex string."""
-    r = max(0, min(255, r))
-    g = max(0, min(255, g))
-    b = max(0, min(255, b))
-    return f"#{r:02x}{g:02x}{b:02x}"
-
-
-def get_relative_luminance(hex_color: str) -> float:
-    """Calculate relative luminance per WCAG 2.1."""
-    r, g, b = hex_to_rgb(hex_color)
-    
-    def channel_luminance(c):
-        c = c / 255
-        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
-    
-    return 0.2126 * channel_luminance(r) + 0.7152 * channel_luminance(g) + 0.0722 * channel_luminance(b)
-
-
-def get_contrast_ratio(color1: str, color2: str) -> float:
-    """Calculate WCAG contrast ratio between two colors."""
-    l1 = get_relative_luminance(color1)
-    l2 = get_relative_luminance(color2)
-    lighter = max(l1, l2)
-    darker = min(l1, l2)
-    return (lighter + 0.05) / (darker + 0.05)
-
-
-def is_gray(hex_color: str, threshold: float = 0.1) -> bool:
-    """Check if color is a gray (low saturation)."""
-    r, g, b = hex_to_rgb(hex_color)
-    h, s, v = colorsys.rgb_to_hsv(r/255, g/255, b/255)
-    return s < threshold
-
-
-def get_saturation(hex_color: str) -> float:
-    """Get saturation value (0-1)."""
-    r, g, b = hex_to_rgb(hex_color)
-    h, s, v = colorsys.rgb_to_hsv(r/255, g/255, b/255)
-    return s
-
-
-def get_hue_name(hex_color: str) -> str:
-    """Get human-readable hue name."""
-    r, g, b = hex_to_rgb(hex_color)
-    h, s, v = colorsys.rgb_to_hsv(r/255, g/255, b/255)
-    
-    if s < 0.1:
-        return "gray"
-    
-    hue_deg = h * 360
-    
-    if hue_deg < 15 or hue_deg >= 345:
-        return "red"
-    elif hue_deg < 45:
-        return "orange"
-    elif hue_deg < 75:
-        return "yellow"
-    elif hue_deg < 150:
-        return "green"
-    elif hue_deg < 210:
-        return "cyan"
-    elif hue_deg < 270:
-        return "blue"
-    elif hue_deg < 315:
-        return "purple"
-    else:
-        return "pink"
-
-
-def color_distance(hex1: str, hex2: str) -> float:
-    """Calculate perceptual color distance (0-1, lower = more similar)."""
-    r1, g1, b1 = hex_to_rgb(hex1)
-    r2, g2, b2 = hex_to_rgb(hex2)
-    
-    # Simple Euclidean distance in RGB space (normalized)
-    dr = (r1 - r2) / 255
-    dg = (g1 - g2) / 255
-    db = (b1 - b2) / 255
-    
-    return (dr**2 + dg**2 + db**2) ** 0.5 / (3 ** 0.5)
-
-
-def darken_color(hex_color: str, factor: float) -> str:
-    """Darken a color by a factor (0-1)."""
-    r, g, b = hex_to_rgb(hex_color)
-    r = int(r * (1 - factor))
-    g = int(g * (1 - factor))
-    b = int(b * (1 - factor))
-    return rgb_to_hex(r, g, b)
-
-
-def lighten_color(hex_color: str, factor: float) -> str:
-    """Lighten a color by a factor (0-1)."""
-    r, g, b = hex_to_rgb(hex_color)
-    r = int(r + (255 - r) * factor)
-    g = int(g + (255 - g) * factor)
-    b = int(b + (255 - b) * factor)
-    return rgb_to_hex(r, g, b)
-
-
-def find_aa_compliant_color(hex_color: str, background: str = "#ffffff", target_contrast: float = 4.5) -> str:
-    """
-    Algorithmically adjust a color until it meets AA contrast requirements.
-    
-    Returns the original color if it already passes, otherwise returns
-    a darkened/lightened version that passes.
-    """
-    current_contrast = get_contrast_ratio(hex_color, background)
-
-    if current_contrast >= target_contrast:
-        return hex_color
-
-    # Determine direction: move fg *away* from bg in luminance.
-    # If fg is lighter than bg → darken fg to increase gap.
-    # If fg is darker than bg → lighten fg to increase gap.
-    bg_luminance = get_relative_luminance(background)
-    color_luminance = get_relative_luminance(hex_color)
-
-    should_darken = color_luminance >= bg_luminance
-
-    best_color = hex_color
-    best_contrast = current_contrast
-
-    for i in range(1, 101):
-        factor = i / 100
-
-        if should_darken:
-            new_color = darken_color(hex_color, factor)
-        else:
-            new_color = lighten_color(hex_color, factor)
-
-        new_contrast = get_contrast_ratio(new_color, background)
-
-        if new_contrast >= target_contrast:
-            return new_color
-
-        if new_contrast > best_contrast:
-            best_contrast = new_contrast
-            best_color = new_color
-
-    # If first direction didn't reach target, try the opposite direction
-    # (e.g., very similar luminances where either direction could work)
-    should_darken = not should_darken
-    for i in range(1, 101):
-        factor = i / 100
-
-        if should_darken:
-            new_color = darken_color(hex_color, factor)
-        else:
-            new_color = lighten_color(hex_color, factor)
-
-        new_contrast = get_contrast_ratio(new_color, background)
-
-        if new_contrast >= target_contrast:
-            return new_color
-
-        if new_contrast > best_contrast:
-            best_contrast = new_contrast
-            best_color = new_color
-
-    return best_color
-
-
-# =============================================================================
-# TYPE SCALE ANALYSIS
-# =============================================================================
-
-# Standard type scale ratios
-STANDARD_SCALES = {
-    1.067: "Minor Second",
-    1.125: "Major Second",
-    1.200: "Minor Third",
-    1.250: "Major Third",       # ⭐ Recommended
-    1.333: "Perfect Fourth",
-    1.414: "Augmented Fourth",
-    1.500: "Perfect Fifth",
-    1.618: "Golden Ratio",
-    2.000: "Octave",
-}
-
-
-def parse_size_to_px(size: str) -> Optional[float]:
-    """Convert any size string to pixels."""
-    if isinstance(size, (int, float)):
-        return float(size)
-    
-    size = str(size).strip().lower()
-    
-    # Extract number
-    match = re.search(r'([\d.]+)', size)
-    if not match:
-        return None
-    
-    value = float(match.group(1))
-    
-    if 'rem' in size:
-        return value * 16  # Assume 16px base
-    elif 'em' in size:
-        return value * 16  # Approximate
-    elif 'px' in size or size.replace('.', '').isdigit():
-        return value
-    
-    return value
-
-
-def analyze_type_scale(typography_tokens: dict) -> TypeScaleAnalysis:
-    """
-    Analyze typography tokens to detect type scale ratio.
-    
-    Args:
-        typography_tokens: Dict of typography tokens with font_size
-        
-    Returns:
-        TypeScaleAnalysis with detected ratio and recommendations
-    """
-    # Extract and parse sizes
-    sizes = []
-    for name, token in typography_tokens.items():
-        if isinstance(token, dict):
-            size = token.get("font_size") or token.get("fontSize") or token.get("size")
-        else:
-            size = getattr(token, "font_size", None)
-        
-        if size:
-            px = parse_size_to_px(size)
-            if px and px > 0:
-                sizes.append(px)
-    
-    # Sort and dedupe
-    sizes_px = sorted(set(sizes))
-    
-    if len(sizes_px) < 2:
-        base_size = sizes_px[0] if sizes_px else 16.0
-        return TypeScaleAnalysis(
-            detected_ratio=1.0,
-            closest_standard_ratio=1.25,
-            scale_name="Unknown",
-            is_consistent=False,
-            variance=0,
-            sizes_px=sizes_px,
-            ratios_between_sizes=[],
-            recommendation=1.25,
-            recommendation_name="Major Third",
-            base_size=base_size,
-        )
-    
-    # Calculate ratios between consecutive sizes
-    ratios = []
-    for i in range(len(sizes_px) - 1):
-        if sizes_px[i] > 0:
-            ratio = sizes_px[i + 1] / sizes_px[i]
-            if 1.0 < ratio < 3.0:  # Reasonable range
-                ratios.append(ratio)
-    
-    if not ratios:
-        # Detect base size even if no valid ratios
-        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,
-            scale_name="Unknown",
-            is_consistent=False,
-            variance=0,
-            sizes_px=sizes_px,
-            ratios_between_sizes=[],
-            recommendation=1.25,
-            recommendation_name="Major Third",
-            base_size=base_size,
-        )
-    
-    # Average ratio
-    avg_ratio = sum(ratios) / len(ratios)
-    
-    # Variance (consistency check)
-    variance = max(ratios) - min(ratios) if ratios else 0
-    is_consistent = variance < 0.15  # Within 15% variance is "consistent"
-    
-    # Find closest standard scale
-    closest_scale = min(STANDARD_SCALES.keys(), key=lambda x: abs(x - avg_ratio))
-    scale_name = STANDARD_SCALES[closest_scale]
-    
-    # Detect base size (closest to 16px, or 14-18px range typical for body)
-    # The base size is typically the most common body text size
-    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 sizes_px:
-        # Fallback: find size closest to 16px
-        base_size = min(sizes_px, key=lambda x: abs(x - 16))
-    else:
-        base_size = 16.0
-    
-    # Recommendation
-    if is_consistent and abs(avg_ratio - closest_scale) < 0.05:
-        # Already using a standard scale
-        recommendation = closest_scale
-        recommendation_name = scale_name
-    else:
-        # Recommend Major Third (1.25) as default
-        recommendation = 1.25
-        recommendation_name = "Major Third"
-    
-    return TypeScaleAnalysis(
-        detected_ratio=avg_ratio,
-        closest_standard_ratio=closest_scale,
-        scale_name=scale_name,
-        is_consistent=is_consistent,
-        variance=variance,
-        sizes_px=sizes_px,
-        ratios_between_sizes=ratios,
-        recommendation=recommendation,
-        recommendation_name=recommendation_name,
-        base_size=base_size,
-    )
-
-
-# =============================================================================
-# ACCESSIBILITY ANALYSIS
-# =============================================================================
-
-def analyze_accessibility(color_tokens: dict, fg_bg_pairs: list[dict] = None) -> list[ColorAccessibility]:
-    """
-    Analyze all colors for WCAG accessibility compliance.
-
-    Args:
-        color_tokens: Dict of color tokens with value/hex
-        fg_bg_pairs: Optional list of actual foreground/background pairs
-                     extracted from the DOM (each dict has 'foreground',
-                     'background', 'element' keys).
-
-    Returns:
-        List of ColorAccessibility results
-    """
-    results = []
-
-    for name, token in color_tokens.items():
-        if isinstance(token, dict):
-            hex_color = token.get("value") or token.get("hex") or token.get("color")
-        else:
-            hex_color = getattr(token, "value", None)
-
-        if not hex_color or not hex_color.startswith("#"):
-            continue
-
-        try:
-            contrast_white = get_contrast_ratio(hex_color, "#ffffff")
-            contrast_black = get_contrast_ratio(hex_color, "#000000")
-
-            passes_aa_normal = contrast_white >= 4.5 or contrast_black >= 4.5
-            passes_aa_large = contrast_white >= 3.0 or contrast_black >= 3.0
-            passes_aaa_normal = contrast_white >= 7.0 or contrast_black >= 7.0
-
-            best_text = "#ffffff" if contrast_white > contrast_black else "#000000"
-
-            # Generate fix suggestion if needed
-            suggested_fix = None
-            suggested_fix_contrast = None
-
-            if not passes_aa_normal:
-                suggested_fix = find_aa_compliant_color(hex_color, "#ffffff", 4.5)
-                suggested_fix_contrast = get_contrast_ratio(suggested_fix, "#ffffff")
-
-            results.append(ColorAccessibility(
-                hex_color=hex_color,
-                name=name,
-                contrast_on_white=contrast_white,
-                contrast_on_black=contrast_black,
-                passes_aa_normal=passes_aa_normal,
-                passes_aa_large=passes_aa_large,
-                passes_aaa_normal=passes_aaa_normal,
-                best_text_color=best_text,
-                suggested_fix=suggested_fix,
-                suggested_fix_contrast=suggested_fix_contrast,
-            ))
-        except Exception:
-            continue
-
-    # --- Real foreground-background pair checks ---
-    if fg_bg_pairs:
-        for pair in fg_bg_pairs:
-            fg = pair.get("foreground", "").lower()
-            bg = pair.get("background", "").lower()
-            element = pair.get("element", "")
-            if not (fg.startswith("#") and bg.startswith("#")):
-                continue
-            # Skip same-color pairs (invisible/placeholder text — not real failures)
-            if fg == bg:
-                continue
-            try:
-                ratio = get_contrast_ratio(fg, bg)
-                # Skip near-identical pairs (ratio < 1.1) — likely decorative/hidden
-                if ratio < 1.1:
-                    continue
-                if ratio < 4.5:
-                    # This pair fails AA — record it
-                    fix = find_aa_compliant_color(fg, bg, 4.5)
-                    fix_contrast = get_contrast_ratio(fix, bg)
-                    results.append(ColorAccessibility(
-                        hex_color=fg,
-                        name=f"fg:{fg} on bg:{bg} ({element}) [{ratio:.1f}:1]",
-                        contrast_on_white=get_contrast_ratio(fg, "#ffffff"),
-                        contrast_on_black=get_contrast_ratio(fg, "#000000"),
-                        passes_aa_normal=False,
-                        passes_aa_large=ratio >= 3.0,
-                        passes_aaa_normal=False,
-                        best_text_color="#ffffff" if get_contrast_ratio(fg, "#ffffff") > get_contrast_ratio(fg, "#000000") else "#000000",
-                        suggested_fix=fix,
-                        suggested_fix_contrast=fix_contrast,
-                    ))
-            except Exception:
-                continue
-
-    return results
-
-
-# =============================================================================
-# SPACING GRID ANALYSIS
-# =============================================================================
-
-def analyze_spacing_grid(spacing_tokens: dict) -> SpacingGridAnalysis:
-    """
-    Analyze spacing tokens to detect grid alignment.
-    
-    Args:
-        spacing_tokens: Dict of spacing tokens with value_px or value
-        
-    Returns:
-        SpacingGridAnalysis with detected grid and recommendations
-    """
-    values = []
-    
-    for name, token in spacing_tokens.items():
-        if isinstance(token, dict):
-            px = token.get("value_px") or token.get("value")
-        else:
-            px = getattr(token, "value_px", None) or getattr(token, "value", None)
-        
-        if px:
-            try:
-                px_val = int(float(str(px).replace('px', '')))
-                if px_val > 0:
-                    values.append(px_val)
-            except (ValueError, TypeError):
-                continue
-    
-    if not values:
-        return SpacingGridAnalysis(
-            detected_base=8,
-            is_aligned=False,
-            alignment_percentage=0,
-            misaligned_values=[],
-            recommendation=8,
-            recommendation_reason="No spacing values detected, defaulting to 8px grid",
-            current_values=[],
-            suggested_scale=[0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64],
-        )
-    
-    values = sorted(set(values))
-    
-    # Find GCD (greatest common divisor) of all values
-    detected_base = reduce(gcd, values)
-    
-    # Check alignment to common grids (4px, 8px)
-    aligned_to_4 = all(v % 4 == 0 for v in values)
-    aligned_to_8 = all(v % 8 == 0 for v in values)
-    
-    # Find misaligned values (not divisible by detected base)
-    misaligned = [v for v in values if v % detected_base != 0] if detected_base > 1 else values
-    
-    alignment_percentage = (len(values) - len(misaligned)) / len(values) * 100 if values else 0
-    
-    # Determine recommendation
-    if aligned_to_8:
-        recommendation = 8
-        recommendation_reason = "All values already align to 8px grid"
-        is_aligned = True
-    elif aligned_to_4:
-        recommendation = 4
-        recommendation_reason = "Values align to 4px grid (consider 8px for simpler system)"
-        is_aligned = True
-    elif detected_base in [4, 8]:
-        recommendation = detected_base
-        recommendation_reason = f"Detected {detected_base}px base with {alignment_percentage:.0f}% alignment"
-        is_aligned = alignment_percentage >= 80
-    else:
-        recommendation = 8
-        recommendation_reason = f"Inconsistent spacing detected (GCD={detected_base}), recommend 8px grid"
-        is_aligned = False
-    
-    # Generate suggested scale
-    base = recommendation
-    suggested_scale = [0] + [base * i for i in [0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10, 12, 16] if base * i == int(base * i)]
-    suggested_scale = sorted(set([int(v) for v in suggested_scale]))
-    
-    return SpacingGridAnalysis(
-        detected_base=detected_base,
-        is_aligned=is_aligned,
-        alignment_percentage=alignment_percentage,
-        misaligned_values=misaligned,
-        recommendation=recommendation,
-        recommendation_reason=recommendation_reason,
-        current_values=values,
-        suggested_scale=suggested_scale,
-    )
-
-
-# =============================================================================
-# COLOR STATISTICS
-# =============================================================================
-
-def analyze_color_statistics(color_tokens: dict, similarity_threshold: float = 0.05) -> ColorStatistics:
-    """
-    Analyze color palette statistics.
-    
-    Args:
-        color_tokens: Dict of color tokens
-        similarity_threshold: Distance threshold for "near duplicate" (0-1)
-        
-    Returns:
-        ColorStatistics with palette analysis
-    """
-    colors = []
-    
-    for name, token in color_tokens.items():
-        if isinstance(token, dict):
-            hex_color = token.get("value") or token.get("hex")
-        else:
-            hex_color = getattr(token, "value", None)
-        
-        if hex_color and hex_color.startswith("#"):
-            colors.append(hex_color.lower())
-    
-    unique_colors = list(set(colors))
-    
-    # Count grays and saturated
-    grays = [c for c in unique_colors if is_gray(c)]
-    saturated = [c for c in unique_colors if get_saturation(c) > 0.3]
-    
-    # Find near duplicates
-    near_duplicates = []
-    for i, c1 in enumerate(unique_colors):
-        for c2 in unique_colors[i+1:]:
-            dist = color_distance(c1, c2)
-            if dist < similarity_threshold and dist > 0:
-                near_duplicates.append((c1, c2, round(dist, 4)))
-    
-    # Hue distribution
-    hue_dist = {}
-    for c in unique_colors:
-        hue = get_hue_name(c)
-        hue_dist[hue] = hue_dist.get(hue, 0) + 1
-    
-    return ColorStatistics(
-        total_count=len(colors),
-        unique_count=len(unique_colors),
-        duplicate_count=len(colors) - len(unique_colors),
-        gray_count=len(grays),
-        saturated_count=len(saturated),
-        near_duplicates=near_duplicates,
-        hue_distribution=hue_dist,
-    )
-
-
-# =============================================================================
-# MAIN ANALYSIS FUNCTION
-# =============================================================================
-
-def run_rule_engine(
-    typography_tokens: dict,
-    color_tokens: dict,
-    spacing_tokens: dict,
-    radius_tokens: dict = None,
-    shadow_tokens: dict = None,
-    log_callback: Optional[callable] = None,
-    fg_bg_pairs: list[dict] = None,
-) -> RuleEngineResults:
-    """
-    Run complete rule-based analysis on design tokens.
-    
-    This is FREE (no LLM costs) and handles all deterministic calculations.
-    
-    Args:
-        typography_tokens: Dict of typography tokens
-        color_tokens: Dict of color tokens  
-        spacing_tokens: Dict of spacing tokens
-        radius_tokens: Dict of border radius tokens (optional)
-        shadow_tokens: Dict of shadow tokens (optional)
-        log_callback: Function to log messages
-        
-    Returns:
-        RuleEngineResults with all analysis data
-    """
-    
-    def log(msg: str):
-        if log_callback:
-            log_callback(msg)
-    
-    log("")
-    log("═" * 60)
-    log("⚙️  LAYER 1: RULE ENGINE (FREE - $0.00)")
-    log("═" * 60)
-    log("")
-    
-    # ─────────────────────────────────────────────────────────────
-    # Typography Analysis
-    # ─────────────────────────────────────────────────────────────
-    log("   📐 TYPE SCALE ANALYSIS")
-    log("   " + "─" * 40)
-    typography = analyze_type_scale(typography_tokens)
-    
-    consistency_icon = "✅" if typography.is_consistent else "⚠️"
-    log(f"   ├─ Detected Ratio: {typography.detected_ratio:.3f}")
-    log(f"   ├─ Closest Standard: {typography.scale_name} ({typography.closest_standard_ratio})")
-    log(f"   ├─ Consistent: {consistency_icon} {'Yes' if typography.is_consistent else f'No (variance: {typography.variance:.2f})'}")
-    log(f"   ├─ Sizes Found: {typography.sizes_px}")
-    log(f"   └─ 💡 Recommendation: {typography.recommendation} ({typography.recommendation_name})")
-    log("")
-    
-    # ─────────────────────────────────────────────────────────────
-    # Accessibility Analysis  
-    # ─────────────────────────────────────────────────────────────
-    log("   ♿ ACCESSIBILITY CHECK (WCAG AA/AAA)")
-    log("   " + "─" * 40)
-    accessibility = analyze_accessibility(color_tokens, fg_bg_pairs=fg_bg_pairs)
-    
-    # Separate individual-color failures from real FG/BG pair failures
-    pair_failures = [a for a in accessibility if not a.passes_aa_normal and a.name.startswith("fg:")]
-    color_only_failures = [a for a in accessibility if not a.passes_aa_normal and not a.name.startswith("fg:")]
-    failures = [a for a in accessibility if not a.passes_aa_normal]
-    passes = len(accessibility) - len(failures)
-
-    pair_count = len(fg_bg_pairs) if fg_bg_pairs else 0
-    log(f"   ├─ Colors Analyzed: {len(accessibility)}")
-    log(f"   ├─ FG/BG Pairs Checked: {pair_count}")
-    log(f"   ├─ AA Pass: {passes} ✅")
-    log(f"   ├─ AA Fail (color vs white/black): {len(color_only_failures)} {'❌' if color_only_failures else '✅'}")
-    log(f"   ├─ AA Fail (real FG/BG pairs): {len(pair_failures)} {'❌' if pair_failures else '✅'}")
-
-    if color_only_failures:
-        log("   │")
-        log("   │  ⚠️  FAILING COLORS (vs white/black):")
-        for i, f in enumerate(color_only_failures[:5]):
-            fix_info = f" → 💡 Fix: {f.suggested_fix} ({f.suggested_fix_contrast:.1f}:1)" if f.suggested_fix else ""
-            log(f"   │  ├─ {f.name}: {f.hex_color} ({f.contrast_on_white:.1f}:1 on white){fix_info}")
-        if len(color_only_failures) > 5:
-            log(f"   │  └─ ... and {len(color_only_failures) - 5} more")
-
-    if pair_failures:
-        log("   │")
-        log("   │  ❌ FAILING FG/BG PAIRS (actual on-page combinations):")
-        for i, f in enumerate(pair_failures[:5]):
-            fix_info = f" → 💡 Fix: {f.suggested_fix} ({f.suggested_fix_contrast:.1f}:1)" if f.suggested_fix else ""
-            log(f"   │  ├─ {f.name}{fix_info}")
-        if len(pair_failures) > 5:
-            log(f"   │  └─ ... and {len(pair_failures) - 5} more")
-    
-    log("")
-    
-    # ─────────────────────────────────────────��───────────────────
-    # Spacing Grid Analysis
-    # ─────────────────────────────────────────────────────────────
-    log("   📏 SPACING GRID ANALYSIS")
-    log("   " + "─" * 40)
-    spacing = analyze_spacing_grid(spacing_tokens)
-    
-    alignment_icon = "✅" if spacing.is_aligned else "⚠️"
-    log(f"   ├─ Detected Base: {spacing.detected_base}px")
-    log(f"   ├─ Grid Aligned: {alignment_icon} {spacing.alignment_percentage:.0f}%")
-    
-    if spacing.misaligned_values:
-        log(f"   ├─ Misaligned Values: {spacing.misaligned_values[:8]}{'...' if len(spacing.misaligned_values) > 8 else ''}")
-    
-    log(f"   ├─ Suggested Scale: {spacing.suggested_scale[:10]}...")
-    log(f"   └─ 💡 Recommendation: {spacing.recommendation}px ({spacing.recommendation_reason})")
-    log("")
-    
-    # ─────────────────────────────────────────────────────────────
-    # Color Statistics
-    # ─────────────────────────────────────────────────────────────
-    log("   🎨 COLOR PALETTE STATISTICS")
-    log("   " + "─" * 40)
-    color_stats = analyze_color_statistics(color_tokens)
-    
-    dup_icon = "⚠️" if color_stats.duplicate_count > 10 else "✅"
-    unique_icon = "⚠️" if color_stats.unique_count > 30 else "✅"
-    
-    log(f"   ├─ Total Colors: {color_stats.total_count}")
-    log(f"   ├─ Unique Colors: {color_stats.unique_count} {unique_icon}")
-    log(f"   ├─ Exact Duplicates: {color_stats.duplicate_count} {dup_icon}")
-    log(f"   ├─ Near-Duplicates: {len(color_stats.near_duplicates)}")
-    log(f"   ├─ Grays: {color_stats.gray_count} | Saturated: {color_stats.saturated_count}")
-    log(f"   └─ Hue Distribution: {dict(list(color_stats.hue_distribution.items())[:5])}...")
-    log("")
-    
-    # ─────────────────────────────────────────────────────────────
-    # Calculate Summary Scores
-    # ─────────────────────────────────────────────────────────────
-    
-    # Consistency score (0-100)
-    type_score = 25 if typography.is_consistent else 10
-    aa_score = 25 * (passes / max(len(accessibility), 1))
-    spacing_score = 25 * (spacing.alignment_percentage / 100)
-    color_score = 25 * (1 - min(color_stats.duplicate_count / max(color_stats.total_count, 1), 1))
-    
-    consistency_score = int(type_score + aa_score + spacing_score + color_score)
-    
-    log("   " + "─" * 40)
-    log(f"   📊 RULE ENGINE SUMMARY")
-    log(f"   ├─ Consistency Score: {consistency_score}/100")
-    log(f"   ├─ AA Failures: {len(failures)}")
-    log(f"   └─ Cost: $0.00 (free)")
-    log("")
-    
-    return RuleEngineResults(
-        typography=typography,
-        accessibility=accessibility,
-        spacing=spacing,
-        color_stats=color_stats,
-        aa_failures=len(failures),
-        consistency_score=consistency_score,
-    )