Upload 2 files

agents/extractor.py

@@ -0,0 +1,1229 @@
+"""
+Agent 1: Token Extractor
+Design System Extractor v2
+
+Persona: Meticulous Design Archaeologist
+
+Responsibilities:
+- Crawl pages at specified viewport
+- Extract computed styles from all elements
+- Parse CSS files for variables and rules
+- Extract colors from SVGs
+- Collect colors, typography, spacing, radius, shadows
+- Track frequency and context for each token
+"""
+
+import asyncio
+import re
+from typing import Optional, Callable
+from datetime import datetime
+from collections import defaultdict
+
+from playwright.async_api import async_playwright, Browser, Page, BrowserContext
+
+from core.token_schema import (
+    Viewport,
+    ExtractedTokens,
+    ColorToken,
+    TypographyToken,
+    SpacingToken,
+    RadiusToken,
+    ShadowToken,
+    FontFamily,
+    TokenSource,
+    Confidence,
+)
+from core.color_utils import (
+    normalize_hex,
+    parse_color,
+    get_contrast_with_white,
+    get_contrast_with_black,
+    check_wcag_compliance,
+)
+from config.settings import get_settings
+
+
+class TokenExtractor:
+    """
+    Extracts design tokens from web pages.
+    
+    This is the second part of Agent 1's job — after pages are confirmed,
+    we crawl and extract all CSS values.
+    
+    Enhanced with:
+    - CSS file parsing for variables and rules
+    - SVG color extraction
+    - Inline style extraction
+    """
+    
+    def __init__(self, viewport: Viewport = Viewport.DESKTOP):
+        self.settings = get_settings()
+        self.viewport = viewport
+        self.browser: Optional[Browser] = None
+        self.context: Optional[BrowserContext] = None
+        
+        # Token collection
+        self.colors: dict[str, ColorToken] = {}
+        self.typography: dict[str, TypographyToken] = {}
+        self.spacing: dict[str, SpacingToken] = {}
+        self.radius: dict[str, RadiusToken] = {}
+        self.shadows: dict[str, ShadowToken] = {}
+
+        # Foreground-background pairs extracted from actual DOM elements
+        self.fg_bg_pairs: list[dict] = []
+
+        # CSS Variables collection
+        self.css_variables: dict[str, str] = {}
+
+        # Font tracking
+        self.font_families: dict[str, FontFamily] = {}
+
+        # Statistics
+        self.total_elements = 0
+        self.errors: list[str] = []
+        self.warnings: list[str] = []
+    
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self._init_browser()
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self._close_browser()
+    
+    async def _init_browser(self):
+        """Initialize Playwright browser."""
+        playwright = await async_playwright().start()
+        self.browser = await playwright.chromium.launch(
+            headless=self.settings.browser.headless
+        )
+        
+        # Set viewport based on extraction mode
+        if self.viewport == Viewport.DESKTOP:
+            width = self.settings.viewport.desktop_width
+            height = self.settings.viewport.desktop_height
+        else:
+            width = self.settings.viewport.mobile_width
+            height = self.settings.viewport.mobile_height
+        
+        self.context = await self.browser.new_context(
+            viewport={"width": width, "height": height},
+            user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
+        )
+    
+    async def _close_browser(self):
+        """Close browser and cleanup."""
+        if self.context:
+            await self.context.close()
+        if self.browser:
+            await self.browser.close()
+    
+    async def _scroll_page(self, page: Page):
+        """Scroll page to load lazy content."""
+        await page.evaluate("""
+            async () => {
+                const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+                const height = document.body.scrollHeight;
+                const step = window.innerHeight;
+                
+                for (let y = 0; y < height; y += step) {
+                    window.scrollTo(0, y);
+                    await delay(100);
+                }
+                
+                // Scroll back to top
+                window.scrollTo(0, 0);
+            }
+        """)
+        
+        # Wait for network idle after scrolling
+        await page.wait_for_load_state("networkidle", timeout=self.settings.browser.network_idle_timeout)
+    
+    async def _extract_styles_from_page(self, page: Page) -> dict:
+        """
+        Extract computed styles from all elements on the page.
+        
+        This is the core extraction logic — we get getComputedStyle for every element.
+        """
+        styles_data = await page.evaluate("""
+            () => {
+                const elements = document.querySelectorAll('*');
+                const results = {
+                    colors: [],
+                    typography: [],
+                    spacing: [],
+                    radius: [],
+                    shadows: [],
+                    elements_count: elements.length,
+                };
+                
+                const colorProperties = [
+                    'color', 'background-color', 'border-color',
+                    'border-top-color', 'border-right-color', 
+                    'border-bottom-color', 'border-left-color',
+                    'outline-color', 'text-decoration-color',
+                ];
+                
+                const spacingProperties = [
+                    'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+                    'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+                    'gap', 'row-gap', 'column-gap',
+                ];
+                
+                elements.forEach(el => {
+                    const tag = el.tagName.toLowerCase();
+                    const styles = window.getComputedStyle(el);
+                    
+                    // Skip invisible elements
+                    if (styles.display === 'none' || styles.visibility === 'hidden') {
+                        return;
+                    }
+                    
+                    // --- COLORS ---
+                    colorProperties.forEach(prop => {
+                        const value = styles.getPropertyValue(prop);
+                        if (value && value !== 'rgba(0, 0, 0, 0)' && value !== 'transparent') {
+                            results.colors.push({
+                                value: value,
+                                property: prop,
+                                element: tag,
+                                context: prop.includes('background') ? 'background' : 
+                                        prop.includes('border') ? 'border' : 'text',
+                            });
+                        }
+                    });
+                    
+                    // --- TYPOGRAPHY ---
+                    const fontFamily = styles.getPropertyValue('font-family');
+                    const fontSize = styles.getPropertyValue('font-size');
+                    const fontWeight = styles.getPropertyValue('font-weight');
+                    const lineHeight = styles.getPropertyValue('line-height');
+                    const letterSpacing = styles.getPropertyValue('letter-spacing');
+                    
+                    if (fontSize && fontFamily) {
+                        results.typography.push({
+                            fontFamily: fontFamily,
+                            fontSize: fontSize,
+                            fontWeight: fontWeight,
+                            lineHeight: lineHeight,
+                            letterSpacing: letterSpacing,
+                            element: tag,
+                        });
+                    }
+                    
+                    // --- SPACING ---
+                    spacingProperties.forEach(prop => {
+                        const value = styles.getPropertyValue(prop);
+                        if (value && value !== '0px' && value !== 'auto' && value !== 'normal') {
+                            const px = parseFloat(value);
+                            if (!isNaN(px) && px > 0 && px < 500) {
+                                results.spacing.push({
+                                    value: value,
+                                    valuePx: Math.round(px),
+                                    property: prop,
+                                    context: prop.includes('margin') ? 'margin' : 
+                                            prop.includes('padding') ? 'padding' : 'gap',
+                                });
+                            }
+                        }
+                    });
+                    
+                    // --- BORDER RADIUS ---
+                    const radiusProps = [
+                        'border-radius', 'border-top-left-radius', 
+                        'border-top-right-radius', 'border-bottom-left-radius',
+                        'border-bottom-right-radius',
+                    ];
+                    
+                    radiusProps.forEach(prop => {
+                        const value = styles.getPropertyValue(prop);
+                        if (value && value !== '0px') {
+                            results.radius.push({
+                                value: value,
+                                element: tag,
+                            });
+                        }
+                    });
+                    
+                    // --- BOX SHADOW ---
+                    const shadow = styles.getPropertyValue('box-shadow');
+                    if (shadow && shadow !== 'none') {
+                        results.shadows.push({
+                            value: shadow,
+                            element: tag,
+                        });
+                    }
+                });
+                
+                return results;
+            }
+        """)
+        
+        return styles_data
+
+    async def _extract_fg_bg_pairs(self, page: Page) -> list[dict]:
+        """
+        Extract actual foreground-background color pairs from visible DOM elements.
+
+        For each visible element that has a non-transparent text color, walk up the
+        ancestor chain to find the effective background color.  This gives us real
+        foreground/background pairs so we can do accurate WCAG AA checks instead of
+        only comparing every color against white/black.
+        """
+        pairs = await page.evaluate("""
+            () => {
+                const pairs = [];
+                const seen = new Set();
+
+                function rgbToHex(rgb) {
+                    if (!rgb || rgb === 'transparent' || rgb === 'rgba(0, 0, 0, 0)') return null;
+                    const match = rgb.match(/rgba?\\((\\d+),\\s*(\\d+),\\s*(\\d+)/);
+                    if (!match) return null;
+                    const r = parseInt(match[1]);
+                    const g = parseInt(match[2]);
+                    const b = parseInt(match[3]);
+                    return '#' + [r, g, b].map(c => c.toString(16).padStart(2, '0')).join('');
+                }
+
+                function getEffectiveBackground(el) {
+                    let current = el;
+                    while (current && current !== document.documentElement) {
+                        const bg = window.getComputedStyle(current).backgroundColor;
+                        if (bg && bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent') {
+                            return rgbToHex(bg);
+                        }
+                        current = current.parentElement;
+                    }
+                    return '#ffffff';  // default page background
+                }
+
+                const elements = document.querySelectorAll('*');
+                elements.forEach(el => {
+                    const styles = window.getComputedStyle(el);
+                    if (styles.display === 'none' || styles.visibility === 'hidden') return;
+
+                    const fg = rgbToHex(styles.color);
+                    if (!fg) return;
+
+                    const bg = getEffectiveBackground(el);
+                    if (!bg) return;
+
+                    const key = fg + '|' + bg;
+                    if (seen.has(key)) return;
+                    seen.add(key);
+
+                    pairs.push({
+                        foreground: fg,
+                        background: bg,
+                        element: el.tagName.toLowerCase(),
+                    });
+                });
+
+                return pairs;
+            }
+        """)
+        return pairs or []
+
+    async def _extract_css_variables(self, page: Page) -> dict:
+        """
+        Extract CSS custom properties (variables) from :root and stylesheets.
+        
+        This catches colors defined as:
+        - :root { --primary-color: #3860be; }
+        - :root { --brand-cyan: #00c4cc; }
+        """
+        css_vars = await page.evaluate("""
+            () => {
+                const variables = {};
+                
+                // 1. Get CSS variables from :root computed styles
+                const rootStyles = getComputedStyle(document.documentElement);
+                const rootCss = document.documentElement.style.cssText;
+                
+                // 2. Parse all stylesheets for CSS variables
+                for (const sheet of document.styleSheets) {
+                    try {
+                        const rules = sheet.cssRules || sheet.rules;
+                        for (const rule of rules) {
+                            if (rule.style) {
+                                for (let i = 0; i < rule.style.length; i++) {
+                                    const prop = rule.style[i];
+                                    if (prop.startsWith('--')) {
+                                        const value = rule.style.getPropertyValue(prop).trim();
+                                        if (value) {
+                                            variables[prop] = value;
+                                        }
+                                    }
+                                }
+                            }
+                            // Also check @media rules
+                            if (rule.cssRules) {
+                                for (const innerRule of rule.cssRules) {
+                                    if (innerRule.style) {
+                                        for (let i = 0; i < innerRule.style.length; i++) {
+                                            const prop = innerRule.style[i];
+                                            if (prop.startsWith('--')) {
+                                                const value = innerRule.style.getPropertyValue(prop).trim();
+                                                if (value) {
+                                                    variables[prop] = value;
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    } catch (e) {
+                        // CORS may block access to external stylesheets
+                        console.log('Could not access stylesheet:', e);
+                    }
+                }
+                
+                // 3. Get computed CSS variable values from :root
+                const computedVars = {};
+                for (const prop of Object.keys(variables)) {
+                    const computed = rootStyles.getPropertyValue(prop).trim();
+                    if (computed) {
+                        computedVars[prop] = computed;
+                    }
+                }
+                
+                return { raw: variables, computed: computedVars };
+            }
+        """)
+        
+        return css_vars
+    
+    async def _extract_svg_colors(self, page: Page) -> list[dict]:
+        """
+        Extract colors from SVG elements (fill, stroke).
+        
+        This catches colors in:
+        - <svg fill="#00c4cc">
+        - <path stroke="#3860be">
+        - <circle fill="rgb(188, 212, 50)">
+        """
+        svg_colors = await page.evaluate("""
+            () => {
+                const colors = [];
+                
+                // Find all SVG elements
+                const svgs = document.querySelectorAll('svg, svg *');
+                
+                svgs.forEach(el => {
+                    // Check fill attribute
+                    const fill = el.getAttribute('fill');
+                    if (fill && fill !== 'none' && fill !== 'currentColor' && !fill.startsWith('url(')) {
+                        colors.push({
+                            value: fill,
+                            property: 'svg-fill',
+                            element: el.tagName.toLowerCase(),
+                            context: 'svg',
+                        });
+                    }
+                    
+                    // Check stroke attribute
+                    const stroke = el.getAttribute('stroke');
+                    if (stroke && stroke !== 'none' && stroke !== 'currentColor' && !stroke.startsWith('url(')) {
+                        colors.push({
+                            value: stroke,
+                            property: 'svg-stroke',
+                            element: el.tagName.toLowerCase(),
+                            context: 'svg',
+                        });
+                    }
+                    
+                    // Check computed styles for SVG elements
+                    const styles = getComputedStyle(el);
+                    const computedFill = styles.fill;
+                    const computedStroke = styles.stroke;
+                    
+                    if (computedFill && computedFill !== 'none' && !computedFill.startsWith('url(')) {
+                        colors.push({
+                            value: computedFill,
+                            property: 'svg-fill-computed',
+                            element: el.tagName.toLowerCase(),
+                            context: 'svg',
+                        });
+                    }
+                    
+                    if (computedStroke && computedStroke !== 'none' && !computedStroke.startsWith('url(')) {
+                        colors.push({
+                            value: computedStroke,
+                            property: 'svg-stroke-computed',
+                            element: el.tagName.toLowerCase(),
+                            context: 'svg',
+                        });
+                    }
+                });
+                
+                return colors;
+            }
+        """)
+        
+        return svg_colors
+    
+    async def _extract_inline_styles(self, page: Page) -> dict:
+        """
+        Extract colors from inline style attributes.
+        
+        This catches colors in:
+        - <div style="background-color: #bcd432;">
+        - <span style="color: rgb(0, 196, 204);">
+        """
+        inline_data = await page.evaluate("""
+            () => {
+                const colors = [];
+                const colorRegex = /#[0-9a-fA-F]{3,8}|rgb\\([^)]+\\)|rgba\\([^)]+\\)|hsl\\([^)]+\\)|hsla\\([^)]+\\)/gi;
+                
+                // Find all elements with inline styles
+                const elements = document.querySelectorAll('[style]');
+                
+                elements.forEach(el => {
+                    const styleAttr = el.getAttribute('style');
+                    if (styleAttr) {
+                        const matches = styleAttr.match(colorRegex);
+                        if (matches) {
+                            matches.forEach(color => {
+                                colors.push({
+                                    value: color,
+                                    property: 'inline-style',
+                                    element: el.tagName.toLowerCase(),
+                                    context: 'inline',
+                                });
+                            });
+                        }
+                    }
+                });
+                
+                return colors;
+            }
+        """)
+        
+        return inline_data
+    
+    async def _extract_stylesheet_colors(self, page: Page) -> list[dict]:
+        """
+        Parse CSS stylesheets for color values.
+        
+        This catches colors defined in CSS rules that may not be
+        currently applied to visible elements.
+        
+        Also fetches external stylesheets that may be CORS-blocked.
+        """
+        css_colors = await page.evaluate("""
+            () => {
+                const colors = [];
+                const colorRegex = /#[0-9a-fA-F]{3,8}|rgb\\([^)]+\\)|rgba\\([^)]+\\)|hsl\\([^)]+\\)|hsla\\([^)]+\\)/gi;
+                
+                // Color-related CSS properties
+                const colorProps = [
+                    'color', 'background-color', 'background', 'border-color',
+                    'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
+                    'outline-color', 'box-shadow', 'text-shadow', 'fill', 'stroke',
+                    'caret-color', 'column-rule-color', 'text-decoration-color',
+                ];
+                
+                // Parse all stylesheets
+                for (const sheet of document.styleSheets) {
+                    try {
+                        const rules = sheet.cssRules || sheet.rules;
+                        for (const rule of rules) {
+                            if (rule.style) {
+                                colorProps.forEach(prop => {
+                                    const value = rule.style.getPropertyValue(prop);
+                                    if (value) {
+                                        const matches = value.match(colorRegex);
+                                        if (matches) {
+                                            matches.forEach(color => {
+                                                colors.push({
+                                                    value: color,
+                                                    property: prop,
+                                                    element: 'css-rule',
+                                                    context: 'stylesheet',
+                                                    selector: rule.selectorText || '',
+                                                });
+                                            });
+                                        }
+                                    }
+                                });
+                            }
+                        }
+                    } catch (e) {
+                        // CORS may block access to external stylesheets
+                    }
+                }
+                
+                return colors;
+            }
+        """)
+        
+        return css_colors
+    
+    async def _fetch_external_css_colors(self, page: Page) -> list[dict]:
+        """
+        Fetch and parse external CSS files directly to bypass CORS.
+        
+        This catches colors in external stylesheets that are blocked by CORS.
+        """
+        colors = []
+        
+        try:
+            # Get all stylesheet URLs
+            css_urls = await page.evaluate("""
+                () => {
+                    const urls = [];
+                    const links = document.querySelectorAll('link[rel="stylesheet"]');
+                    links.forEach(link => {
+                        if (link.href) {
+                            urls.push(link.href);
+                        }
+                    });
+                    return urls;
+                }
+            """)
+            
+            # Color regex pattern
+            color_regex = re.compile(r'#[0-9a-fA-F]{3,8}|rgb\([^)]+\)|rgba\([^)]+\)|hsl\([^)]+\)|hsla\([^)]+\)', re.IGNORECASE)
+            
+            # Fetch each CSS file
+            for css_url in css_urls[:10]:  # Limit to 10 files
+                try:
+                    response = await page.request.get(css_url, timeout=5000)
+                    if response.ok:
+                        css_text = await response.text()
+                        
+                        # Find all color values in CSS text
+                        matches = color_regex.findall(css_text)
+                        for match in matches:
+                            colors.append({
+                                "value": match,
+                                "property": "external-css",
+                                "element": "css-file",
+                                "context": "external-stylesheet",
+                            })
+                except Exception as e:
+                    # Skip if fetch fails
+                    pass
+            
+        except Exception as e:
+            self.warnings.append(f"External CSS fetch failed: {str(e)}")
+        
+        return colors
+    
+    async def _extract_all_page_colors(self, page: Page) -> list[dict]:
+        """
+        Extract ALL color values from the page source and styles.
+        
+        This is a brute-force approach that scans the entire page HTML
+        and all style blocks for any color values.
+        """
+        colors = await page.evaluate("""
+            () => {
+                const colors = [];
+                const colorRegex = /#[0-9a-fA-F]{3,8}|rgb\\([^)]+\\)|rgba\\([^)]+\\)|hsl\\([^)]+\\)|hsla\\([^)]+\\)/gi;
+                
+                // 1. Scan all <style> tags
+                const styleTags = document.querySelectorAll('style');
+                styleTags.forEach(style => {
+                    const matches = style.textContent.match(colorRegex);
+                    if (matches) {
+                        matches.forEach(color => {
+                            colors.push({
+                                value: color,
+                                property: 'style-tag',
+                                element: 'style',
+                                context: 'style-block',
+                            });
+                        });
+                    }
+                });
+                
+                // 2. Scan data attributes that might contain colors
+                const allElements = document.querySelectorAll('*');
+                allElements.forEach(el => {
+                    // Check data attributes
+                    for (const attr of el.attributes) {
+                        if (attr.name.startsWith('data-') || attr.name === 'style') {
+                            const matches = attr.value.match(colorRegex);
+                            if (matches) {
+                                matches.forEach(color => {
+                                    colors.push({
+                                        value: color,
+                                        property: attr.name,
+                                        element: el.tagName.toLowerCase(),
+                                        context: 'attribute',
+                                    });
+                                });
+                            }
+                        }
+                    }
+                    
+                    // Check for color in class names (some frameworks use color classes)
+                    const classList = el.className;
+                    if (typeof classList === 'string') {
+                        const colorMatches = classList.match(colorRegex);
+                        if (colorMatches) {
+                            colorMatches.forEach(color => {
+                                colors.push({
+                                    value: color,
+                                    property: 'class',
+                                    element: el.tagName.toLowerCase(),
+                                    context: 'class-name',
+                                });
+                            });
+                        }
+                    }
+                });
+                
+                // 3. Look for colors in script tags (config objects)
+                const scriptTags = document.querySelectorAll('script');
+                scriptTags.forEach(script => {
+                    if (script.textContent && !script.src) {
+                        const matches = script.textContent.match(colorRegex);
+                        if (matches) {
+                            matches.forEach(color => {
+                                colors.push({
+                                    value: color,
+                                    property: 'script',
+                                    element: 'script',
+                                    context: 'javascript',
+                                });
+                            });
+                        }
+                    }
+                });
+                
+                return colors;
+            }
+        """)
+        
+        return colors
+    
+    def _process_css_variables(self, css_vars: dict):
+        """Process CSS variables and extract color tokens from them."""
+        computed = css_vars.get("computed", {})
+        raw = css_vars.get("raw", {})
+        
+        # Store CSS variables
+        self.css_variables = {**raw, **computed}
+        
+        # Extract colors from CSS variables
+        color_regex = re.compile(r'#[0-9a-fA-F]{3,8}|rgb\([^)]+\)|rgba\([^)]+\)|hsl\([^)]+\)|hsla\([^)]+\)', re.IGNORECASE)
+        
+        for var_name, value in computed.items():
+            if color_regex.match(value.strip()):
+                # This is a color variable
+                color_data = {
+                    "value": value.strip(),
+                    "property": var_name,
+                    "element": ":root",
+                    "context": "css-variable",
+                }
+                
+                hex_value = self._process_color(color_data)
+                if hex_value and hex_value not in self.colors:
+                    contrast_white = get_contrast_with_white(hex_value)
+                    contrast_black = get_contrast_with_black(hex_value)
+                    compliance = check_wcag_compliance(hex_value, "#ffffff")
+                    
+                    self.colors[hex_value] = ColorToken(
+                        value=hex_value,
+                        frequency=1,
+                        contexts=["css-variable"],
+                        elements=[":root"],
+                        css_properties=[var_name],
+                        contrast_white=round(contrast_white, 2),
+                        contrast_black=round(contrast_black, 2),
+                        wcag_aa_large_text=compliance["aa_large_text"],
+                        wcag_aa_small_text=compliance["aa_normal_text"],
+                        source=TokenSource.DETECTED,  # CSS variable is still "detected"
+                        confidence=Confidence.HIGH,
+                    )
+                elif hex_value and hex_value in self.colors:
+                    # Update existing token
+                    token = self.colors[hex_value]
+                    token.frequency += 1
+                    if "css-variable" not in token.contexts:
+                        token.contexts.append("css-variable")
+                    if var_name not in token.css_properties:
+                        token.css_properties.append(var_name)
+
+    def _process_color(self, color_data: dict) -> Optional[str]:
+        """Process and normalize a color value."""
+        value = color_data.get("value", "")
+        
+        # Parse and normalize
+        parsed = parse_color(value)
+        if not parsed:
+            return None
+        
+        return parsed.hex
+    
+    def _aggregate_colors(self, raw_colors: list[dict]):
+        """Aggregate color data from extraction."""
+        for color_data in raw_colors:
+            hex_value = self._process_color(color_data)
+            if not hex_value:
+                continue
+            
+            if hex_value not in self.colors:
+                # Calculate contrast ratios
+                contrast_white = get_contrast_with_white(hex_value)
+                contrast_black = get_contrast_with_black(hex_value)
+                compliance = check_wcag_compliance(hex_value, "#ffffff")
+                
+                self.colors[hex_value] = ColorToken(
+                    value=hex_value,
+                    frequency=0,
+                    contexts=[],
+                    elements=[],
+                    css_properties=[],
+                    contrast_white=round(contrast_white, 2),
+                    contrast_black=round(contrast_black, 2),
+                    wcag_aa_large_text=compliance["aa_large_text"],
+                    wcag_aa_small_text=compliance["aa_normal_text"],
+                )
+            
+            # Update frequency and context
+            token = self.colors[hex_value]
+            token.frequency += 1
+            
+            context = color_data.get("context", "")
+            if context and context not in token.contexts:
+                token.contexts.append(context)
+            
+            element = color_data.get("element", "")
+            if element and element not in token.elements:
+                token.elements.append(element)
+            
+            prop = color_data.get("property", "")
+            if prop and prop not in token.css_properties:
+                token.css_properties.append(prop)
+    
+    def _aggregate_typography(self, raw_typography: list[dict]):
+        """Aggregate typography data from extraction."""
+        for typo_data in raw_typography:
+            # Create unique key
+            font_family = typo_data.get("fontFamily", "")
+            font_size = typo_data.get("fontSize", "")
+            font_weight = typo_data.get("fontWeight", "400")
+            line_height = typo_data.get("lineHeight", "normal")
+            
+            key = f"{font_size}|{font_weight}|{font_family[:50]}"
+            
+            if key not in self.typography:
+                # Parse font size to px
+                font_size_px = None
+                if font_size.endswith("px"):
+                    try:
+                        font_size_px = float(font_size.replace("px", ""))
+                    except ValueError:
+                        pass
+                
+                # Parse line height
+                line_height_computed = None
+                if line_height and line_height != "normal":
+                    if line_height.endswith("px") and font_size_px:
+                        try:
+                            lh_px = float(line_height.replace("px", ""))
+                            line_height_computed = round(lh_px / font_size_px, 2)
+                        except ValueError:
+                            pass
+                    else:
+                        try:
+                            line_height_computed = float(line_height)
+                        except ValueError:
+                            pass
+                
+                self.typography[key] = TypographyToken(
+                    font_family=font_family.split(",")[0].strip().strip('"\''),
+                    font_size=font_size,
+                    font_size_px=font_size_px,
+                    font_weight=int(font_weight) if font_weight.isdigit() else 400,
+                    line_height=line_height,
+                    line_height_computed=line_height_computed,
+                    letter_spacing=typo_data.get("letterSpacing"),
+                    frequency=0,
+                    elements=[],
+                )
+            
+            # Update
+            token = self.typography[key]
+            token.frequency += 1
+            
+            element = typo_data.get("element", "")
+            if element and element not in token.elements:
+                token.elements.append(element)
+            
+            # Track font families
+            primary_font = token.font_family
+            if primary_font not in self.font_families:
+                self.font_families[primary_font] = FontFamily(
+                    name=primary_font,
+                    fallbacks=[f.strip().strip('"\'') for f in font_family.split(",")[1:]],
+                    frequency=0,
+                )
+            self.font_families[primary_font].frequency += 1
+    
+    def _aggregate_spacing(self, raw_spacing: list[dict]):
+        """Aggregate spacing data from extraction."""
+        for space_data in raw_spacing:
+            value = space_data.get("value", "")
+            value_px = space_data.get("valuePx", 0)
+            
+            key = str(value_px)
+            
+            if key not in self.spacing:
+                self.spacing[key] = SpacingToken(
+                    value=f"{value_px}px",
+                    value_px=value_px,
+                    frequency=0,
+                    contexts=[],
+                    properties=[],
+                    fits_base_4=value_px % 4 == 0,
+                    fits_base_8=value_px % 8 == 0,
+                )
+            
+            token = self.spacing[key]
+            token.frequency += 1
+            
+            context = space_data.get("context", "")
+            if context and context not in token.contexts:
+                token.contexts.append(context)
+            
+            prop = space_data.get("property", "")
+            if prop and prop not in token.properties:
+                token.properties.append(prop)
+    
+    def _aggregate_radius(self, raw_radius: list[dict]):
+        """Aggregate border radius data."""
+        for radius_data in raw_radius:
+            value = radius_data.get("value", "")
+            
+            # Normalize to simple format
+            # "8px 8px 8px 8px" -> "8px"
+            parts = value.split()
+            if len(set(parts)) == 1:
+                value = parts[0]
+            
+            if value not in self.radius:
+                value_px = None
+                if value.endswith("px"):
+                    try:
+                        value_px = int(float(value.replace("px", "")))
+                    except ValueError:
+                        pass
+                
+                self.radius[value] = RadiusToken(
+                    value=value,
+                    value_px=value_px,
+                    frequency=0,
+                    elements=[],
+                    fits_base_4=value_px % 4 == 0 if value_px else False,
+                    fits_base_8=value_px % 8 == 0 if value_px else False,
+                )
+            
+            token = self.radius[value]
+            token.frequency += 1
+            
+            element = radius_data.get("element", "")
+            if element and element not in token.elements:
+                token.elements.append(element)
+    
+    def _aggregate_shadows(self, raw_shadows: list[dict]):
+        """Aggregate box shadow data."""
+        for shadow_data in raw_shadows:
+            value = shadow_data.get("value", "")
+            
+            if value not in self.shadows:
+                self.shadows[value] = ShadowToken(
+                    value=value,
+                    frequency=0,
+                    elements=[],
+                )
+            
+            token = self.shadows[value]
+            token.frequency += 1
+            
+            element = shadow_data.get("element", "")
+            if element and element not in token.elements:
+                token.elements.append(element)
+    
+    def _calculate_confidence(self, frequency: int) -> Confidence:
+        """Calculate confidence level based on frequency."""
+        if frequency >= 10:
+            return Confidence.HIGH
+        elif frequency >= 3:
+            return Confidence.MEDIUM
+        return Confidence.LOW
+    
+    def _detect_spacing_base(self) -> Optional[int]:
+        """Detect the base spacing unit (4 or 8)."""
+        fits_4 = sum(1 for s in self.spacing.values() if s.fits_base_4)
+        fits_8 = sum(1 for s in self.spacing.values() if s.fits_base_8)
+        
+        total = len(self.spacing)
+        if total == 0:
+            return None
+        
+        # If 80%+ values fit base 8, use 8
+        if fits_8 / total >= 0.8:
+            return 8
+        # If 80%+ values fit base 4, use 4
+        elif fits_4 / total >= 0.8:
+            return 4
+        
+        return None
+    
+    async def extract(
+        self,
+        pages: list[str],
+        progress_callback: Optional[Callable[[float], None]] = None
+    ) -> ExtractedTokens:
+        """
+        Extract tokens from a list of pages.
+        
+        Enhanced extraction includes:
+        - DOM computed styles
+        - CSS variables from :root
+        - SVG fill/stroke colors
+        - Inline style colors
+        - Stylesheet color rules
+        
+        Args:
+            pages: List of URLs to crawl
+            progress_callback: Optional callback for progress updates
+        
+        Returns:
+            ExtractedTokens with all discovered tokens
+        """
+        start_time = datetime.now()
+        pages_crawled = []
+        
+        async with self:
+            for i, url in enumerate(pages):
+                try:
+                    page = await self.context.new_page()
+                    
+                    # Navigate with fallback strategy
+                    try:
+                        await page.goto(
+                            url,
+                            wait_until="domcontentloaded",
+                            timeout=60000  # 60 seconds
+                        )
+                        # Wait for JS to render
+                        await page.wait_for_timeout(2000)
+                    except Exception as nav_error:
+                        # Fallback to load event
+                        try:
+                            await page.goto(
+                                url,
+                                wait_until="load",
+                                timeout=60000
+                            )
+                            await page.wait_for_timeout(3000)
+                        except Exception:
+                            self.warnings.append(f"Slow load for {url}, extracting partial content")
+                    
+                    # Scroll to load lazy content
+                    await self._scroll_page(page)
+                    
+                    # =========================================================
+                    # ENHANCED EXTRACTION: Multiple sources
+                    # =========================================================
+                    
+                    # Track counts before extraction for this page
+                    colors_before = len(self.colors)
+                    typo_before = len(self.typography)
+                    spacing_before = len(self.spacing)
+                    radius_before = len(self.radius)
+                    shadows_before = len(self.shadows)
+                    
+                    # 1. Extract DOM computed styles (original method)
+                    styles = await self._extract_styles_from_page(page)
+                    dom_colors = len(styles.get("colors", []))
+                    self._aggregate_colors(styles.get("colors", []))
+                    self._aggregate_typography(styles.get("typography", []))
+                    self._aggregate_spacing(styles.get("spacing", []))
+                    self._aggregate_radius(styles.get("radius", []))
+                    self._aggregate_shadows(styles.get("shadows", []))
+                    
+                    # 2. Extract CSS variables (--primary-color, etc.)
+                    css_var_count = 0
+                    try:
+                        css_vars = await self._extract_css_variables(page)
+                        css_var_count = len(css_vars.get("computed", {}))
+                        self._process_css_variables(css_vars)
+                    except Exception as e:
+                        self.warnings.append(f"CSS variables extraction failed: {str(e)}")
+                    
+                    # 3. Extract SVG colors (fill, stroke)
+                    svg_color_count = 0
+                    try:
+                        svg_colors = await self._extract_svg_colors(page)
+                        svg_color_count = len(svg_colors)
+                        self._aggregate_colors(svg_colors)
+                    except Exception as e:
+                        self.warnings.append(f"SVG color extraction failed: {str(e)}")
+                    
+                    # 4. Extract inline style colors
+                    inline_color_count = 0
+                    try:
+                        inline_colors = await self._extract_inline_styles(page)
+                        inline_color_count = len(inline_colors)
+                        self._aggregate_colors(inline_colors)
+                    except Exception as e:
+                        self.warnings.append(f"Inline style extraction failed: {str(e)}")
+                    
+                    # 5. Extract stylesheet colors (CSS rules)
+                    stylesheet_color_count = 0
+                    try:
+                        stylesheet_colors = await self._extract_stylesheet_colors(page)
+                        stylesheet_color_count = len(stylesheet_colors)
+                        self._aggregate_colors(stylesheet_colors)
+                    except Exception as e:
+                        self.warnings.append(f"Stylesheet color extraction failed: {str(e)}")
+                    
+                    # 6. Fetch external CSS files (bypass CORS)
+                    external_css_count = 0
+                    try:
+                        external_colors = await self._fetch_external_css_colors(page)
+                        external_css_count = len(external_colors)
+                        self._aggregate_colors(external_colors)
+                    except Exception as e:
+                        self.warnings.append(f"External CSS fetch failed: {str(e)}")
+                    
+                    # 7. Brute-force scan all page content for colors
+                    page_scan_count = 0
+                    try:
+                        page_colors = await self._extract_all_page_colors(page)
+                        page_scan_count = len(page_colors)
+                        self._aggregate_colors(page_colors)
+                    except Exception as e:
+                        self.warnings.append(f"Page scan failed: {str(e)}")
+
+                    # 8. Extract foreground-background color pairs for real AA checks
+                    try:
+                        fg_bg = await self._extract_fg_bg_pairs(page)
+                        self.fg_bg_pairs.extend(fg_bg)
+                    except Exception as e:
+                        self.warnings.append(f"FG/BG pair extraction failed: {str(e)}")
+
+                    # =========================================================
+                    # Log extraction results for this page
+                    # =========================================================
+                    colors_new = len(self.colors) - colors_before
+                    typo_new = len(self.typography) - typo_before
+                    spacing_new = len(self.spacing) - spacing_before
+                    radius_new = len(self.radius) - radius_before
+                    shadows_new = len(self.shadows) - shadows_before
+                    
+                    # Store extraction stats for logging
+                    self._last_extraction_stats = {
+                        "url": url,
+                        "dom_colors": dom_colors,
+                        "css_variables": css_var_count,
+                        "svg_colors": svg_color_count,
+                        "inline_colors": inline_color_count,
+                        "stylesheet_colors": stylesheet_color_count,
+                        "external_css_colors": external_css_count,
+                        "page_scan_colors": page_scan_count,
+                        "new_colors": colors_new,
+                        "new_typography": typo_new,
+                        "new_spacing": spacing_new,
+                        "new_radius": radius_new,
+                        "new_shadows": shadows_new,
+                    }
+                    
+                    # =========================================================
+                    
+                    self.total_elements += styles.get("elements_count", 0)
+                    pages_crawled.append(url)
+                    
+                    await page.close()
+                    
+                    # Progress callback
+                    if progress_callback:
+                        progress_callback((i + 1) / len(pages))
+                    
+                    # Rate limiting
+                    await asyncio.sleep(self.settings.crawl.crawl_delay_ms / 1000)
+                    
+                except Exception as e:
+                    self.errors.append(f"Error extracting {url}: {str(e)}")
+        
+        # Calculate confidence for all tokens
+        for token in self.colors.values():
+            token.confidence = self._calculate_confidence(token.frequency)
+        for token in self.typography.values():
+            token.confidence = self._calculate_confidence(token.frequency)
+        for token in self.spacing.values():
+            token.confidence = self._calculate_confidence(token.frequency)
+        
+        # Detect spacing base
+        spacing_base = self._detect_spacing_base()
+        
+        # Mark outliers in spacing
+        if spacing_base:
+            for token in self.spacing.values():
+                if spacing_base == 8 and not token.fits_base_8:
+                    token.is_outlier = True
+                elif spacing_base == 4 and not token.fits_base_4:
+                    token.is_outlier = True
+        
+        # Determine primary font
+        if self.font_families:
+            primary_font = max(self.font_families.values(), key=lambda f: f.frequency)
+            primary_font.usage = "primary"
+        
+        # Build result
+        end_time = datetime.now()
+        duration_ms = int((end_time - start_time).total_seconds() * 1000)
+        
+        return ExtractedTokens(
+            viewport=self.viewport,
+            source_url=pages[0] if pages else "",
+            pages_crawled=pages_crawled,
+            colors=list(self.colors.values()),
+            typography=list(self.typography.values()),
+            spacing=list(self.spacing.values()),
+            radius=list(self.radius.values()),
+            shadows=list(self.shadows.values()),
+            font_families=list(self.font_families.values()),
+            spacing_base=spacing_base,
+            extraction_timestamp=start_time,
+            extraction_duration_ms=duration_ms,
+            total_elements_analyzed=self.total_elements,
+            unique_colors=len(self.colors),
+            unique_font_sizes=len(set(t.font_size for t in self.typography.values())),
+            unique_spacing_values=len(self.spacing),
+            errors=self.errors,
+            warnings=self.warnings,
+        )
+
+
+# =============================================================================
+# CONVENIENCE FUNCTIONS
+# =============================================================================
+
+async def extract_from_pages(
+    pages: list[str],
+    viewport: Viewport = Viewport.DESKTOP
+) -> ExtractedTokens:
+    """Convenience function to extract tokens from pages."""
+    extractor = TokenExtractor(viewport=viewport)
+    return await extractor.extract(pages)
+
+
+async def extract_both_viewports(pages: list[str]) -> tuple[ExtractedTokens, ExtractedTokens]:
+    """Extract tokens from both desktop and mobile viewports."""
+    desktop_extractor = TokenExtractor(viewport=Viewport.DESKTOP)
+    mobile_extractor = TokenExtractor(viewport=Viewport.MOBILE)
+    
+    desktop_result = await desktop_extractor.extract(pages)
+    mobile_result = await mobile_extractor.extract(pages)
+    
+    return desktop_result, mobile_result

