Delete core/preview_generator.py

core/preview_generator.py

@@ -1,1534 +0,0 @@
-"""
-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