Upload 2 files

core/hf_inference.py

@@ -0,0 +1,602 @@
+"""
+HuggingFace Inference Client
+Design System Extractor v2
+
+Handles all LLM inference calls using HuggingFace Inference API.
+Supports diverse models from different providers for specialized tasks.
+"""
+
+import os
+from typing import Optional, AsyncGenerator
+from dataclasses import dataclass
+from huggingface_hub import InferenceClient, AsyncInferenceClient
+
+from config.settings import get_settings
+
+
+@dataclass
+class ModelInfo:
+    """Information about a model."""
+    model_id: str
+    provider: str
+    context_length: int
+    strengths: list[str]
+    best_for: str
+    tier: str  # "free", "pro", "pro+"
+
+
+# =============================================================================
+# COMPREHENSIVE MODEL REGISTRY — Organized by Provider
+# =============================================================================
+
+AVAILABLE_MODELS = {
+    # =========================================================================
+    # META — Llama Family (Best for reasoning)
+    # =========================================================================
+    "meta-llama/Llama-3.1-405B-Instruct": ModelInfo(
+        model_id="meta-llama/Llama-3.1-405B-Instruct",
+        provider="Meta",
+        context_length=128000,
+        strengths=["Best reasoning", "Massive knowledge", "Complex analysis"],
+        best_for="Agent 3 (Advisor) — PREMIUM CHOICE",
+        tier="pro+"
+    ),
+    "meta-llama/Llama-3.1-70B-Instruct": ModelInfo(
+        model_id="meta-llama/Llama-3.1-70B-Instruct",
+        provider="Meta",
+        context_length=128000,
+        strengths=["Excellent reasoning", "Long context", "Design knowledge"],
+        best_for="Agent 3 (Advisor) — RECOMMENDED",
+        tier="pro"
+    ),
+    "meta-llama/Llama-3.1-8B-Instruct": ModelInfo(
+        model_id="meta-llama/Llama-3.1-8B-Instruct",
+        provider="Meta",
+        context_length=128000,
+        strengths=["Fast", "Good reasoning for size", "Long context"],
+        best_for="Budget Agent 3 fallback",
+        tier="free"
+    ),
+    
+    # =========================================================================
+    # MISTRAL — European Excellence
+    # =========================================================================
+    "mistralai/Mixtral-8x22B-Instruct-v0.1": ModelInfo(
+        model_id="mistralai/Mixtral-8x22B-Instruct-v0.1",
+        provider="Mistral",
+        context_length=65536,
+        strengths=["Large MoE", "Strong reasoning", "Efficient"],
+        best_for="Agent 3 (Advisor) — Pro alternative",
+        tier="pro"
+    ),
+    "mistralai/Mixtral-8x7B-Instruct-v0.1": ModelInfo(
+        model_id="mistralai/Mixtral-8x7B-Instruct-v0.1",
+        provider="Mistral",
+        context_length=32768,
+        strengths=["Good MoE efficiency", "Solid reasoning"],
+        best_for="Agent 3 (Advisor) — Free tier option",
+        tier="free"
+    ),
+    "mistralai/Mistral-7B-Instruct-v0.3": ModelInfo(
+        model_id="mistralai/Mistral-7B-Instruct-v0.3",
+        provider="Mistral",
+        context_length=32768,
+        strengths=["Fast", "Good instruction following"],
+        best_for="General fallback",
+        tier="free"
+    ),
+    "mistralai/Codestral-22B-v0.1": ModelInfo(
+        model_id="mistralai/Codestral-22B-v0.1",
+        provider="Mistral",
+        context_length=32768,
+        strengths=["Code specialist", "JSON generation", "Structured output"],
+        best_for="Agent 4 (Generator) — RECOMMENDED",
+        tier="pro"
+    ),
+    
+    # =========================================================================
+    # COHERE — Command R Family (Analysis & Retrieval)
+    # =========================================================================
+    "CohereForAI/c4ai-command-r-plus": ModelInfo(
+        model_id="CohereForAI/c4ai-command-r-plus",
+        provider="Cohere",
+        context_length=128000,
+        strengths=["Excellent analysis", "RAG optimized", "Long context"],
+        best_for="Agent 3 (Advisor) — Great for research tasks",
+        tier="pro"
+    ),
+    "CohereForAI/c4ai-command-r-v01": ModelInfo(
+        model_id="CohereForAI/c4ai-command-r-v01",
+        provider="Cohere",
+        context_length=128000,
+        strengths=["Good analysis", "Efficient"],
+        best_for="Agent 3 budget option",
+        tier="free"
+    ),
+    
+    # =========================================================================
+    # GOOGLE — Gemma Family
+    # =========================================================================
+    "google/gemma-2-27b-it": ModelInfo(
+        model_id="google/gemma-2-27b-it",
+        provider="Google",
+        context_length=8192,
+        strengths=["Strong instruction following", "Good balance"],
+        best_for="Agent 2 (Normalizer) — Quality option",
+        tier="pro"
+    ),
+    "google/gemma-2-9b-it": ModelInfo(
+        model_id="google/gemma-2-9b-it",
+        provider="Google",
+        context_length=8192,
+        strengths=["Fast", "Good instruction following"],
+        best_for="Agent 2 (Normalizer) — Balanced",
+        tier="free"
+    ),
+    
+    # =========================================================================
+    # MICROSOFT — Phi Family (Small but Mighty)
+    # =========================================================================
+    "microsoft/Phi-3.5-mini-instruct": ModelInfo(
+        model_id="microsoft/Phi-3.5-mini-instruct",
+        provider="Microsoft",
+        context_length=128000,
+        strengths=["Very fast", "Great structured output", "Long context"],
+        best_for="Agent 2 (Normalizer) — RECOMMENDED",
+        tier="free"
+    ),
+    "microsoft/Phi-3-medium-4k-instruct": ModelInfo(
+        model_id="microsoft/Phi-3-medium-4k-instruct",
+        provider="Microsoft",
+        context_length=4096,
+        strengths=["Fast", "Good for simple tasks"],
+        best_for="Simple naming tasks",
+        tier="free"
+    ),
+    
+    # =========================================================================
+    # QWEN — Alibaba Family
+    # =========================================================================
+    "Qwen/Qwen2.5-72B-Instruct": ModelInfo(
+        model_id="Qwen/Qwen2.5-72B-Instruct",
+        provider="Alibaba",
+        context_length=32768,
+        strengths=["Strong reasoning", "Multilingual", "Good design knowledge"],
+        best_for="Agent 3 (Advisor) — Alternative",
+        tier="pro"
+    ),
+    "Qwen/Qwen2.5-32B-Instruct": ModelInfo(
+        model_id="Qwen/Qwen2.5-32B-Instruct",
+        provider="Alibaba",
+        context_length=32768,
+        strengths=["Good balance", "Multilingual"],
+        best_for="Medium-tier option",
+        tier="pro"
+    ),
+    "Qwen/Qwen2.5-Coder-32B-Instruct": ModelInfo(
+        model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
+        provider="Alibaba",
+        context_length=32768,
+        strengths=["Code specialist", "JSON/structured output"],
+        best_for="Agent 4 (Generator) — Alternative",
+        tier="pro"
+    ),
+    "Qwen/Qwen2.5-7B-Instruct": ModelInfo(
+        model_id="Qwen/Qwen2.5-7B-Instruct",
+        provider="Alibaba",
+        context_length=32768,
+        strengths=["Fast", "Good all-rounder"],
+        best_for="General fallback",
+        tier="free"
+    ),
+    
+    # =========================================================================
+    # DEEPSEEK — Code Specialists
+    # =========================================================================
+    "deepseek-ai/deepseek-coder-33b-instruct": ModelInfo(
+        model_id="deepseek-ai/deepseek-coder-33b-instruct",
+        provider="DeepSeek",
+        context_length=16384,
+        strengths=["Excellent code generation", "JSON specialist"],
+        best_for="Agent 4 (Generator) — Code focused",
+        tier="pro"
+    ),
+    "deepseek-ai/DeepSeek-V2.5": ModelInfo(
+        model_id="deepseek-ai/DeepSeek-V2.5",
+        provider="DeepSeek",
+        context_length=32768,
+        strengths=["Strong reasoning", "Good code"],
+        best_for="Multi-purpose",
+        tier="pro"
+    ),
+    
+    # =========================================================================
+    # BIGCODE — StarCoder Family
+    # =========================================================================
+    "bigcode/starcoder2-15b-instruct-v0.1": ModelInfo(
+        model_id="bigcode/starcoder2-15b-instruct-v0.1",
+        provider="BigCode",
+        context_length=16384,
+        strengths=["Code generation", "Multiple languages"],
+        best_for="Agent 4 (Generator) — Open source code model",
+        tier="free"
+    ),
+}
+
+
+# =============================================================================
+# RECOMMENDED CONFIGURATIONS BY TIER
+# =============================================================================
+
+MODEL_PRESETS = {
+    "budget": {
+        "name": "Budget (Free Tier)",
+        "description": "Best free models for each task",
+        "agent2": "microsoft/Phi-3.5-mini-instruct",
+        "agent3": "mistralai/Mixtral-8x7B-Instruct-v0.1",
+        "agent4": "bigcode/starcoder2-15b-instruct-v0.1",
+        "fallback": "mistralai/Mistral-7B-Instruct-v0.3",
+    },
+    "balanced": {
+        "name": "Balanced (Pro Tier)",
+        "description": "Good quality/cost balance",
+        "agent2": "google/gemma-2-9b-it",
+        "agent3": "meta-llama/Llama-3.1-70B-Instruct",
+        "agent4": "mistralai/Codestral-22B-v0.1",
+        "fallback": "Qwen/Qwen2.5-7B-Instruct",
+    },
+    "quality": {
+        "name": "Maximum Quality (Pro+)",
+        "description": "Best models regardless of cost",
+        "agent2": "google/gemma-2-27b-it",
+        "agent3": "meta-llama/Llama-3.1-405B-Instruct",
+        "agent4": "deepseek-ai/deepseek-coder-33b-instruct",
+        "fallback": "meta-llama/Llama-3.1-8B-Instruct",
+    },
+    "diverse": {
+        "name": "Diverse Providers",
+        "description": "One model from each major provider",
+        "agent2": "microsoft/Phi-3.5-mini-instruct",  # Microsoft
+        "agent3": "CohereForAI/c4ai-command-r-plus",  # Cohere
+        "agent4": "mistralai/Codestral-22B-v0.1",     # Mistral
+        "fallback": "meta-llama/Llama-3.1-8B-Instruct",  # Meta
+    },
+}
+
+
+# =============================================================================
+# AGENT-SPECIFIC RECOMMENDATIONS
+# =============================================================================
+
+AGENT_MODEL_RECOMMENDATIONS = {
+    "crawler": {
+        "requires_llm": False,
+        "notes": "Pure rule-based extraction using Playwright + CSS parsing"
+    },
+    "extractor": {
+        "requires_llm": False,
+        "notes": "Pure rule-based extraction using Playwright + CSS parsing"
+    },
+    "normalizer": {
+        "requires_llm": True,
+        "task": "Token naming, duplicate detection, pattern inference",
+        "needs": ["Fast inference", "Good instruction following", "Structured output"],
+        "recommended": [
+            ("microsoft/Phi-3.5-mini-instruct", "BEST — Fast, great structured output"),
+            ("google/gemma-2-9b-it", "Good balance of speed and quality"),
+            ("Qwen/Qwen2.5-7B-Instruct", "Reliable all-rounder"),
+        ],
+        "temperature": 0.2,
+    },
+    "advisor": {
+        "requires_llm": True,
+        "task": "Design system analysis, best practice recommendations",
+        "needs": ["Strong reasoning", "Design knowledge", "Creative suggestions"],
+        "recommended": [
+            ("meta-llama/Llama-3.1-70B-Instruct", "BEST — Excellent reasoning"),
+            ("CohereForAI/c4ai-command-r-plus", "Great for analysis tasks"),
+            ("Qwen/Qwen2.5-72B-Instruct", "Strong alternative"),
+            ("mistralai/Mixtral-8x7B-Instruct-v0.1", "Best free option"),
+        ],
+        "temperature": 0.4,
+    },
+    "generator": {
+        "requires_llm": True,
+        "task": "Generate JSON tokens, CSS variables, structured output",
+        "needs": ["Code generation", "JSON formatting", "Schema adherence"],
+        "recommended": [
+            ("mistralai/Codestral-22B-v0.1", "BEST — Mistral's code model"),
+            ("deepseek-ai/deepseek-coder-33b-instruct", "Excellent code specialist"),
+            ("Qwen/Qwen2.5-Coder-32B-Instruct", "Strong code model"),
+            ("bigcode/starcoder2-15b-instruct-v0.1", "Best free option"),
+        ],
+        "temperature": 0.1,
+    },
+}
+
+
+# =============================================================================
+# INFERENCE CLIENT
+# =============================================================================
+
+class HFInferenceClient:
+    """
+    Wrapper around HuggingFace Inference API.
+    
+    Handles model selection, retries, and fallbacks.
+    """
+    
+    def __init__(self):
+        self.settings = get_settings()
+        # Read token fresh from env — the Settings singleton may have been
+        # created before the user entered their token via the Gradio UI.
+        self.token = os.getenv("HF_TOKEN", "") or self.settings.hf.hf_token
+
+        if not self.token:
+            raise ValueError("HF_TOKEN is required for inference")
+
+        # Let huggingface_hub route to the best available provider automatically.
+        # Do NOT set base_url (overrides per-model routing) or
+        # provider="hf-inference" (that provider no longer hosts most models).
+        # The default provider="auto" picks the first available third-party
+        # provider (novita, together, cerebras, etc.) for each model.
+        self.sync_client = InferenceClient(token=self.token)
+        self.async_client = AsyncInferenceClient(token=self.token)
+    
+    def get_model_for_agent(self, agent_name: str) -> str:
+        """Get the appropriate model for an agent."""
+        return self.settings.get_model_for_agent(agent_name)
+    
+    def get_temperature_for_agent(self, agent_name: str) -> float:
+        """Get recommended temperature for an agent."""
+        temps = {
+            "normalizer": 0.2,  # Consistent naming
+            "advisor": 0.4,    # Creative recommendations
+            "generator": 0.1,  # Precise formatting
+        }
+        return temps.get(agent_name, 0.3)
+    
+    def _build_messages(
+        self,
+        system_prompt: str,
+        user_message: str,
+        examples: list[dict] = None
+    ) -> list[dict]:
+        """Build message list for chat completion."""
+        messages = []
+        
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        
+        if examples:
+            for example in examples:
+                messages.append({"role": "user", "content": example["user"]})
+                messages.append({"role": "assistant", "content": example["assistant"]})
+        
+        messages.append({"role": "user", "content": user_message})
+        
+        return messages
+    
+    def complete(
+        self,
+        agent_name: str,
+        system_prompt: str,
+        user_message: str,
+        examples: list[dict] = None,
+        max_tokens: int = None,
+        temperature: float = None,
+        json_mode: bool = False,
+    ) -> str:
+        """
+        Synchronous completion.
+        
+        Args:
+            agent_name: Which agent is making the call (for model selection)
+            system_prompt: System instructions
+            user_message: User input
+            examples: Optional few-shot examples
+            max_tokens: Max tokens to generate
+            temperature: Sampling temperature (uses agent default if not specified)
+            json_mode: If True, instruct model to output JSON
+        
+        Returns:
+            Generated text
+        """
+        model = self.get_model_for_agent(agent_name)
+        max_tokens = max_tokens or self.settings.hf.max_new_tokens
+        temperature = temperature or self.get_temperature_for_agent(agent_name)
+        
+        # Build messages
+        if json_mode:
+            system_prompt = f"{system_prompt}\n\nYou must respond with valid JSON only. No markdown, no explanation, just JSON."
+        
+        messages = self._build_messages(system_prompt, user_message, examples)
+        
+        try:
+            response = self.sync_client.chat_completion(
+                model=model,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+            return response.choices[0].message.content
+
+        except Exception as e:
+            error_msg = str(e)
+            print(f"[HF] Primary model {model} failed: {error_msg[:120]}")
+            fallback = self.settings.models.fallback_model
+            if fallback and fallback != model:
+                print(f"[HF] Trying fallback: {fallback}")
+                try:
+                    response = self.sync_client.chat_completion(
+                        model=fallback,
+                        messages=messages,
+                        max_tokens=max_tokens,
+                        temperature=temperature,
+                    )
+                    return response.choices[0].message.content
+                except Exception as fallback_err:
+                    print(f"[HF] Fallback {fallback} also failed: {str(fallback_err)[:120]}")
+                    raise fallback_err
+            raise e
+    
+    async def complete_async(
+        self,
+        agent_name: str,
+        system_prompt: str,
+        user_message: str,
+        examples: list[dict] = None,
+        max_tokens: int = None,
+        temperature: float = None,
+        json_mode: bool = False,
+    ) -> str:
+        """
+        Asynchronous completion.
+        
+        Same parameters as complete().
+        """
+        model = self.get_model_for_agent(agent_name)
+        max_tokens = max_tokens or self.settings.hf.max_new_tokens
+        temperature = temperature or self.get_temperature_for_agent(agent_name)
+        
+        if json_mode:
+            system_prompt = f"{system_prompt}\n\nYou must respond with valid JSON only. No markdown, no explanation, just JSON."
+        
+        messages = self._build_messages(system_prompt, user_message, examples)
+        
+        try:
+            response = await self.async_client.chat_completion(
+                model=model,
+                messages=messages,
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+            return response.choices[0].message.content
+
+        except Exception as e:
+            error_msg = str(e)
+            print(f"[HF] Primary model {model} failed: {error_msg[:120]}")
+            fallback = self.settings.models.fallback_model
+            if fallback and fallback != model:
+                print(f"[HF] Trying fallback: {fallback}")
+                try:
+                    response = await self.async_client.chat_completion(
+                        model=fallback,
+                        messages=messages,
+                        max_tokens=max_tokens,
+                        temperature=temperature,
+                    )
+                    return response.choices[0].message.content
+                except Exception as fallback_err:
+                    print(f"[HF] Fallback {fallback} also failed: {str(fallback_err)[:120]}")
+                    raise fallback_err
+            raise e
+    
+    async def stream_async(
+        self,
+        agent_name: str,
+        system_prompt: str,
+        user_message: str,
+        max_tokens: int = None,
+        temperature: float = None,
+    ) -> AsyncGenerator[str, None]:
+        """
+        Async streaming completion.
+        
+        Yields tokens as they are generated.
+        """
+        model = self.get_model_for_agent(agent_name)
+        max_tokens = max_tokens or self.settings.hf.max_new_tokens
+        temperature = temperature or self.get_temperature_for_agent(agent_name)
+        
+        messages = self._build_messages(system_prompt, user_message)
+        
+        async for chunk in await self.async_client.chat_completion(
+            model=model,
+            messages=messages,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=True,
+        ):
+            if chunk.choices[0].delta.content:
+                yield chunk.choices[0].delta.content
+
+
+# =============================================================================
+# SINGLETON & CONVENIENCE FUNCTIONS
+# =============================================================================
+
+_client: Optional[HFInferenceClient] = None
+
+
+def get_inference_client() -> HFInferenceClient:
+    """Get or create the inference client singleton.
+
+    Re-creates the client if the token has changed (e.g. user entered it
+    via the Gradio UI after initial startup).
+    """
+    global _client
+    current_token = os.getenv("HF_TOKEN", "")
+    if _client is None or (_client.token != current_token and current_token):
+        _client = HFInferenceClient()
+    return _client
+
+
+def complete(
+    agent_name: str,
+    system_prompt: str,
+    user_message: str,
+    **kwargs
+) -> str:
+    """Convenience function for sync completion."""
+    client = get_inference_client()
+    return client.complete(agent_name, system_prompt, user_message, **kwargs)
+
+
+async def complete_async(
+    agent_name: str,
+    system_prompt: str,
+    user_message: str,
+    **kwargs
+) -> str:
+    """Convenience function for async completion."""
+    client = get_inference_client()
+    return await client.complete_async(agent_name, system_prompt, user_message, **kwargs)
+
+
+def get_model_info(model_id: str) -> dict:
+    """Get information about a specific model."""
+    if model_id in AVAILABLE_MODELS:
+        info = AVAILABLE_MODELS[model_id]
+        return {
+            "model_id": info.model_id,
+            "provider": info.provider,
+            "context_length": info.context_length,
+            "strengths": info.strengths,
+            "best_for": info.best_for,
+            "tier": info.tier,
+        }
+    return {"model_id": model_id, "provider": "unknown"}
+
+
+def get_models_by_provider() -> dict[str, list[str]]:
+    """Get all models grouped by provider."""
+    by_provider = {}
+    for model_id, info in AVAILABLE_MODELS.items():
+        if info.provider not in by_provider:
+            by_provider[info.provider] = []
+        by_provider[info.provider].append(model_id)
+    return by_provider
+
+
+def get_models_by_tier(tier: str) -> list[str]:
+    """Get all models for a specific tier (free, pro, pro+)."""
+    return [
+        model_id for model_id, info in AVAILABLE_MODELS.items()
+        if info.tier == tier
+    ]
+
+
+def get_preset_config(preset_name: str) -> dict:
+    """Get a preset model configuration."""
+    return MODEL_PRESETS.get(preset_name, MODEL_PRESETS["balanced"])

core/preview_generator.py

@@ -0,0 +1,1534 @@
+"""
+Preview Generator for Typography and Color Previews
+
+Generates HTML previews for:
+1. Typography - Actual font rendering with detected styles
+2. Colors AS-IS - Simple swatches showing extracted colors (Stage 1)
+3. Color Ramps - 11 shades (50-950) with AA compliance (Stage 2)
+4. Spacing AS-IS - Visual spacing blocks
+5. Radius AS-IS - Rounded corner examples
+6. Shadows AS-IS - Shadow examples
+"""
+
+from typing import Optional
+import colorsys
+import re
+
+
+# =============================================================================
+# STAGE 1: AS-IS PREVIEWS (No enhancements, just raw extracted values)
+# =============================================================================
+
+def generate_colors_asis_preview_html(
+    color_tokens: dict,
+    background: str = "#FAFAFA",
+    max_colors: int = 50
+) -> str:
+    """
+    Generate HTML preview for AS-IS colors (Stage 1).
+    
+    Shows simple color swatches without generated ramps.
+    Sorted by frequency (most used first).
+    
+    Args:
+        color_tokens: Dict of colors {name: {value: "#hex", ...}}
+        background: Background color
+        max_colors: Maximum colors to display (default 50)
+    
+    Returns:
+        HTML string for Gradio HTML component
+    """
+    
+    # Sort by frequency (highest first)
+    sorted_tokens = []
+    for name, token in color_tokens.items():
+        if isinstance(token, dict):
+            freq = token.get("frequency", 0)
+        else:
+            freq = 0
+        sorted_tokens.append((name, token, freq))
+    
+    sorted_tokens.sort(key=lambda x: -x[2])  # Descending by frequency
+    
+    rows_html = ""
+    
+    for name, token, freq in sorted_tokens[:max_colors]:
+        # Get hex value
+        if isinstance(token, dict):
+            hex_val = token.get("value", "#888888")
+            frequency = token.get("frequency", 0)
+            contexts = token.get("contexts", [])
+            contrast_white = token.get("contrast_white", 0)
+            contrast_black = token.get("contrast_black", 0)
+        else:
+            hex_val = str(token)
+            frequency = 0
+            contexts = []
+            contrast_white = 0
+            contrast_black = 0
+        
+        # Clean up hex
+        if not hex_val.startswith("#"):
+            hex_val = f"#{hex_val}"
+        
+        # Determine text color based on background luminance
+        # Use contrast ratios to pick best text color
+        text_color = "#1a1a1a" if contrast_white and contrast_white < 4.5 else "#ffffff"
+        if not contrast_white:
+            # Fallback: calculate from hex
+            try:
+                r = int(hex_val[1:3], 16)
+                g = int(hex_val[3:5], 16)
+                b = int(hex_val[5:7], 16)
+                luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255
+                text_color = "#1a1a1a" if luminance > 0.5 else "#ffffff"
+            except:
+                text_color = "#1a1a1a"
+        
+        # Clean name
+        display_name = name.replace("_", " ").replace("-", " ").replace(".", " ").title()
+        if len(display_name) > 25:
+            display_name = display_name[:22] + "..."
+        
+        # AA compliance check
+        aa_status = "✓ AA" if contrast_white and contrast_white >= 4.5 else "✗ AA" if contrast_white else ""
+        aa_class = "aa-pass" if contrast_white and contrast_white >= 4.5 else "aa-fail"
+        
+        # Context badges (limit to 3)
+        context_html = ""
+        for ctx in contexts[:3]:
+            ctx_display = ctx[:12] + "..." if len(ctx) > 12 else ctx
+            context_html += f'<span class="context-badge">{ctx_display}</span>'
+        
+        rows_html += f'''
+        <div class="color-row-asis">
+            <div class="color-swatch-large" style="background-color: {hex_val};">
+                <span class="swatch-hex" style="color: {text_color};">{hex_val}</span>
+            </div>
+            <div class="color-info-asis">
+                <div class="color-name-asis">{display_name}</div>
+                <div class="color-meta-asis">
+                    <span class="frequency">Used {frequency}x</span>
+                    <span class="{aa_class}">{aa_status}</span>
+                </div>
+                <div class="context-row">
+                    {context_html}
+                </div>
+            </div>
+        </div>
+        '''
+    
+    # Show count info
+    total_colors = len(color_tokens)
+    showing = min(max_colors, total_colors)
+    count_info = f"Showing {showing} of {total_colors} colors (sorted by frequency)"
+    
+    html = f'''
+    <style>
+        .colors-asis-header {{
+            font-family: system-ui, -apple-system, sans-serif;
+            font-size: 14px;
+            color: #333 !important;
+            margin-bottom: 16px;
+            padding: 8px 12px;
+            background: #e8e8e8 !important;
+            border-radius: 6px;
+        }}
+        
+        .colors-asis-preview {{
+            font-family: system-ui, -apple-system, sans-serif;
+            background: {background} !important;
+            border-radius: 12px;
+            padding: 20px;
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+            gap: 16px;
+            max-height: 800px;
+            overflow-y: auto;
+        }}
+        
+        .color-row-asis {{
+            display: flex;
+            align-items: center;
+            background: #ffffff !important;
+            border-radius: 8px;
+            padding: 12px;
+            border: 1px solid #d0d0d0 !important;
+            box-shadow: 0 1px 3px rgba(0,0,0,0.08);
+        }}
+        
+        .color-swatch-large {{
+            width: 80px;
+            height: 80px;
+            border-radius: 8px;
+            border: 2px solid rgba(0,0,0,0.15) !important;
+            margin-right: 16px;
+            flex-shrink: 0;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }}
+        
+        .swatch-hex {{
+            font-size: 11px;
+            font-family: 'SF Mono', Monaco, monospace;
+            font-weight: 600;
+            text-shadow: 0 1px 2px rgba(0,0,0,0.4);
+        }}
+        
+        .color-info-asis {{
+            flex: 1;
+            min-width: 0;
+        }}
+        
+        .color-name-asis {{
+            font-weight: 700;
+            font-size: 14px;
+            color: #1a1a1a !important;
+            margin-bottom: 6px;
+            white-space: nowrap;
+            overflow: hidden;
+            text-overflow: ellipsis;
+        }}
+        
+        .color-meta-asis {{
+            display: flex;
+            gap: 12px;
+            align-items: center;
+            margin-bottom: 6px;
+        }}
+        
+        .frequency {{
+            font-size: 12px;
+            color: #333 !important;
+            font-weight: 500;
+        }}
+        
+        .context-row {{
+            display: flex;
+            gap: 6px;
+            flex-wrap: wrap;
+        }}
+        
+        .context-badge {{
+            font-size: 10px;
+            background: #d0d0d0 !important;
+            padding: 2px 8px;
+            border-radius: 4px;
+            color: #222 !important;
+        }}
+        
+        .aa-pass {{
+            font-size: 11px;
+            color: #166534 !important;
+            font-weight: 700;
+            background: #dcfce7 !important;
+            padding: 2px 6px;
+            border-radius: 4px;
+        }}
+        
+        .aa-fail {{
+            font-size: 11px;
+            color: #991b1b !important;
+            font-weight: 700;
+            background: #fee2e2 !important;
+            padding: 2px 6px;
+            border-radius: 4px;
+        }}
+
+        /* Dark mode overrides */
+        .dark .colors-asis-header {{ color: #e2e8f0 !important; background: #1e293b !important; }}
+        .dark .colors-asis-preview {{ background: #0f172a !important; }}
+        .dark .color-row-asis {{ background: #1e293b !important; border-color: #475569 !important; }}
+        .dark .color-name-asis {{ color: #f1f5f9 !important; }}
+        .dark .frequency {{ color: #cbd5e1 !important; }}
+        .dark .context-badge {{ background: #334155 !important; color: #e2e8f0 !important; }}
+        .dark .aa-pass {{ color: #22c55e !important; background: #14532d !important; }}
+        .dark .aa-fail {{ color: #f87171 !important; background: #450a0a !important; }}
+    </style>
+    
+    <div class="colors-asis-header">{count_info}</div>
+    <div class="colors-asis-preview">
+        {rows_html}
+    </div>
+    '''
+    
+    return html
+
+
+def generate_spacing_asis_preview_html(
+    spacing_tokens: dict,
+    background: str = "#FAFAFA"
+) -> str:
+    """
+    Generate HTML preview for AS-IS spacing (Stage 1).
+    
+    Shows visual blocks representing each spacing value.
+    """
+    
+    rows_html = ""
+    
+    # Sort by pixel value
+    sorted_tokens = []
+    for name, token in spacing_tokens.items():
+        if isinstance(token, dict):
+            value_px = token.get("value_px", 0)
+            value = token.get("value", "0px")
+        else:
+            value = str(token)
+            value_px = float(re.sub(r'[^0-9.]', '', value) or 0)
+        sorted_tokens.append((name, token, value_px, value))
+    
+    sorted_tokens.sort(key=lambda x: x[2])
+    
+    for name, token, value_px, value in sorted_tokens[:15]:
+        # Cap visual width at 200px
+        visual_width = min(value_px, 200)
+        
+        rows_html += f'''
+        <div class="spacing-row-asis">
+            <div class="spacing-label">{value}</div>
+            <div class="spacing-bar" style="width: {visual_width}px;"></div>
+        </div>
+        '''
+    
+    html = f'''
+    <style>
+        .spacing-asis-preview {{
+            font-family: system-ui, -apple-system, sans-serif;
+            background: #f5f5f5 !important;
+            border-radius: 12px;
+            padding: 20px;
+        }}
+        
+        .spacing-row-asis {{
+            display: flex;
+            align-items: center;
+            margin-bottom: 12px;
+            background: #ffffff !important;
+            padding: 8px 12px;
+            border-radius: 6px;
+        }}
+        
+        .spacing-label {{
+            width: 80px;
+            font-size: 14px;
+            font-weight: 600;
+            color: #1a1a1a !important;
+            font-family: 'SF Mono', Monaco, monospace;
+        }}
+        
+        .spacing-bar {{
+            height: 24px;
+            background: linear-gradient(90deg, #3b82f6 0%, #60a5fa 100%) !important;
+            border-radius: 4px;
+            min-width: 4px;
+        }}
+
+        /* Dark mode */
+        .dark .spacing-asis-preview {{ background: #0f172a !important; }}
+        .dark .spacing-row-asis {{ background: #1e293b !important; }}
+        .dark .spacing-label {{ color: #f1f5f9 !important; }}
+    </style>
+    
+    <div class="spacing-asis-preview">
+        {rows_html}
+    </div>
+    '''
+    
+    return html
+
+
+def generate_radius_asis_preview_html(
+    radius_tokens: dict,
+    background: str = "#FAFAFA"
+) -> str:
+    """
+    Generate HTML preview for AS-IS border radius (Stage 1).
+    
+    Shows boxes with each radius value applied.
+    """
+    
+    rows_html = ""
+    
+    for name, token in list(radius_tokens.items())[:12]:
+        if isinstance(token, dict):
+            value = token.get("value", "0px")
+        else:
+            value = str(token)
+        
+        rows_html += f'''
+        <div class="radius-item">
+            <div class="radius-box" style="border-radius: {value};"></div>
+            <div class="radius-label">{value}</div>
+        </div>
+        '''
+    
+    html = f'''
+    <style>
+        .radius-asis-preview {{
+            font-family: system-ui, -apple-system, sans-serif;
+            background: #f5f5f5 !important;
+            border-radius: 12px;
+            padding: 20px;
+            display: flex;
+            flex-wrap: wrap;
+            gap: 20px;
+        }}
+        
+        .radius-item {{
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            background: #ffffff !important;
+            padding: 12px;
+            border-radius: 8px;
+        }}
+        
+        .radius-box {{
+            width: 60px;
+            height: 60px;
+            background: #3b82f6 !important;
+            margin-bottom: 8px;
+        }}
+        
+        .radius-label {{
+            font-size: 13px;
+            font-weight: 600;
+            color: #1a1a1a !important;
+            font-family: 'SF Mono', Monaco, monospace;
+        }}
+
+        /* Dark mode */
+        .dark .radius-asis-preview {{ background: #0f172a !important; }}
+        .dark .radius-item {{ background: #1e293b !important; }}
+        .dark .radius-label {{ color: #f1f5f9 !important; }}
+    </style>
+    
+    <div class="radius-asis-preview">
+        {rows_html}
+    </div>
+    '''
+    
+    return html
+
+
+def generate_shadows_asis_preview_html(
+    shadow_tokens: dict,
+    background: str = "#FAFAFA"
+) -> str:
+    """
+    Generate HTML preview for AS-IS shadows (Stage 1).
+    
+    Shows cards with each shadow value applied.
+    """
+    
+    rows_html = ""
+    
+    for name, token in list(shadow_tokens.items())[:8]:
+        if isinstance(token, dict):
+            value = token.get("value", "none")
+        else:
+            value = str(token)
+        
+        # Clean name for display
+        display_name = name.replace("_", " ").replace("-", " ").title()
+        if len(display_name) > 15:
+            display_name = display_name[:12] + "..."
+        
+        rows_html += f'''
+        <div class="shadow-item">
+            <div class="shadow-box" style="box-shadow: {value};"></div>
+            <div class="shadow-label">{display_name}</div>
+            <div class="shadow-value">{value[:40]}...</div>
+        </div>
+        '''
+    
+    html = f'''
+    <style>
+        .shadows-asis-preview {{
+            font-family: system-ui, -apple-system, sans-serif;
+            background: #f5f5f5 !important;
+            border-radius: 12px;
+            padding: 20px;
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));
+            gap: 24px;
+        }}
+        
+        .shadow-item {{
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            background: #e8e8e8 !important;
+            padding: 16px;
+            border-radius: 8px;
+        }}
+        
+        .shadow-box {{
+            width: 100px;
+            height: 100px;
+            background: #ffffff !important;
+            border-radius: 8px;
+            margin-bottom: 12px;
+        }}
+        
+        .shadow-label {{
+            font-size: 13px;
+            font-weight: 600;
+            color: #1a1a1a !important;
+            margin-bottom: 4px;
+        }}
+        
+        .shadow-value {{
+            font-size: 10px;
+            color: #444 !important;
+            font-family: 'SF Mono', Monaco, monospace;
+            text-align: center;
+            word-break: break-all;
+        }}
+
+        /* Dark mode */
+        .dark .shadows-asis-preview {{ background: #0f172a !important; }}
+        .dark .shadow-item {{ background: #1e293b !important; }}
+        .dark .shadow-box {{ background: #334155 !important; }}
+        .dark .shadow-label {{ color: #f1f5f9 !important; }}
+        .dark .shadow-value {{ color: #94a3b8 !important; }}
+    </style>
+    
+    <div class="shadows-asis-preview">
+        {rows_html}
+    </div>
+    '''
+    
+    return html
+
+
+# =============================================================================
+# STAGE 2: TYPOGRAPHY PREVIEW (with rendered font)
+# =============================================================================
+
+def generate_typography_preview_html(
+    typography_tokens: dict,
+    font_family: str = "Open Sans",
+    background: str = "#FAFAFA",
+    sample_text: str = "The quick brown fox jumps over the lazy dog"
+) -> str:
+    """
+    Generate HTML preview for typography tokens.
+    
+    Args:
+        typography_tokens: Dict of typography styles {name: {font_size, font_weight, line_height, letter_spacing}}
+        font_family: Primary font family detected
+        background: Background color (neutral)
+        sample_text: Text to render for preview
+    
+    Returns:
+        HTML string for Gradio HTML component
+    """
+    
+    # Sort tokens by font size (largest first)
+    sorted_tokens = []
+    for name, token in typography_tokens.items():
+        size_str = str(token.get("font_size", "16px"))
+        size_num = float(re.sub(r'[^0-9.]', '', size_str) or 16)
+        sorted_tokens.append((name, token, size_num))
+    
+    sorted_tokens.sort(key=lambda x: -x[2])  # Descending by size
+    
+    # Generate rows
+    rows_html = ""
+    for name, token, size_num in sorted_tokens[:15]:  # Limit to 15 styles
+        font_size = token.get("font_size", "16px")
+        font_weight = token.get("font_weight", "400")
+        line_height = token.get("line_height", "1.5")
+        letter_spacing = token.get("letter_spacing", "0")
+        
+        # Convert weight names to numbers
+        weight_map = {
+            "thin": 100, "extralight": 200, "light": 300, "regular": 400,
+            "medium": 500, "semibold": 600, "bold": 700, "extrabold": 800, "black": 900
+        }
+        if isinstance(font_weight, str) and font_weight.lower() in weight_map:
+            font_weight = weight_map[font_weight.lower()]
+        
+        # Weight label
+        weight_labels = {
+            100: "Thin", 200: "ExtraLight", 300: "Light", 400: "Regular",
+            500: "Medium", 600: "SemiBold", 700: "Bold", 800: "ExtraBold", 900: "Black"
+        }
+        weight_label = weight_labels.get(int(font_weight) if str(font_weight).isdigit() else 400, "Regular")
+        
+        # Clean up name for display
+        display_name = name.replace("_", " ").replace("-", " ").title()
+        if len(display_name) > 15:
+            display_name = display_name[:15] + "..."
+        
+        # Truncate sample text for large sizes
+        display_text = sample_text
+        if size_num > 48:
+            display_text = sample_text[:30] + "..."
+        elif size_num > 32:
+            display_text = sample_text[:40] + "..."
+        
+        rows_html += f'''
+        <tr class="meta-row">
+            <td class="scale-name">
+                <div class="scale-label">{display_name}</div>
+            </td>
+            <td class="meta">{font_family}</td>
+            <td class="meta">{weight_label}</td>
+            <td class="meta">{int(size_num)}</td>
+            <td class="meta">Sentence</td>
+            <td class="meta">{letter_spacing}</td>
+        </tr>
+        <tr>
+            <td colspan="6" class="preview-cell">
+                <div class="preview-text" style="
+                    font-family: '{font_family}', sans-serif;
+                    font-size: {font_size};
+                    font-weight: {font_weight};
+                    line-height: {line_height};
+                    letter-spacing: {letter_spacing}px;
+                ">{display_text}</div>
+            </td>
+        </tr>
+        '''
+    
+    html = f'''
+    <style>
+        @import url('https://fonts.googleapis.com/css2?family={font_family.replace(" ", "+")}:wght@100;200;300;400;500;600;700;800;900&display=swap');
+        
+        .typography-preview {{
+            font-family: system-ui, -apple-system, sans-serif;
+            background: {background};
+            border-radius: 12px;
+            padding: 20px;
+            overflow-x: auto;
+        }}
+        
+        .typography-preview table {{
+            width: 100%;
+            border-collapse: collapse;
+        }}
+        
+        .typography-preview th {{
+            text-align: left;
+            padding: 12px 16px;
+            font-size: 12px;
+            font-weight: 600;
+            color: #333;
+            text-transform: uppercase;
+            letter-spacing: 0.5px;
+            border-bottom: 2px solid #E0E0E0;
+            background: #F5F5F5;
+        }}
+        
+        .typography-preview td {{
+            padding: 8px 16px;
+            vertical-align: middle;
+        }}
+        
+        .typography-preview .meta-row {{
+            background: #F8F8F8;
+            border-top: 1px solid #E8E8E8;
+        }}
+        
+        .typography-preview .scale-name {{
+            font-weight: 700;
+            color: #1A1A1A;
+            min-width: 120px;
+        }}
+        
+        .typography-preview .scale-label {{
+            font-size: 13px;
+            font-weight: 600;
+            color: #1A1A1A;
+            background: #E8E8E8;
+            padding: 4px 8px;
+            border-radius: 4px;
+            display: inline-block;
+        }}
+        
+        .typography-preview .meta {{
+            font-size: 13px;
+            color: #444;
+            white-space: nowrap;
+        }}
+        
+        .typography-preview .preview-cell {{
+            padding: 16px;
+            background: #FFFFFF;
+            border-bottom: 1px solid #E8E8E8;
+        }}
+        
+        .typography-preview .preview-text {{
+            color: #1A1A1A;
+            margin: 0;
+            word-break: break-word;
+        }}
+        
+        .typography-preview tr:hover .preview-cell {{
+            background: #F5F5F5;
+        }}
+
+        /* Dark mode */
+        .dark .typography-preview {{ background: #1e293b !important; }}
+        .dark .typography-preview th {{ background: #334155 !important; color: #e2e8f0 !important; border-bottom-color: #475569 !important; }}
+        .dark .typography-preview td {{ color: #e2e8f0 !important; }}
+        .dark .typography-preview .meta-row {{ background: #1e293b !important; border-top-color: #334155 !important; }}
+        .dark .typography-preview .scale-name,
+        .dark .typography-preview .scale-label {{ color: #f1f5f9 !important; background: #475569 !important; }}
+        .dark .typography-preview .meta {{ color: #cbd5e1 !important; }}
+        .dark .typography-preview .preview-cell {{ background: #0f172a !important; border-bottom-color: #334155 !important; }}
+        .dark .typography-preview .preview-text {{ color: #f1f5f9 !important; }}
+        .dark .typography-preview tr:hover .preview-cell {{ background: #1e293b !important; }}
+    </style>
+    
+    <div class="typography-preview">
+        <table>
+            <thead>
+                <tr>
+                    <th>Scale Category</th>
+                    <th>Typeface</th>
+                    <th>Weight</th>
+                    <th>Size</th>
+                    <th>Case</th>
+                    <th>Letter Spacing</th>
+                </tr>
+            </thead>
+            <tbody>
+                {rows_html}
+            </tbody>
+        </table>
+    </div>
+    '''
+    
+    return html
+
+
+# =============================================================================
+# COLOR RAMP PREVIEW
+# =============================================================================
+
+def hex_to_rgb(hex_color: str) -> tuple:
+    """Convert hex color 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(rgb: tuple) -> str:
+    """Convert RGB tuple to hex string."""
+    return '#{:02x}{:02x}{:02x}'.format(int(rgb[0]), int(rgb[1]), int(rgb[2]))
+
+
+def get_luminance(rgb: tuple) -> float:
+    """Calculate relative luminance for contrast ratio."""
+    def adjust(c):
+        c = c / 255
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+    
+    r, g, b = rgb
+    return 0.2126 * adjust(r) + 0.7152 * adjust(g) + 0.0722 * adjust(b)
+
+
+def get_contrast_ratio(color1: tuple, color2: tuple) -> float:
+    """Calculate contrast ratio between two colors."""
+    l1 = get_luminance(color1)
+    l2 = get_luminance(color2)
+    lighter = max(l1, l2)
+    darker = min(l1, l2)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def generate_color_ramp(base_hex: str) -> list[dict]:
+    """
+    Generate 11 shades (50-950) from a base color.
+    
+    Uses OKLCH-like approach for perceptually uniform steps.
+    """
+    try:
+        rgb = hex_to_rgb(base_hex)
+    except:
+        return []
+    
+    # Convert to HLS for easier manipulation
+    r, g, b = [x / 255 for x in rgb]
+    h, l, s = colorsys.rgb_to_hls(r, g, b)
+    
+    # Define lightness levels for each shade
+    # 50 = very light (0.95), 500 = base, 950 = very dark (0.05)
+    shade_lightness = {
+        50: 0.95,
+        100: 0.90,
+        200: 0.80,
+        300: 0.70,
+        400: 0.60,
+        500: l,  # Keep original lightness for 500
+        600: 0.45,
+        700: 0.35,
+        800: 0.25,
+        900: 0.15,
+        950: 0.08,
+    }
+    
+    # Adjust saturation for light/dark shades
+    ramp = []
+    for shade, target_l in shade_lightness.items():
+        # Reduce saturation for very light colors
+        if target_l > 0.8:
+            adjusted_s = s * 0.6
+        elif target_l < 0.2:
+            adjusted_s = s * 0.8
+        else:
+            adjusted_s = s
+        
+        # Generate new RGB
+        new_r, new_g, new_b = colorsys.hls_to_rgb(h, target_l, adjusted_s)
+        new_rgb = (int(new_r * 255), int(new_g * 255), int(new_b * 255))
+        new_hex = rgb_to_hex(new_rgb)
+        
+        # Check AA compliance
+        white = (255, 255, 255)
+        black = (0, 0, 0)
+        contrast_white = get_contrast_ratio(new_rgb, white)
+        contrast_black = get_contrast_ratio(new_rgb, black)
+        
+        # AA requires 4.5:1 for normal text
+        aa_on_white = contrast_white >= 4.5
+        aa_on_black = contrast_black >= 4.5
+        
+        ramp.append({
+            "shade": shade,
+            "hex": new_hex,
+            "rgb": new_rgb,
+            "contrast_white": round(contrast_white, 2),
+            "contrast_black": round(contrast_black, 2),
+            "aa_on_white": aa_on_white,
+            "aa_on_black": aa_on_black,
+        })
+    
+    return ramp
+
+
+def generate_color_ramps_preview_html(
+    color_tokens: dict,
+    background: str = "#FAFAFA",
+    max_colors: int = 20
+) -> str:
+    """
+    Generate HTML preview for color ramps.
+    
+    Sorts colors by frequency and filters out near-white/near-black
+    to prioritize showing actual brand colors.
+    
+    Args:
+        color_tokens: Dict of colors {name: {value: "#hex", ...}}
+        background: Background color
+        max_colors: Maximum colors to show ramps for
+    
+    Returns:
+        HTML string for Gradio HTML component
+    """
+    
+    def get_color_priority(name, token):
+        """Calculate priority score for a color (higher = more important)."""
+        if isinstance(token, dict):
+            hex_val = token.get("value", "#888888")
+            frequency = token.get("frequency", 0)
+        else:
+            hex_val = str(token)
+            frequency = 0
+        
+        # Clean hex
+        if not hex_val.startswith("#"):
+            hex_val = f"#{hex_val}"
+        
+        # Calculate luminance
+        try:
+            r = int(hex_val[1:3], 16)
+            g = int(hex_val[3:5], 16)
+            b = int(hex_val[5:7], 16)
+            luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255
+            
+            # Calculate saturation (simplified)
+            max_c = max(r, g, b)
+            min_c = min(r, g, b)
+            saturation = (max_c - min_c) / 255 if max_c > 0 else 0
+        except:
+            luminance = 0.5
+            saturation = 0
+        
+        # Priority scoring:
+        # - Penalize near-white (luminance > 0.9)
+        # - Penalize near-black (luminance < 0.1)
+        # - Penalize low saturation (grays)
+        # - Reward high frequency
+        # - Reward colors with "primary", "brand", "accent" in name
+        
+        score = frequency * 10  # Base score from frequency
+        
+        # Penalize extremes
+        if luminance > 0.9:
+            score -= 500  # Near white
+        if luminance < 0.1:
+            score -= 300  # Near black
+        
+        # Reward saturated colors (actual brand colors)
+        score += saturation * 200
+        
+        # Reward named brand colors
+        name_lower = name.lower()
+        if any(kw in name_lower for kw in ['primary', 'brand', 'accent', 'cyan', 'blue', 'green', 'red', 'orange', 'purple']):
+            score += 100
+        
+        # Penalize "background", "border", "text" colors
+        if any(kw in name_lower for kw in ['background', 'border', 'neutral', 'gray', 'grey']):
+            score -= 50
+        
+        return score
+    
+    # Sort colors by priority
+    sorted_colors = []
+    for name, token in color_tokens.items():
+        priority = get_color_priority(name, token)
+        sorted_colors.append((name, token, priority))
+    
+    sorted_colors.sort(key=lambda x: -x[2])  # Descending by priority
+    
+    rows_html = ""
+    shown_count = 0
+    
+    for name, token, priority in sorted_colors:
+        if shown_count >= max_colors:
+            break
+            
+        # Get hex value
+        if isinstance(token, dict):
+            hex_val = token.get("value", "#888888")
+        else:
+            hex_val = str(token)
+        
+        # Clean up hex
+        if not hex_val.startswith("#"):
+            hex_val = f"#{hex_val}"
+        
+        # Skip invalid hex
+        if len(hex_val) < 7:
+            continue
+        
+        # Generate ramp
+        ramp = generate_color_ramp(hex_val)
+        if not ramp:
+            continue
+        
+        # Clean name
+        display_name = name.replace("_", " ").replace("-", " ").replace(".", " ").title()
+        if len(display_name) > 18:
+            display_name = display_name[:15] + "..."
+        
+        # Generate shade cells
+        shades_html = ""
+        for shade_info in ramp:
+            shade = shade_info["shade"]
+            hex_color = shade_info["hex"]
+            aa_white = shade_info["aa_on_white"]
+            aa_black = shade_info["aa_on_black"]
+            
+            # Determine text color for label
+            text_color = "#000" if shade < 500 else "#FFF"
+            
+            # AA indicator
+            if aa_white or aa_black:
+                aa_indicator = "✓"
+                aa_class = "aa-pass"
+            else:
+                aa_indicator = ""
+                aa_class = ""
+            
+            shades_html += f'''
+            <div class="shade-cell" style="background-color: {hex_color};" title="{hex_color} | AA: {'Pass' if aa_white or aa_black else 'Fail'}">
+                <span class="shade-label" style="color: {text_color};">{shade}</span>
+                <span class="aa-badge {aa_class}">{aa_indicator}</span>
+            </div>
+            '''
+        
+        rows_html += f'''
+        <div class="color-row">
+            <div class="color-info">
+                <div class="color-swatch" style="background-color: {hex_val};"></div>
+                <div class="color-meta">
+                    <div class="color-name">{display_name}</div>
+                    <div class="color-hex">{hex_val}</div>
+                </div>
+            </div>
+            <div class="color-ramp">
+                {shades_html}
+            </div>
+        </div>
+        '''
+        shown_count += 1
+    
+    # Count info
+    total_colors = len(color_tokens)
+    count_info = f"Showing {shown_count} of {total_colors} colors (sorted by brand priority)"
+    
+    html = f'''
+    <style>
+        .color-ramps-preview {{
+            font-family: system-ui, -apple-system, sans-serif;
+            background: #f5f5f5 !important;
+            border-radius: 12px;
+            padding: 20px;
+            overflow-x: auto;
+        }}
+        
+        .color-row {{
+            display: flex;
+            align-items: center;
+            margin-bottom: 16px;
+            padding: 12px;
+            background: #ffffff !important;
+            border-radius: 8px;
+            border: 1px solid #d0d0d0 !important;
+        }}
+        
+        .color-row:last-child {{
+            margin-bottom: 0;
+        }}
+        
+        .color-info {{
+            display: flex;
+            align-items: center;
+            min-width: 160px;
+            margin-right: 20px;
+        }}
+        
+        .color-swatch {{
+            width: 44px;
+            height: 44px;
+            border-radius: 8px;
+            border: 2px solid rgba(0,0,0,0.15) !important;
+            margin-right: 12px;
+            flex-shrink: 0;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }}
+        
+        .color-meta {{
+            flex: 1;
+            min-width: 100px;
+        }}
+        
+        .color-name {{
+            font-weight: 700;
+            font-size: 13px;
+            color: #1a1a1a !important;
+            margin-bottom: 4px;
+            background: #e0e0e0 !important;
+            padding: 4px 10px;
+            border-radius: 4px;
+            display: inline-block;
+        }}
+        
+        .color-hex {{
+            font-size: 12px;
+            color: #333 !important;
+            font-family: 'SF Mono', Monaco, monospace;
+            margin-top: 4px;
+            font-weight: 500;
+        }}
+        
+        .color-ramp {{
+            display: flex;
+            gap: 4px;
+            flex: 1;
+        }}
+        
+        .shade-cell {{
+            width: 48px;
+            height: 48px;
+            border-radius: 6px;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            position: relative;
+            cursor: pointer;
+            transition: transform 0.15s;
+            border: 1px solid rgba(0,0,0,0.1) !important;
+        }}
+        
+        .shade-cell:hover {{
+            transform: scale(1.1);
+            z-index: 10;
+            box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+        }}
+        
+        .shade-label {{
+            font-size: 10px;
+            font-weight: 700;
+        }}
+        
+        .aa-badge {{
+            font-size: 12px;
+            margin-top: 2px;
+            font-weight: 700;
+        }}
+        
+        .aa-pass {{
+            color: #166534 !important;
+        }}
+        
+        .aa-fail {{
+            color: #991b1b !important;
+        }}
+        
+        .shade-cell:hover .shade-label,
+        .shade-cell:hover .aa-badge {{
+            opacity: 1;
+        }}
+        
+        /* Header row */
+        .ramp-header {{
+            display: flex;
+            margin-bottom: 12px;
+            padding-left: 180px;
+            background: #e8e8e8 !important;
+            padding-top: 8px;
+            padding-bottom: 8px;
+            border-radius: 6px;
+        }}
+        
+        .ramp-header-label {{
+            width: 48px;
+            text-align: center;
+            font-size: 12px;
+            font-weight: 700;
+            color: #333 !important;
+            margin-right: 4px;
+        }}
+        
+        .ramps-header-info {{
+            font-size: 14px;
+            color: #333 !important;
+            margin-bottom: 16px;
+            padding: 10px 14px;
+            background: #e0e0e0 !important;
+            border-radius: 6px;
+            font-weight: 500;
+        }}
+
+        /* Dark mode */
+        .dark .color-ramps-preview {{ background: #0f172a !important; }}
+        .dark .ramps-header-info {{ color: #e2e8f0 !important; background: #1e293b !important; }}
+        .dark .ramp-header {{ background: #1e293b !important; }}
+        .dark .ramp-header-label {{ color: #cbd5e1 !important; }}
+        .dark .color-row {{ background: #1e293b !important; border-color: #475569 !important; }}
+        .dark .color-name {{ color: #f1f5f9 !important; background: #475569 !important; }}
+        .dark .color-hex {{ color: #cbd5e1 !important; }}
+    </style>
+    
+    <div class="color-ramps-preview">
+        <div class="ramps-header-info">{count_info}</div>
+        <div class="ramp-header">
+            <span class="ramp-header-label">50</span>
+            <span class="ramp-header-label">100</span>
+            <span class="ramp-header-label">200</span>
+            <span class="ramp-header-label">300</span>
+            <span class="ramp-header-label">400</span>
+            <span class="ramp-header-label">500</span>
+            <span class="ramp-header-label">600</span>
+            <span class="ramp-header-label">700</span>
+            <span class="ramp-header-label">800</span>
+            <span class="ramp-header-label">900</span>
+            <span class="ramp-header-label">950</span>
+        </div>
+        {rows_html}
+    </div>
+    '''
+    
+    return html
+
+
+# =============================================================================
+# SEMANTIC COLOR RAMPS WITH LLM RECOMMENDATIONS (Stage 2)
+# =============================================================================
+
+def generate_semantic_color_ramps_html(
+    semantic_analysis: dict,
+    color_tokens: dict,
+    llm_recommendations: dict = None,
+    background: str = "#F5F5F5"
+) -> str:
+    """
+    Generate HTML preview for colors organized by semantic role with LLM recommendations.
+    
+    Args:
+        semantic_analysis: Output from SemanticColorAnalyzer
+        color_tokens: Dict of all color tokens
+        llm_recommendations: LLM suggestions for color improvements
+        background: Background color
+    
+    Returns:
+        HTML string for Gradio HTML component
+    """
+    
+    def generate_single_ramp(hex_val: str) -> str:
+        """Generate a single color ramp HTML."""
+        ramp = generate_color_ramp(hex_val)
+        if not ramp:
+            return ""
+        
+        shades_html = ""
+        for shade_info in ramp:
+            shade = shade_info["shade"]
+            hex_color = shade_info["hex"]
+            aa_white = shade_info["aa_on_white"]
+            aa_black = shade_info["aa_on_black"]
+            
+            text_color = "#000" if shade < 500 else "#FFF"
+            aa_indicator = "✓" if aa_white or aa_black else ""
+            
+            shades_html += f'''
+            <div class="sem-shade" style="background-color: {hex_color};">
+                <span class="sem-shade-num" style="color: {text_color};">{shade}</span>
+                <span class="sem-shade-aa" style="color: {text_color};">{aa_indicator}</span>
+            </div>
+            '''
+        return shades_html
+    
+    def color_row_with_recommendation(hex_val: str, role: str, role_display: str, recommendation: dict = None) -> str:
+        """Generate a color row with optional LLM recommendation."""
+        ramp_html = generate_single_ramp(hex_val)
+        
+        # Calculate contrast
+        try:
+            from core.color_utils import get_contrast_with_white
+            contrast = get_contrast_with_white(hex_val)
+            aa_status = "✓ AA" if contrast >= 4.5 else f"⚠️ {contrast:.1f}:1"
+            aa_class = "aa-ok" if contrast >= 4.5 else "aa-warn"
+        except:
+            aa_status = ""
+            aa_class = ""
+        
+        # LLM recommendation display
+        rec_html = ""
+        if recommendation:
+            suggested = recommendation.get("suggested", "")
+            issue = recommendation.get("issue", "")
+            if suggested and suggested != hex_val:
+                rec_html = f'''
+                <div class="llm-rec">
+                    <span class="rec-label">💡 LLM:</span>
+                    <span class="rec-issue">{issue}</span>
+                    <span class="rec-arrow">→</span>
+                    <span class="rec-suggested" style="background-color: {suggested};">{suggested}</span>
+                </div>
+                '''
+        
+        return f'''
+        <div class="sem-color-row">
+            <div class="sem-color-info">
+                <div class="sem-swatch" style="background-color: {hex_val};"></div>
+                <div class="sem-details">
+                    <div class="sem-role">{role_display}</div>
+                    <div class="sem-hex">{hex_val} <span class="{aa_class}">{aa_status}</span></div>
+                </div>
+            </div>
+            <div class="sem-ramp">{ramp_html}</div>
+            {rec_html}
+        </div>
+        '''
+    
+    def category_section(title: str, icon: str, colors: dict, category_key: str) -> str:
+        """Generate a category section with color rows."""
+        if not colors:
+            return ""
+        
+        rows_html = ""
+        for role, data in colors.items():
+            if data and isinstance(data, dict) and "hex" in data:
+                # Get LLM recommendation for this role
+                rec = None
+                if llm_recommendations:
+                    color_recs = llm_recommendations.get("color_recommendations", {})
+                    rec = color_recs.get(f"{category_key}.{role}", {})
+                
+                role_display = role.replace("_", " ").title()
+                rows_html += color_row_with_recommendation(
+                    data["hex"],
+                    f"{category_key}.{role}",
+                    role_display,
+                    rec
+                )
+        
+        if not rows_html:
+            return ""
+        
+        return f'''
+        <div class="sem-category">
+            <h3 class="sem-cat-title">{icon} {title}</h3>
+            {rows_html}
+        </div>
+        '''
+    
+    # Handle empty analysis
+    if not semantic_analysis:
+        return '''
+        <div class="sem-warning-box" style="padding: 40px; text-align: center; background: #fff3cd; border-radius: 8px;">
+            <p style="color: #856404; font-size: 14px;">⚠️ No semantic analysis available.</p>
+        </div>
+        <style>
+            .dark .sem-warning-box { background: #422006 !important; border-color: #b45309 !important; }
+            .dark .sem-warning-box p { color: #fde68a !important; }
+        </style>
+        '''
+    
+    # Build sections
+    sections_html = ""
+    sections_html += category_section("Brand Colors", "🎨", semantic_analysis.get("brand", {}), "brand")
+    sections_html += category_section("Text Colors", "📝", semantic_analysis.get("text", {}), "text")
+    sections_html += category_section("Background Colors", "🖼️", semantic_analysis.get("background", {}), "background")
+    sections_html += category_section("Border Colors", "📏", semantic_analysis.get("border", {}), "border")
+    sections_html += category_section("Feedback Colors", "🚨", semantic_analysis.get("feedback", {}), "feedback")
+    
+    # LLM Impact Summary
+    llm_summary = ""
+    if llm_recommendations:
+        changes = llm_recommendations.get("changes_made", [])
+        if changes:
+            changes_html = "".join([f"<li>{c}</li>" for c in changes[:5]])
+            llm_summary = f'''
+            <div class="llm-summary">
+                <h4>🤖 LLM Recommendations Applied:</h4>
+                <ul>{changes_html}</ul>
+            </div>
+            '''
+    
+    html = f'''
+    <style>
+        .sem-ramps-preview {{
+            font-family: system-ui, -apple-system, sans-serif;
+            background: #f5f5f5 !important;
+            border-radius: 12px;
+            padding: 20px;
+        }}
+        
+        .sem-category {{
+            background: #ffffff !important;
+            border-radius: 8px;
+            padding: 16px;
+            margin-bottom: 20px;
+            border: 1px solid #d0d0d0 !important;
+        }}
+        
+        .sem-cat-title {{
+            font-size: 16px;
+            font-weight: 700;
+            color: #1a1a1a !important;
+            margin: 0 0 16px 0;
+            padding-bottom: 8px;
+            border-bottom: 2px solid #e0e0e0 !important;
+        }}
+        
+        .sem-color-row {{
+            display: flex;
+            flex-wrap: wrap;
+            align-items: center;
+            padding: 12px;
+            background: #f8f8f8 !important;
+            border-radius: 6px;
+            margin-bottom: 12px;
+            border: 1px solid #e0e0e0 !important;
+        }}
+        
+        .sem-color-row:last-child {{
+            margin-bottom: 0;
+        }}
+        
+        .sem-color-info {{
+            display: flex;
+            align-items: center;
+            min-width: 180px;
+            margin-right: 16px;
+        }}
+        
+        .sem-swatch {{
+            width: 48px;
+            height: 48px;
+            border-radius: 8px;
+            border: 2px solid rgba(0,0,0,0.15) !important;
+            margin-right: 12px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }}
+        
+        .sem-details {{
+            flex: 1;
+        }}
+        
+        .sem-role {{
+            font-weight: 700;
+            font-size: 14px;
+            color: #1a1a1a !important;
+            margin-bottom: 4px;
+        }}
+        
+        .sem-hex {{
+            font-size: 12px;
+            font-family: 'SF Mono', Monaco, monospace;
+            color: #333 !important;
+        }}
+        
+        .aa-ok {{
+            color: #166534 !important;
+            font-weight: 600;
+        }}
+        
+        .aa-warn {{
+            color: #b45309 !important;
+            font-weight: 600;
+        }}
+        
+        .sem-ramp {{
+            display: flex;
+            gap: 3px;
+            flex: 1;
+            min-width: 400px;
+        }}
+        
+        .sem-shade {{
+            width: 36px;
+            height: 36px;
+            border-radius: 4px;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: center;
+            border: 1px solid rgba(0,0,0,0.1) !important;
+        }}
+        
+        .sem-shade-num {{
+            font-size: 9px;
+            font-weight: 700;
+        }}
+        
+        .sem-shade-aa {{
+            font-size: 10px;
+        }}
+        
+        .llm-rec {{
+            width: 100%;
+            margin-top: 10px;
+            padding: 8px 12px;
+            background: #fef3c7 !important;
+            border-radius: 4px;
+            display: flex;
+            align-items: center;
+            gap: 8px;
+            border: 1px solid #f59e0b !important;
+        }}
+        
+        .rec-label {{
+            font-weight: 600;
+            color: #92400e !important;
+        }}
+        
+        .rec-issue {{
+            color: #78350f !important;
+            font-size: 13px;
+        }}
+        
+        .rec-arrow {{
+            color: #92400e !important;
+        }}
+        
+        .rec-suggested {{
+            padding: 4px 10px;
+            border-radius: 4px;
+            font-family: 'SF Mono', Monaco, monospace;
+            font-size: 12px;
+            font-weight: 600;
+            color: #fff !important;
+            text-shadow: 0 1px 2px rgba(0,0,0,0.3);
+        }}
+        
+        .llm-summary {{
+            background: #dbeafe !important;
+            border: 1px solid #3b82f6 !important;
+            border-radius: 8px;
+            padding: 16px;
+            margin-top: 20px;
+        }}
+        
+        .llm-summary h4 {{
+            color: #1e40af !important;
+            margin: 0 0 12px 0;
+            font-size: 14px;
+        }}
+        
+        .llm-summary ul {{
+            margin: 0;
+            padding-left: 20px;
+            color: #1e3a8a !important;
+        }}
+        
+        .llm-summary li {{
+            margin-bottom: 4px;
+            font-size: 13px;
+        }}
+
+        /* Dark mode */
+        .dark .sem-ramps-preview {{ background: #0f172a !important; }}
+        .dark .sem-category {{ background: #1e293b !important; border-color: #475569 !important; }}
+        .dark .sem-cat-title {{ color: #f1f5f9 !important; border-bottom-color: #475569 !important; }}
+        .dark .sem-color-row {{ background: #0f172a !important; border-color: #334155 !important; }}
+        .dark .sem-role {{ color: #f1f5f9 !important; }}
+        .dark .sem-hex {{ color: #cbd5e1 !important; }}
+        .dark .llm-rec {{ background: #422006 !important; border-color: #b45309 !important; }}
+        .dark .rec-label {{ color: #fbbf24 !important; }}
+        .dark .rec-issue {{ color: #fde68a !important; }}
+        .dark .rec-arrow {{ color: #fbbf24 !important; }}
+        .dark .llm-summary {{ background: #1e3a5f !important; border-color: #3b82f6 !important; }}
+        .dark .llm-summary h4 {{ color: #93c5fd !important; }}
+        .dark .llm-summary ul, .dark .llm-summary li {{ color: #bfdbfe !important; }}
+    </style>
+    
+    <div class="sem-ramps-preview">
+        {sections_html}
+        {llm_summary}
+    </div>
+    '''
+    
+    return html
+
+
+# =============================================================================
+# COMBINED PREVIEW
+# =============================================================================
+
+def generate_design_system_preview_html(
+    typography_tokens: dict,
+    color_tokens: dict,
+    font_family: str = "Open Sans",
+    sample_text: str = "The quick brown fox jumps over the lazy dog"
+) -> tuple[str, str]:
+    """
+    Generate both typography and color ramp previews.
+    
+    Returns:
+        Tuple of (typography_html, color_ramps_html)
+    """
+    typography_html = generate_typography_preview_html(
+        typography_tokens=typography_tokens,
+        font_family=font_family,
+        sample_text=sample_text,
+    )
+    
+    color_ramps_html = generate_color_ramps_preview_html(
+        color_tokens=color_tokens,
+    )
+    
+    return typography_html, color_ramps_html