agents/llm_agents.py

@@ -0,0 +1,905 @@
+"""
+Stage 2 LLM Agents — Specialized Analysis Tasks
+=================================================
+
+These agents handle tasks that REQUIRE LLM reasoning:
+- Brand Identifier: Identify brand colors from usage context
+- Benchmark Advisor: Recommend best-fit design system
+- Best Practices Validator: Prioritize fixes by business impact
+- HEAD Synthesizer: Combine all outputs into final recommendations
+
+Each agent has a focused prompt for its specific task.
+"""
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Optional, Callable, Any
+from datetime import datetime
+
+
+# =============================================================================
+# DATA CLASSES
+# =============================================================================
+
+@dataclass
+class BrandIdentification:
+    """Results from Brand Identifier agent."""
+    brand_primary: dict = field(default_factory=dict)
+    # {color, confidence, reasoning, usage_count}
+    
+    brand_secondary: dict = field(default_factory=dict)
+    brand_accent: dict = field(default_factory=dict)
+    
+    palette_strategy: str = ""  # complementary, analogous, triadic, monochromatic, random
+    cohesion_score: int = 5  # 1-10
+    cohesion_notes: str = ""
+    
+    semantic_names: dict = field(default_factory=dict)
+    # {hex_color: suggested_name}
+    
+    def to_dict(self) -> dict:
+        return {
+            "brand_primary": self.brand_primary,
+            "brand_secondary": self.brand_secondary,
+            "brand_accent": self.brand_accent,
+            "palette_strategy": self.palette_strategy,
+            "cohesion_score": self.cohesion_score,
+            "cohesion_notes": self.cohesion_notes,
+            "semantic_names": self.semantic_names,
+        }
+
+
+@dataclass
+class BenchmarkAdvice:
+    """Results from Benchmark Advisor agent."""
+    recommended_benchmark: str = ""
+    recommended_benchmark_name: str = ""
+    reasoning: str = ""
+    
+    alignment_changes: list = field(default_factory=list)
+    # [{change, from, to, effort}]
+    
+    pros_of_alignment: list = field(default_factory=list)
+    cons_of_alignment: list = field(default_factory=list)
+    
+    alternative_benchmarks: list = field(default_factory=list)
+    # [{name, reason}]
+    
+    def to_dict(self) -> dict:
+        return {
+            "recommended_benchmark": self.recommended_benchmark,
+            "recommended_benchmark_name": self.recommended_benchmark_name,
+            "reasoning": self.reasoning,
+            "alignment_changes": self.alignment_changes,
+            "pros": self.pros_of_alignment,
+            "cons": self.cons_of_alignment,
+            "alternatives": self.alternative_benchmarks,
+        }
+
+
+@dataclass
+class BestPracticesResult:
+    """Results from Best Practices Validator agent."""
+    overall_score: int = 50  # 0-100
+    
+    checks: dict = field(default_factory=dict)
+    # {check_name: {status: pass/warn/fail, note: str}}
+    
+    priority_fixes: list = field(default_factory=list)
+    # [{rank, issue, impact, effort, action}]
+    
+    passing_practices: list = field(default_factory=list)
+    failing_practices: list = field(default_factory=list)
+    
+    def to_dict(self) -> dict:
+        return {
+            "overall_score": self.overall_score,
+            "checks": self.checks,
+            "priority_fixes": self.priority_fixes,
+            "passing": self.passing_practices,
+            "failing": self.failing_practices,
+        }
+
+
+@dataclass
+class HeadSynthesis:
+    """Final synthesized output from HEAD agent."""
+    executive_summary: str = ""
+    
+    scores: dict = field(default_factory=dict)
+    # {overall, accessibility, consistency, organization}
+    
+    benchmark_fit: dict = field(default_factory=dict)
+    # {closest, similarity, recommendation}
+    
+    brand_analysis: dict = field(default_factory=dict)
+    # {primary, secondary, cohesion}
+    
+    top_3_actions: list = field(default_factory=list)
+    # [{action, impact, effort, details}]
+    
+    color_recommendations: list = field(default_factory=list)
+    # [{role, current, suggested, reason, accept}]
+    
+    type_scale_recommendation: dict = field(default_factory=dict)
+    spacing_recommendation: dict = field(default_factory=dict)
+    
+    def to_dict(self) -> dict:
+        return {
+            "executive_summary": self.executive_summary,
+            "scores": self.scores,
+            "benchmark_fit": self.benchmark_fit,
+            "brand_analysis": self.brand_analysis,
+            "top_3_actions": self.top_3_actions,
+            "color_recommendations": self.color_recommendations,
+            "type_scale_recommendation": self.type_scale_recommendation,
+            "spacing_recommendation": self.spacing_recommendation,
+        }
+
+
+# =============================================================================
+# BRAND IDENTIFIER AGENT
+# =============================================================================
+
+class BrandIdentifierAgent:
+    """
+    Identifies brand colors from usage context.
+    
+    WHY LLM: Requires understanding context (33 buttons = likely brand primary),
+    not just color math.
+    """
+    
+    PROMPT_TEMPLATE = """You are a senior design system analyst. Identify the brand colors from this color usage data.
+
+## COLOR DATA WITH USAGE CONTEXT
+
+{color_data}
+
+## SEMANTIC ANALYSIS (from CSS properties)
+
+{semantic_analysis}
+
+## YOUR TASK
+
+1. **Identify Brand Colors**:
+   - Brand Primary: The main action/CTA color (highest visibility)
+   - Brand Secondary: Supporting brand color
+   - Brand Accent: Highlight color for emphasis
+
+2. **Assess Palette Strategy**:
+   - Is it complementary, analogous, triadic, monochromatic, or random?
+
+3. **Rate Cohesion** (1-10):
+   - Do the colors work together?
+   - Is there a clear color story?
+
+4. **Suggest Semantic Names** for top 10 most-used colors
+
+## OUTPUT FORMAT (JSON only)
+
+{{
+  "brand_primary": {{
+    "color": "#hex",
+    "confidence": "high|medium|low",
+    "reasoning": "Why this is brand primary",
+    "usage_count": <number>
+  }},
+  "brand_secondary": {{
+    "color": "#hex",
+    "confidence": "high|medium|low",
+    "reasoning": "..."
+  }},
+  "brand_accent": {{
+    "color": "#hex or null",
+    "confidence": "...",
+    "reasoning": "..."
+  }},
+  "palette_strategy": "complementary|analogous|triadic|monochromatic|random",
+  "cohesion_score": <1-10>,
+  "cohesion_notes": "Assessment of how well colors work together",
+  "semantic_names": {{
+    "#hex1": "brand.primary",
+    "#hex2": "text.primary",
+    "#hex3": "background.primary"
+  }}
+}}
+
+Return ONLY valid JSON."""
+
+    def __init__(self, hf_client):
+        self.hf_client = hf_client
+    
+    async def analyze(
+        self,
+        color_tokens: dict,
+        semantic_analysis: dict,
+        log_callback: Callable = None,
+    ) -> BrandIdentification:
+        """
+        Identify brand colors from usage context.
+        
+        Args:
+            color_tokens: Dict of color tokens with usage data
+            semantic_analysis: Semantic categorization from Stage 1
+            log_callback: Progress logging function
+            
+        Returns:
+            BrandIdentification with identified colors
+        """
+        def log(msg: str):
+            if log_callback:
+                log_callback(msg)
+        
+        log("   🎨 Brand Identifier (Llama 70B)")
+        log("   └─ Analyzing color context and usage patterns...")
+        
+        # Format color data
+        color_data = self._format_color_data(color_tokens)
+        semantic_str = self._format_semantic_analysis(semantic_analysis)
+        
+        prompt = self.PROMPT_TEMPLATE.format(
+            color_data=color_data,
+            semantic_analysis=semantic_str,
+        )
+        
+        try:
+            start_time = datetime.now()
+            
+            # Use the correct method signature
+            response = await self.hf_client.complete_async(
+                agent_name="brand_identifier",
+                system_prompt="You are a senior design system analyst specializing in brand color identification.",
+                user_message=prompt,
+                max_tokens=800,
+                json_mode=True,
+            )
+            
+            duration = (datetime.now() - start_time).total_seconds()
+            
+            # Parse response
+            result = self._parse_response(response)
+            
+            log(f"   ────────────────────────────────────────────────")
+            log(f"   🎨 Brand Identifier: COMPLETE ({duration:.1f}s)")
+            log(f"   ├─ Brand Primary: {result.brand_primary.get('color', '?')} ({result.brand_primary.get('confidence', '?')} confidence)")
+            log(f"   ├─ Brand Secondary: {result.brand_secondary.get('color', '?')}")
+            log(f"   ├─ Palette Strategy: {result.palette_strategy}")
+            log(f"   └─ Cohesion Score: {result.cohesion_score}/10")
+            
+            return result
+            
+        except Exception as e:
+            error_msg = str(e)
+            # Parse common HF errors
+            if "Rate limit" in error_msg or "429" in error_msg:
+                log(f"   ⚠️ Rate limited - HF free tier exhausted")
+            elif "Request ID:" in error_msg:
+                log(f"   ⚠️ HF API error (check token/model)")
+            else:
+                log(f"   ⚠️ Error: {error_msg[:60]}")
+            return BrandIdentification()
+    
+    def _format_color_data(self, color_tokens: dict) -> str:
+        """Format color tokens for prompt."""
+        lines = []
+        for name, token in list(color_tokens.items())[:30]:
+            if isinstance(token, dict):
+                hex_val = token.get("value", token.get("hex", ""))
+                usage = token.get("usage_count", token.get("count", 1))
+                context = token.get("context", token.get("css_property", ""))
+            else:
+                hex_val = getattr(token, "value", "")
+                usage = getattr(token, "usage_count", 1)
+                context = getattr(token, "context", "")
+            
+            if hex_val:
+                lines.append(f"- {hex_val}: used {usage}x, context: {context or 'unknown'}")
+        
+        return "\n".join(lines) if lines else "No color data available"
+    
+    def _format_semantic_analysis(self, semantic: dict) -> str:
+        """Format semantic analysis for prompt."""
+        if not semantic:
+            return "No semantic analysis available"
+
+        lines = []
+        try:
+            for category, value in semantic.items():
+                if not value:
+                    continue
+
+                if isinstance(value, list):
+                    # List of colors
+                    color_list = []
+                    for c in value[:5]:
+                        if isinstance(c, dict):
+                            color_list.append(c.get("hex", c.get("value", str(c))))
+                        else:
+                            color_list.append(str(c))
+                    lines.append(f"- {category}: {', '.join(color_list)}")
+
+                elif isinstance(value, dict):
+                    # Could be a nested dict of sub-roles → color dicts
+                    # e.g. {"primary": {"hex": "#007bff", ...}, "secondary": {...}}
+                    # or a flat color dict {"hex": "#...", "confidence": "..."}
+                    # or a summary dict {"total_colors_analyzed": 50, ...}
+                    if "hex" in value:
+                        # Flat color dict
+                        lines.append(f"- {category}: {value['hex']}")
+                    else:
+                        # Nested dict — iterate sub-roles
+                        sub_items = []
+                        for sub_role, sub_val in list(value.items())[:5]:
+                            if isinstance(sub_val, dict) and "hex" in sub_val:
+                                sub_items.append(f"{sub_role}={sub_val['hex']}")
+                            elif isinstance(sub_val, (str, int, float, bool)):
+                                sub_items.append(f"{sub_role}={sub_val}")
+                        if sub_items:
+                            lines.append(f"- {category}: {', '.join(sub_items)}")
+                else:
+                    lines.append(f"- {category}: {value}")
+        except Exception as e:
+            return f"Error formatting semantic analysis: {str(e)[:50]}"
+
+        return "\n".join(lines) if lines else "No semantic analysis available"
+    
+    def _parse_response(self, response: str) -> BrandIdentification:
+        """Parse LLM response into BrandIdentification."""
+        try:
+            json_match = re.search(r'\{[\s\S]*\}', response)
+            if json_match:
+                data = json.loads(json_match.group())
+                return BrandIdentification(
+                    brand_primary=data.get("brand_primary", {}),
+                    brand_secondary=data.get("brand_secondary", {}),
+                    brand_accent=data.get("brand_accent", {}),
+                    palette_strategy=data.get("palette_strategy", "unknown"),
+                    cohesion_score=data.get("cohesion_score", 5),
+                    cohesion_notes=data.get("cohesion_notes", ""),
+                    semantic_names=data.get("semantic_names", {}),
+                )
+        except Exception:
+            pass
+        
+        return BrandIdentification()
+
+
+# =============================================================================
+# BENCHMARK ADVISOR AGENT
+# =============================================================================
+
+class BenchmarkAdvisorAgent:
+    """
+    Recommends best-fit design system based on comparison data.
+    
+    WHY LLM: Requires reasoning about trade-offs and use-case fit,
+    not just similarity scores.
+    """
+    
+    PROMPT_TEMPLATE = """You are a senior design system consultant. Recommend the best design system alignment.
+
+## USER'S CURRENT VALUES
+
+- Type Scale Ratio: {user_ratio}
+- Base Font Size: {user_base}px
+- Spacing Grid: {user_spacing}px
+
+## BENCHMARK COMPARISON
+
+{benchmark_comparison}
+
+## YOUR TASK
+
+1. **Recommend Best Fit**: Which design system should they align with?
+2. **Explain Why**: Consider similarity scores AND use-case fit
+3. **List Changes Needed**: What would they need to change to align?
+4. **Pros/Cons**: Benefits and drawbacks of alignment
+
+## OUTPUT FORMAT (JSON only)
+
+{{
+  "recommended_benchmark": "<system_key>",
+  "recommended_benchmark_name": "<full name>",
+  "reasoning": "Why this is the best fit for their use case",
+  "alignment_changes": [
+    {{"change": "Type scale", "from": "1.18", "to": "1.25", "effort": "medium"}},
+    {{"change": "Spacing grid", "from": "mixed", "to": "4px", "effort": "high"}}
+  ],
+  "pros_of_alignment": [
+    "Familiar patterns for users",
+    "Well-tested accessibility"
+  ],
+  "cons_of_alignment": [
+    "May lose brand uniqueness"
+  ],
+  "alternative_benchmarks": [
+    {{"name": "Material Design 3", "reason": "Good for Android-first products"}}
+  ]
+}}
+
+Return ONLY valid JSON."""
+
+    def __init__(self, hf_client):
+        self.hf_client = hf_client
+    
+    async def analyze(
+        self,
+        user_ratio: float,
+        user_base: int,
+        user_spacing: int,
+        benchmark_comparisons: list,
+        log_callback: Callable = None,
+    ) -> BenchmarkAdvice:
+        """
+        Recommend best-fit design system.
+        
+        Args:
+            user_ratio: User's detected type scale ratio
+            user_base: User's base font size
+            user_spacing: User's spacing grid base
+            benchmark_comparisons: List of BenchmarkComparison objects
+            log_callback: Progress logging function
+            
+        Returns:
+            BenchmarkAdvice with recommendations
+        """
+        def log(msg: str):
+            if log_callback:
+                log_callback(msg)
+        
+        log("")
+        log("   🏢 Benchmark Advisor (Qwen 72B)")
+        log("   └─ Evaluating benchmark fit for your use case...")
+        
+        # Format comparison data
+        comparison_str = self._format_comparisons(benchmark_comparisons)
+        
+        prompt = self.PROMPT_TEMPLATE.format(
+            user_ratio=user_ratio,
+            user_base=user_base,
+            user_spacing=user_spacing,
+            benchmark_comparison=comparison_str,
+        )
+        
+        try:
+            start_time = datetime.now()
+            
+            response = await self.hf_client.complete_async(
+                agent_name="benchmark_advisor",
+                system_prompt="You are a senior design system consultant specializing in design system architecture.",
+                user_message=prompt,
+                max_tokens=700,
+                json_mode=True,
+            )
+            
+            duration = (datetime.now() - start_time).total_seconds()
+            
+            result = self._parse_response(response)
+            
+            log(f"   ────────────────────────────────────────────────")
+            log(f"   🏢 Benchmark Advisor: COMPLETE ({duration:.1f}s)")
+            log(f"   ├─ Recommended: {result.recommended_benchmark_name}")
+            log(f"   ├─ Changes Needed: {len(result.alignment_changes)}")
+            log(f"   └─ Key Change: {result.alignment_changes[0].get('change', 'N/A') if result.alignment_changes else 'None'}")
+            
+            return result
+            
+        except Exception as e:
+            log(f"   ├─ ⚠️ Error: {str(e)[:50]}")
+            return BenchmarkAdvice()
+    
+    def _format_comparisons(self, comparisons: list) -> str:
+        """Format benchmark comparisons for prompt."""
+        lines = []
+        for i, c in enumerate(comparisons[:5]):
+            b = c.benchmark
+            lines.append(f"""
+{i+1}. {b.icon} {b.name}
+   - Similarity Score: {c.similarity_score:.2f} (lower = better)
+   - Match: {c.overall_match_pct:.0f}%
+   - Type Ratio: {b.typography.get('scale_ratio', '?')} (diff: {c.type_ratio_diff:.3f})
+   - Base Size: {b.typography.get('base_size', '?')}px (diff: {c.base_size_diff})
+   - Spacing: {b.spacing.get('base', '?')}px (diff: {c.spacing_grid_diff})
+   - Best For: {', '.join(b.best_for)}""")
+        
+        return "\n".join(lines)
+    
+    def _parse_response(self, response: str) -> BenchmarkAdvice:
+        """Parse LLM response into BenchmarkAdvice."""
+        try:
+            json_match = re.search(r'\{[\s\S]*\}', response)
+            if json_match:
+                data = json.loads(json_match.group())
+                return BenchmarkAdvice(
+                    recommended_benchmark=data.get("recommended_benchmark", ""),
+                    recommended_benchmark_name=data.get("recommended_benchmark_name", ""),
+                    reasoning=data.get("reasoning", ""),
+                    alignment_changes=data.get("alignment_changes", []),
+                    pros_of_alignment=data.get("pros_of_alignment", []),
+                    cons_of_alignment=data.get("cons_of_alignment", []),
+                    alternative_benchmarks=data.get("alternative_benchmarks", []),
+                )
+        except Exception:
+            pass
+        
+        return BenchmarkAdvice()
+
+
+# =============================================================================
+# BEST PRACTICES VALIDATOR AGENT
+# =============================================================================
+
+class BestPracticesValidatorAgent:
+    """
+    Validates against design system best practices and prioritizes fixes.
+    
+    WHY LLM: Prioritization requires judgment about business impact,
+    not just checking boxes.
+    """
+    
+    PROMPT_TEMPLATE = """You are a design system auditor. Validate these tokens against best practices.
+
+## RULE ENGINE ANALYSIS RESULTS
+
+### Typography
+- Detected Ratio: {type_ratio} ({type_consistent})
+- Base Size: {base_size}px
+- Recommendation: {type_recommendation}
+
+### Accessibility
+- Total Colors: {total_colors}
+- AA Pass: {aa_pass}
+- AA Fail: {aa_fail}
+- Failing Colors: {failing_colors}
+
+### Spacing
+- Detected Base: {spacing_base}px
+- Grid Aligned: {spacing_aligned}%
+- Recommendation: {spacing_recommendation}px
+
+### Color Statistics
+- Unique Colors: {unique_colors}
+- Duplicates: {duplicates}
+- Near-Duplicates: {near_duplicates}
+
+## BEST PRACTICES CHECKLIST
+
+1. Type scale uses standard ratio (1.2, 1.25, 1.333, 1.5, 1.618)
+2. Type scale is consistent (variance < 0.15)
+3. Base font size >= 16px (accessibility)
+4. Line height >= 1.5 for body text
+5. All interactive colors pass AA (4.5:1)
+6. Spacing uses consistent grid (4px or 8px)
+7. Limited color palette (< 20 unique semantic colors)
+8. No near-duplicate colors
+
+## YOUR TASK
+
+1. Score each practice: pass/warn/fail
+2. Calculate overall score (0-100)
+3. Identify TOP 3 priority fixes with impact assessment
+
+## OUTPUT FORMAT (JSON only)
+
+{{
+  "overall_score": <0-100>,
+  "checks": {{
+    "type_scale_standard": {{"status": "pass|warn|fail", "note": "..."}},
+    "type_scale_consistent": {{"status": "...", "note": "..."}},
+    "base_size_accessible": {{"status": "...", "note": "..."}},
+    "aa_compliance": {{"status": "...", "note": "..."}},
+    "spacing_grid": {{"status": "...", "note": "..."}},
+    "color_count": {{"status": "...", "note": "..."}}
+  }},
+  "priority_fixes": [
+    {{
+      "rank": 1,
+      "issue": "Brand primary fails AA",
+      "impact": "high|medium|low",
+      "effort": "low|medium|high",
+      "action": "Change #06b2c4 → #0891a8"
+    }}
+  ],
+  "passing_practices": ["Base font size", "..."],
+  "failing_practices": ["AA compliance", "..."]
+}}
+
+Return ONLY valid JSON."""
+
+    def __init__(self, hf_client):
+        self.hf_client = hf_client
+    
+    async def analyze(
+        self,
+        rule_engine_results: Any,
+        log_callback: Callable = None,
+    ) -> BestPracticesResult:
+        """
+        Validate against best practices.
+        
+        Args:
+            rule_engine_results: Results from rule engine
+            log_callback: Progress logging function
+            
+        Returns:
+            BestPracticesResult with validation
+        """
+        def log(msg: str):
+            if log_callback:
+                log_callback(msg)
+        
+        log("")
+        log("   ✅ 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]])
+        
+        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}",
+            base_size=typo.sizes_px[0] if typo.sizes_px else 16,
+            type_recommendation=f"{typo.recommendation} ({typo.recommendation_name})",
+            total_colors=len(accessibility),
+            aa_pass=len(accessibility) - len(failures),
+            aa_fail=len(failures),
+            failing_colors=failing_colors_str or "None",
+            spacing_base=spacing.detected_base,
+            spacing_aligned=f"{spacing.alignment_percentage:.0f}",
+            spacing_recommendation=spacing.recommendation,
+            unique_colors=color_stats.unique_count,
+            duplicates=color_stats.duplicate_count,
+            near_duplicates=len(color_stats.near_duplicates),
+        )
+        
+        try:
+            start_time = datetime.now()
+            
+            response = await self.hf_client.complete_async(
+                agent_name="best_practices_validator",
+                system_prompt="You are a design system auditor specializing in best practices validation.",
+                user_message=prompt,
+                max_tokens=800,
+                json_mode=True,
+            )
+            
+            duration = (datetime.now() - start_time).total_seconds()
+            
+            result = self._parse_response(response)
+            
+            log(f"   ────────────────────────────────────────────────")
+            log(f"   ✅ Best Practices: COMPLETE ({duration:.1f}s)")
+            log(f"   ├─ Overall Score: {result.overall_score}/100")
+            log(f"   ├─ Passing: {len(result.passing_practices)} | Failing: {len(result.failing_practices)}")
+            if result.priority_fixes:
+                log(f"   └─ Top Fix: {result.priority_fixes[0].get('issue', 'N/A')}")
+            
+            return result
+            
+        except Exception as e:
+            log(f"   ├─ ⚠️ Error: {str(e)[:50]}")
+            return BestPracticesResult()
+    
+    def _parse_response(self, response: str) -> BestPracticesResult:
+        """Parse LLM response into BestPracticesResult."""
+        try:
+            json_match = re.search(r'\{[\s\S]*\}', response)
+            if json_match:
+                data = json.loads(json_match.group())
+                return BestPracticesResult(
+                    overall_score=data.get("overall_score", 50),
+                    checks=data.get("checks", {}),
+                    priority_fixes=data.get("priority_fixes", []),
+                    passing_practices=data.get("passing_practices", []),
+                    failing_practices=data.get("failing_practices", []),
+                )
+        except Exception:
+            pass
+        
+        return BestPracticesResult()
+
+
+# =============================================================================
+# HEAD SYNTHESIZER AGENT
+# =============================================================================
+
+class HeadSynthesizerAgent:
+    """
+    Combines all agent outputs into final recommendations.
+    
+    This is the final step that produces actionable output for the user.
+    """
+    
+    PROMPT_TEMPLATE = """You are a senior design system architect. Synthesize these analysis results into final recommendations.
+
+## RULE ENGINE FACTS
+
+- Type Scale: {type_ratio} ({type_status})
+- Base Size: {base_size}px
+- AA Failures: {aa_failures}
+- Spacing Grid: {spacing_status}
+- Unique Colors: {unique_colors}
+- Consistency Score: {consistency_score}/100
+
+## BENCHMARK COMPARISON
+
+Closest Match: {closest_benchmark}
+Match Percentage: {match_pct}%
+Recommended Changes: {benchmark_changes}
+
+## BRAND IDENTIFICATION
+
+- Brand Primary: {brand_primary}
+- Brand Secondary: {brand_secondary}
+- Palette Cohesion: {cohesion_score}/10
+
+## BEST PRACTICES VALIDATION
+
+Overall Score: {best_practices_score}/100
+Priority Fixes: {priority_fixes}
+
+## ACCESSIBILITY FIXES NEEDED
+
+{accessibility_fixes}
+
+## YOUR TASK
+
+Synthesize ALL the above into:
+1. Executive Summary (2-3 sentences)
+2. Overall Scores
+3. Top 3 Priority Actions (with effort estimates)
+4. Specific Color Recommendations (with accept/reject defaults)
+5. Type Scale Recommendation
+6. Spacing Recommendation
+
+## OUTPUT FORMAT (JSON only)
+
+{{
+  "executive_summary": "Your design system scores X/100. Key issues are Y. Priority action is Z.",
+  "scores": {{
+    "overall": <0-100>,
+    "accessibility": <0-100>,
+    "consistency": <0-100>,
+    "organization": <0-100>
+  }},
+  "benchmark_fit": {{
+    "closest": "<name>",
+    "similarity": "<X%>",
+    "recommendation": "Align type scale to 1.25"
+  }},
+  "brand_analysis": {{
+    "primary": "#hex",
+    "secondary": "#hex",
+    "cohesion": <1-10>
+  }},
+  "top_3_actions": [
+    {{"action": "Fix brand color AA", "impact": "high", "effort": "5 min", "details": "Change #X to #Y"}}
+  ],
+  "color_recommendations": [
+    {{"role": "brand.primary", "current": "#06b2c4", "suggested": "#0891a8", "reason": "AA compliance", "accept": true}}
+  ],
+  "type_scale_recommendation": {{
+    "current_ratio": 1.18,
+    "recommended_ratio": 1.25,
+    "reason": "Align with industry standard"
+  }},
+  "spacing_recommendation": {{
+    "current": "mixed",
+    "recommended": "8px",
+    "reason": "Consistent grid improves maintainability"
+  }}
+}}
+
+Return ONLY valid JSON."""
+
+    def __init__(self, hf_client):
+        self.hf_client = hf_client
+    
+    async def synthesize(
+        self,
+        rule_engine_results: Any,
+        benchmark_comparisons: list,
+        brand_identification: BrandIdentification,
+        benchmark_advice: BenchmarkAdvice,
+        best_practices: BestPracticesResult,
+        log_callback: Callable = None,
+    ) -> HeadSynthesis:
+        """
+        Synthesize all results into final recommendations.
+        """
+        def log(msg: str):
+            if log_callback:
+                log_callback(msg)
+        
+        log("")
+        log("═" * 60)
+        log("🧠 LAYER 4: HEAD SYNTHESIZER")
+        log("═" * 60)
+        log("")
+        log("   Combining: Rule Engine + Benchmarks + Brand + Best Practices...")
+        
+        # Extract data
+        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]
+        aa_fixes_str = "\n".join([
+            f"- {a.name}: {a.hex_color} ({a.contrast_on_white:.1f}:1) → {a.suggested_fix} ({a.suggested_fix_contrast:.1f}:1)"
+            for a in failures[:5] if a.suggested_fix
+        ])
+        
+        closest = benchmark_comparisons[0] if benchmark_comparisons else None
+        
+        prompt = self.PROMPT_TEMPLATE.format(
+            type_ratio=f"{typo.detected_ratio:.3f}",
+            type_status="consistent" if typo.is_consistent else "inconsistent",
+            base_size=typo.sizes_px[0] if typo.sizes_px else 16,
+            aa_failures=len(failures),
+            spacing_status=f"{spacing.detected_base}px, {spacing.alignment_percentage:.0f}% aligned",
+            unique_colors=color_stats.unique_count,
+            consistency_score=rule_engine_results.consistency_score,
+            closest_benchmark=closest.benchmark.name if closest else "Unknown",
+            match_pct=f"{closest.overall_match_pct:.0f}" if closest else "0",
+            benchmark_changes="; ".join([c.get("change", "") for c in benchmark_advice.alignment_changes[:3]]),
+            brand_primary=brand_identification.brand_primary.get("color", "Unknown"),
+            brand_secondary=brand_identification.brand_secondary.get("color", "Unknown"),
+            cohesion_score=brand_identification.cohesion_score,
+            best_practices_score=best_practices.overall_score,
+            priority_fixes="; ".join([f.get("issue", "") for f in best_practices.priority_fixes[:3]]),
+            accessibility_fixes=aa_fixes_str or "None needed",
+        )
+        
+        try:
+            start_time = datetime.now()
+            
+            response = await self.hf_client.complete_async(
+                agent_name="head_synthesizer",
+                system_prompt="You are a senior design system architect specializing in synthesis and recommendations.",
+                user_message=prompt,
+                max_tokens=1000,
+                json_mode=True,
+            )
+            
+            duration = (datetime.now() - start_time).total_seconds()
+            
+            result = self._parse_response(response)
+            
+            log("")
+            log(f"   ✅ HEAD Synthesizer: COMPLETE ({duration:.1f}s)")
+            log("")
+            
+            return result
+            
+        except Exception as e:
+            log(f"   ├─ ⚠️ Error: {str(e)[:50]}")
+            return HeadSynthesis()
+    
+    def _parse_response(self, response: str) -> HeadSynthesis:
+        """Parse LLM response into HeadSynthesis."""
+        try:
+            json_match = re.search(r'\{[\s\S]*\}', response)
+            if json_match:
+                data = json.loads(json_match.group())
+                return HeadSynthesis(
+                    executive_summary=data.get("executive_summary", ""),
+                    scores=data.get("scores", {}),
+                    benchmark_fit=data.get("benchmark_fit", {}),
+                    brand_analysis=data.get("brand_analysis", {}),
+                    top_3_actions=data.get("top_3_actions", []),
+                    color_recommendations=data.get("color_recommendations", []),
+                    type_scale_recommendation=data.get("type_scale_recommendation", {}),
+                    spacing_recommendation=data.get("spacing_recommendation", {}),
+                )
+        except Exception:
+            pass
+        
+        return HeadSynthesis()