sonance-brand-mcp 1.3.51 → 1.3.55

package/dist/assets/api/sonance-vision-apply/theme-discovery.ts

@@ -0,0 +1,755 @@
+/**
+ * Theme Discovery Module for Sonance DevTools
+ * 
+ * Dynamically discovers and parses theme/design system files from target codebases.
+ * Extracts CSS variables, Tailwind colors, and available semantic tokens to provide
+ * context to the LLM for intelligent styling decisions.
+ * 
+ * NEW: Includes WCAG contrast ratio calculation to warn about bad color combinations.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+// ============================================================================
+// TYPE DEFINITIONS
+// ============================================================================
+
+/**
+ * RGB color representation
+ */
+interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * Contrast warning for a failing color combination
+ */
+interface ContrastWarning {
+  background: string;
+  text: string;
+  ratio: string;
+  suggestion: string;
+}
+
+/**
+ * Safe color pattern that passes WCAG
+ */
+interface SafePattern {
+  background: string;
+  text: string;
+  ratio: string;
+}
+
+/**
+ * Result of contrast analysis
+ */
+interface ContrastAnalysis {
+  warnings: ContrastWarning[];
+  safePatterns: SafePattern[];
+}
+
+/**
+ * Discovered theme information from a codebase
+ */
+export interface DiscoveredTheme {
+  // Raw CSS variable definitions found (e.g., { "--accent": "#00D3C8" })
+  cssVariables: Record<string, string>;
+  
+  // Tailwind custom colors from config (if found)
+  tailwindColors: Record<string, string>;
+  
+  // Available semantic class tokens discovered
+  availableTokens: string[];
+  
+  // Full raw theme CSS content for additional context
+  rawThemeCSS: string;
+  
+  // Files that were discovered and parsed
+  discoveredFiles: string[];
+  
+  // Contrast analysis results
+  contrastAnalysis?: ContrastAnalysis;
+}
+
+// ============================================================================
+// COLOR PARSING FUNCTIONS
+// ============================================================================
+
+/**
+ * Convert HSL values to RGB
+ * Handles formats: "195 100% 41%" or "hsl(195, 100%, 41%)" or "195deg 100% 41%"
+ */
+function hslToRgb(h: number, s: number, l: number): RGB {
+  // Normalize h to 0-360, s and l to 0-1
+  h = ((h % 360) + 360) % 360;
+  s = Math.max(0, Math.min(1, s / 100));
+  l = Math.max(0, Math.min(1, l / 100));
+  
+  const k = (n: number) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  
+  return {
+    r: Math.round(f(0) * 255),
+    g: Math.round(f(8) * 255),
+    b: Math.round(f(4) * 255),
+  };
+}
+
+/**
+ * Parse hex color to RGB
+ * Handles: #fff, #ffffff, fff, ffffff
+ */
+function hexToRgb(hex: string): RGB | null {
+  // Remove # if present
+  hex = hex.replace(/^#/, "");
+  
+  // Expand shorthand (e.g., "fff" -> "ffffff")
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+  }
+  
+  if (hex.length !== 6) {
+    return null;
+  }
+  
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+  
+  if (isNaN(r) || isNaN(g) || isNaN(b)) {
+    return null;
+  }
+  
+  return { r, g, b };
+}
+
+/**
+ * Parse CSS color value to RGB
+ * Handles multiple formats:
+ * - Hex: #fff, #ffffff
+ * - RGB: rgb(255, 255, 255), rgb(255 255 255)
+ * - HSL: hsl(195, 100%, 41%), hsl(195 100% 41%)
+ * - Space-separated HSL: 195 100% 41% (common in Tailwind/shadcn)
+ * - oklch: oklch(0.7 0.15 195) - approximated
+ */
+function parseColorToRgb(value: string): RGB | null {
+  if (!value || typeof value !== "string") {
+    return null;
+  }
+  
+  const trimmed = value.trim().toLowerCase();
+  
+  // Skip CSS variable references - we can't resolve these without runtime
+  if (trimmed.includes("var(")) {
+    return null;
+  }
+  
+  // Handle hex colors
+  if (trimmed.startsWith("#") || /^[0-9a-f]{3,6}$/i.test(trimmed)) {
+    return hexToRgb(trimmed);
+  }
+  
+  // Handle rgb() and rgba()
+  const rgbMatch = trimmed.match(/rgba?\s*\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/);
+  if (rgbMatch) {
+    return {
+      r: parseInt(rgbMatch[1], 10),
+      g: parseInt(rgbMatch[2], 10),
+      b: parseInt(rgbMatch[3], 10),
+    };
+  }
+  
+  // Handle hsl() and hsla()
+  const hslFuncMatch = trimmed.match(/hsla?\s*\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/);
+  if (hslFuncMatch) {
+    const h = parseFloat(hslFuncMatch[1]);
+    const s = parseFloat(hslFuncMatch[2]);
+    const l = parseFloat(hslFuncMatch[3]);
+    return hslToRgb(h, s, l);
+  }
+  
+  // Handle space-separated HSL (common in Tailwind/shadcn): "195 100% 41%"
+  const hslSpaceMatch = trimmed.match(/^([\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%$/);
+  if (hslSpaceMatch) {
+    const h = parseFloat(hslSpaceMatch[1]);
+    const s = parseFloat(hslSpaceMatch[2]);
+    const l = parseFloat(hslSpaceMatch[3]);
+    return hslToRgb(h, s, l);
+  }
+  
+  // Handle oklch() - approximate conversion (not perfect but gives reasonable results)
+  const oklchMatch = trimmed.match(/oklch\s*\(\s*([\d.]+)(?:%?)\s+([\d.]+)\s+([\d.]+)/);
+  if (oklchMatch) {
+    // Simplified oklch to RGB approximation
+    // L is lightness (0-1 or 0-100%), C is chroma, H is hue
+    let l = parseFloat(oklchMatch[1]);
+    if (l > 1) l = l / 100; // Handle percentage format
+    const c = parseFloat(oklchMatch[2]);
+    const h = parseFloat(oklchMatch[3]);
+    
+    // Very rough approximation: treat as HSL with adjusted values
+    // This won't be perfect but gives a reasonable estimate for contrast
+    const approxS = Math.min(100, c * 300); // Chroma to saturation approximation
+    const approxL = l * 100;
+    return hslToRgb(h, approxS, approxL);
+  }
+  
+  // Handle named colors (common ones)
+  const namedColors: Record<string, RGB> = {
+    white: { r: 255, g: 255, b: 255 },
+    black: { r: 0, g: 0, b: 0 },
+    transparent: { r: 0, g: 0, b: 0 }, // Treat as black for contrast purposes
+    red: { r: 255, g: 0, b: 0 },
+    green: { r: 0, g: 128, b: 0 },
+    blue: { r: 0, g: 0, b: 255 },
+    yellow: { r: 255, g: 255, b: 0 },
+    cyan: { r: 0, g: 255, b: 255 },
+    magenta: { r: 255, g: 0, b: 255 },
+    gray: { r: 128, g: 128, b: 128 },
+    grey: { r: 128, g: 128, b: 128 },
+  };
+  
+  if (namedColors[trimmed]) {
+    return namedColors[trimmed];
+  }
+  
+  return null;
+}
+
+// ============================================================================
+// WCAG CONTRAST CALCULATION
+// ============================================================================
+
+/**
+ * Calculate relative luminance using WCAG formula
+ * https://www.w3.org/TR/WCAG21/#dfn-relative-luminance
+ */
+function getLuminance(r: number, g: number, b: number): number {
+  const [rs, gs, bs] = [r, g, b].map((c) => {
+    c /= 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
+}
+
+/**
+ * Calculate WCAG contrast ratio between two colors
+ * Returns ratio like 4.5, 7.0, 21.0 (max), etc.
+ * WCAG AA requires 4.5:1 for normal text, 3:1 for large text
+ * WCAG AAA requires 7:1 for normal text, 4.5:1 for large text
+ */
+function getContrastRatio(rgb1: RGB, rgb2: RGB): number {
+  const l1 = getLuminance(rgb1.r, rgb1.g, rgb1.b);
+  const l2 = getLuminance(rgb2.r, rgb2.g, rgb2.b);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Determine which alternative (white or black) provides better contrast
+ */
+function getBestAlternative(bgRgb: RGB): { color: string; ratio: number } {
+  const whiteRgb: RGB = { r: 255, g: 255, b: 255 };
+  const blackRgb: RGB = { r: 0, g: 0, b: 0 };
+  
+  const whiteRatio = getContrastRatio(bgRgb, whiteRgb);
+  const blackRatio = getContrastRatio(bgRgb, blackRgb);
+  
+  if (whiteRatio >= blackRatio) {
+    return { color: "text-white", ratio: whiteRatio };
+  } else {
+    return { color: "text-black", ratio: blackRatio };
+  }
+}
+
+// ============================================================================
+// THEME FILE DISCOVERY
+// ============================================================================
+
+/**
+ * Patterns for finding theme-related files
+ */
+const THEME_FILE_PATTERNS = [
+  // CSS files
+  "src/app/globals.css",
+  "app/globals.css",
+  "src/styles/globals.css",
+  "styles/globals.css",
+  "src/styles/global.css",
+  "styles/global.css",
+  "src/styles/variables.css",
+  "styles/variables.css",
+  "src/styles/theme.css",
+  "styles/theme.css",
+  "src/styles/brand-overrides.css",
+  "styles/brand-overrides.css",
+  // Tailwind config files
+  "tailwind.config.js",
+  "tailwind.config.ts",
+  "tailwind.config.mjs",
+  "tailwind.config.cjs",
+];
+
+/**
+ * Find all theme-related files in a project
+ */
+export function findThemeFiles(projectRoot: string): string[] {
+  const foundFiles: string[] = [];
+  
+  for (const pattern of THEME_FILE_PATTERNS) {
+    const fullPath = path.join(projectRoot, pattern);
+    if (fs.existsSync(fullPath)) {
+      foundFiles.push(pattern);
+    }
+  }
+  
+  // Also search for any additional CSS files in common locations
+  const additionalDirs = ["src/styles", "styles", "src/app", "app"];
+  for (const dir of additionalDirs) {
+    const dirPath = path.join(projectRoot, dir);
+    if (fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()) {
+      try {
+        const files = fs.readdirSync(dirPath);
+        for (const file of files) {
+          if (file.endsWith(".css") && !foundFiles.includes(path.join(dir, file))) {
+            foundFiles.push(path.join(dir, file));
+          }
+        }
+      } catch {
+        // Ignore read errors
+      }
+    }
+  }
+  
+  return foundFiles;
+}
+
+/**
+ * Parse CSS content and extract variable definitions
+ * Extracts patterns like: --primary: #333F48; or --accent: hsl(180 100% 50%);
+ */
+export function parseCSSVariables(cssContent: string): Record<string, string> {
+  const variables: Record<string, string> = {};
+  
+  // Match CSS custom property definitions
+  // Handles: --name: value; with various value formats
+  const regex = /--([a-zA-Z0-9-]+)\s*:\s*([^;]+);/g;
+  
+  let match;
+  while ((match = regex.exec(cssContent)) !== null) {
+    const name = match[1].trim();
+    const value = match[2].trim();
+    variables[`--${name}`] = value;
+  }
+  
+  return variables;
+}
+
+/**
+ * Parse Tailwind config file and extract custom color definitions
+ * Handles both JS and TS config formats
+ */
+export function parseTailwindConfig(configPath: string, projectRoot: string): Record<string, string> {
+  const colors: Record<string, string> = {};
+  
+  const fullPath = path.join(projectRoot, configPath);
+  if (!fs.existsSync(fullPath)) {
+    return colors;
+  }
+  
+  try {
+    const content = fs.readFileSync(fullPath, "utf-8");
+    
+    // Extract color definitions from the config
+    // This is a simplified parser that handles common patterns
+    
+    // Pattern 1: colors: { name: "value" } or colors: { name: { DEFAULT: "value" } }
+    const colorBlockMatch = content.match(/colors\s*:\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}/s);
+    if (colorBlockMatch) {
+      const colorBlock = colorBlockMatch[1];
+      
+      // Simple key-value pairs: name: "value" or name: 'value'
+      const simpleColorRegex = /(\w+[-\w]*)\s*:\s*["']([^"']+)["']/g;
+      let match;
+      while ((match = simpleColorRegex.exec(colorBlock)) !== null) {
+        colors[match[1]] = match[2];
+      }
+      
+      // Nested objects with DEFAULT: name: { DEFAULT: "value" }
+      const nestedColorRegex = /(\w+[-\w]*)\s*:\s*\{\s*DEFAULT\s*:\s*["']([^"']+)["']/g;
+      while ((match = nestedColorRegex.exec(colorBlock)) !== null) {
+        colors[match[1]] = match[2];
+      }
+    }
+    
+    // Pattern 2: extend: { colors: { ... } }
+    const extendColorMatch = content.match(/extend\s*:\s*\{[^}]*colors\s*:\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}/s);
+    if (extendColorMatch) {
+      const extendBlock = extendColorMatch[1];
+      
+      const simpleColorRegex = /(\w+[-\w]*)\s*:\s*["']([^"']+)["']/g;
+      let match;
+      while ((match = simpleColorRegex.exec(extendBlock)) !== null) {
+        colors[match[1]] = match[2];
+      }
+      
+      // CSS variable references: name: "var(--name)" or "hsl(var(--name))"
+      const varRefRegex = /(\w+[-\w]*)\s*:\s*["'](?:hsl\()?var\(--([^)]+)\)(?:\))?["']/g;
+      while ((match = varRefRegex.exec(extendBlock)) !== null) {
+        colors[match[1]] = `var(--${match[2]})`;
+      }
+    }
+    
+  } catch (error) {
+    // Silently fail - config parsing is best-effort
+    console.warn(`[Theme Discovery] Failed to parse Tailwind config: ${error}`);
+  }
+  
+  return colors;
+}
+
+/**
+ * Extract available semantic tokens from CSS content
+ * Finds class-like patterns that suggest available Tailwind/utility classes
+ */
+export function extractAvailableTokens(cssVariables: Record<string, string>): string[] {
+  const tokens: string[] = [];
+  
+  // Generate bg-* and text-* tokens from CSS variable names
+  for (const varName of Object.keys(cssVariables)) {
+    // Remove -- prefix
+    const name = varName.replace(/^--/, "");
+    
+    // Skip numeric or utility variables
+    if (/^\d/.test(name) || name.includes("radius") || name.includes("shadow")) {
+      continue;
+    }
+    
+    // Common color-related variable patterns
+    if (
+      name.includes("background") ||
+      name.includes("foreground") ||
+      name.includes("primary") ||
+      name.includes("secondary") ||
+      name.includes("accent") ||
+      name.includes("muted") ||
+      name.includes("destructive") ||
+      name.includes("success") ||
+      name.includes("warning") ||
+      name.includes("border") ||
+      name.includes("ring") ||
+      name.includes("card") ||
+      name.includes("popover")
+    ) {
+      // Add as potential class token
+      tokens.push(name);
+    }
+  }
+  
+  // Always include common utility tokens
+  const commonTokens = [
+    "text-white",
+    "text-black",
+    "bg-white",
+    "bg-black",
+    "bg-transparent",
+  ];
+  
+  return [...new Set([...tokens, ...commonTokens])];
+}
+
+// ============================================================================
+// CONTRAST ANALYSIS
+// ============================================================================
+
+/**
+ * Analyze CSS variables to identify contrast relationships
+ * Calculates actual WCAG contrast ratios and returns warnings for failing combinations
+ */
+export function analyzeContrastRelationships(
+  cssVariables: Record<string, string>
+): ContrastAnalysis {
+  const warnings: ContrastWarning[] = [];
+  const safePatterns: SafePattern[] = [];
+  
+  // Track which backgrounds we've analyzed to add white/black alternatives
+  const analyzedBackgrounds: { name: string; rgb: RGB }[] = [];
+  
+  // Find all bg/foreground pairs automatically
+  for (const [varName, value] of Object.entries(cssVariables)) {
+    // Skip if this is a foreground variable
+    if (varName.includes("foreground")) continue;
+    
+    // Skip non-color variables
+    if (
+      varName.includes("radius") ||
+      varName.includes("shadow") ||
+      varName.includes("ring") ||
+      varName.includes("border") && !varName.match(/border$/)
+    ) {
+      continue;
+    }
+    
+    const baseName = varName.replace(/^--/, "");
+    const foregroundVar = `--${baseName}-foreground`;
+    
+    // Parse background color
+    const bgRgb = parseColorToRgb(value);
+    if (!bgRgb) continue;
+    
+    // Track this background for alternative suggestions
+    analyzedBackgrounds.push({ name: baseName, rgb: bgRgb });
+    
+    // Check if there's a corresponding foreground variable
+    if (cssVariables[foregroundVar]) {
+      const fgRgb = parseColorToRgb(cssVariables[foregroundVar]);
+      
+      if (fgRgb) {
+        const ratio = getContrastRatio(bgRgb, fgRgb);
+        const passes = ratio >= 4.5; // WCAG AA for normal text
+        
+        if (!passes) {
+          // Find the best alternative
+          const alternative = getBestAlternative(bgRgb);
+          
+          warnings.push({
+            background: `bg-${baseName}`,
+            text: `text-${baseName}-foreground`,
+            ratio: ratio.toFixed(1),
+            suggestion: `Use ${alternative.color} instead (${alternative.ratio.toFixed(1)}:1 contrast)`,
+          });
+        } else {
+          safePatterns.push({
+            background: `bg-${baseName}`,
+            text: `text-${baseName}-foreground`,
+            ratio: ratio.toFixed(1),
+          });
+        }
+      }
+    }
+  }
+  
+  // Add white/black alternatives for all analyzed backgrounds
+  const whiteRgb: RGB = { r: 255, g: 255, b: 255 };
+  const blackRgb: RGB = { r: 0, g: 0, b: 0 };
+  
+  for (const { name, rgb } of analyzedBackgrounds) {
+    // Only add alternatives for semantic color names (primary, accent, etc.)
+    if (
+      name.includes("primary") ||
+      name.includes("secondary") ||
+      name.includes("accent") ||
+      name.includes("destructive") ||
+      name.includes("success") ||
+      name.includes("warning") ||
+      name.includes("muted")
+    ) {
+      const whiteRatio = getContrastRatio(rgb, whiteRgb);
+      const blackRatio = getContrastRatio(rgb, blackRgb);
+      
+      if (whiteRatio >= 4.5) {
+        safePatterns.push({
+          background: `bg-${name}`,
+          text: "text-white",
+          ratio: whiteRatio.toFixed(1),
+        });
+      }
+      
+      if (blackRatio >= 4.5) {
+        safePatterns.push({
+          background: `bg-${name}`,
+          text: "text-black",
+          ratio: blackRatio.toFixed(1),
+        });
+      }
+    }
+  }
+  
+  return { warnings, safePatterns };
+}
+
+// ============================================================================
+// MAIN ENTRY POINTS
+// ============================================================================
+
+/**
+ * Main entry point: Discover theme from a project
+ */
+export async function discoverTheme(projectRoot: string): Promise<DiscoveredTheme> {
+  const result: DiscoveredTheme = {
+    cssVariables: {},
+    tailwindColors: {},
+    availableTokens: [],
+    rawThemeCSS: "",
+    discoveredFiles: [],
+  };
+  
+  // Find theme files
+  const themeFiles = findThemeFiles(projectRoot);
+  result.discoveredFiles = themeFiles;
+  
+  // Parse each file
+  for (const file of themeFiles) {
+    const fullPath = path.join(projectRoot, file);
+    
+    try {
+      if (file.endsWith(".css")) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        
+        // Accumulate raw CSS
+        result.rawThemeCSS += `\n/* === ${file} === */\n${content}\n`;
+        
+        // Parse variables
+        const variables = parseCSSVariables(content);
+        Object.assign(result.cssVariables, variables);
+        
+      } else if (file.includes("tailwind.config")) {
+        // Parse Tailwind config
+        const colors = parseTailwindConfig(file, projectRoot);
+        Object.assign(result.tailwindColors, colors);
+      }
+    } catch (error) {
+      console.warn(`[Theme Discovery] Error reading ${file}:`, error);
+    }
+  }
+  
+  // Extract available tokens
+  result.availableTokens = extractAvailableTokens(result.cssVariables);
+  
+  // Run contrast analysis
+  result.contrastAnalysis = analyzeContrastRelationships(result.cssVariables);
+  
+  return result;
+}
+
+/**
+ * Format discovered theme as context for the LLM prompt
+ * Includes contrast warnings to prevent bad color combinations
+ */
+export function formatThemeForPrompt(theme: DiscoveredTheme): string {
+  const lines: string[] = [];
+  
+  lines.push("**TARGET CODEBASE THEME (discovered):**");
+  lines.push("");
+  
+  // CSS Variables
+  if (Object.keys(theme.cssVariables).length > 0) {
+    lines.push("CSS Variables:");
+    
+    // Group by category
+    const categories: Record<string, string[]> = {
+      colors: [],
+      other: [],
+    };
+    
+    for (const [name, value] of Object.entries(theme.cssVariables)) {
+      const entry = `  ${name}: ${value}`;
+      if (
+        name.includes("background") ||
+        name.includes("foreground") ||
+        name.includes("primary") ||
+        name.includes("secondary") ||
+        name.includes("accent") ||
+        name.includes("muted") ||
+        name.includes("destructive") ||
+        name.includes("success") ||
+        name.includes("warning") ||
+        name.includes("border") ||
+        name.includes("card")
+      ) {
+        categories.colors.push(entry);
+      } else {
+        categories.other.push(entry);
+      }
+    }
+    
+    // Only include color-related variables (most relevant for styling)
+    lines.push(...categories.colors.slice(0, 30)); // Limit to avoid prompt bloat
+    
+    if (categories.colors.length > 30) {
+      lines.push(`  ... and ${categories.colors.length - 30} more color variables`);
+    }
+    lines.push("");
+  }
+  
+  // Tailwind Colors
+  if (Object.keys(theme.tailwindColors).length > 0) {
+    lines.push("Tailwind Custom Colors:");
+    for (const [name, value] of Object.entries(theme.tailwindColors)) {
+      lines.push(`  ${name}: ${value}`);
+    }
+    lines.push("");
+  }
+  
+  // ========== CONTRAST ANALYSIS (NEW) ==========
+  // Run contrast analysis if not already done
+  const contrastAnalysis = theme.contrastAnalysis || analyzeContrastRelationships(theme.cssVariables);
+  
+  // Show warnings first (most important for LLM)
+  if (contrastAnalysis.warnings.length > 0) {
+    lines.push("");
+    lines.push("⚠️ CONTRAST WARNINGS (these combinations FAIL WCAG in this codebase - DO NOT USE):");
+    for (const w of contrastAnalysis.warnings) {
+      lines.push(`  ❌ ${w.background} + ${w.text}: ${w.ratio}:1 → ${w.suggestion}`);
+    }
+  }
+  
+  // Show safe patterns
+  if (contrastAnalysis.safePatterns.length > 0) {
+    lines.push("");
+    lines.push("✓ SAFE COLOR COMBINATIONS (use these instead):");
+    
+    // Deduplicate and sort by background, prioritize semantic foregrounds
+    const seen = new Set<string>();
+    const sorted = contrastAnalysis.safePatterns
+      .filter((p) => {
+        const key = `${p.background}+${p.text}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      })
+      .sort((a, b) => {
+        // Sort by background name, then prioritize -foreground over white/black
+        if (a.background !== b.background) {
+          return a.background.localeCompare(b.background);
+        }
+        // Prioritize -foreground variants
+        const aIsForeground = a.text.includes("-foreground");
+        const bIsForeground = b.text.includes("-foreground");
+        if (aIsForeground && !bIsForeground) return -1;
+        if (!aIsForeground && bIsForeground) return 1;
+        return 0;
+      });
+    
+    for (const s of sorted.slice(0, 15)) { // Limit to avoid prompt bloat
+      lines.push(`  ✓ ${s.background} + ${s.text}: ${s.ratio}:1`);
+    }
+    
+    if (sorted.length > 15) {
+      lines.push(`  ... and ${sorted.length - 15} more safe combinations`);
+    }
+  }
+  
+  lines.push("");
+  
+  // Available Tokens
+  if (theme.availableTokens.length > 0) {
+    lines.push(`Available Semantic Tokens: ${theme.availableTokens.slice(0, 20).join(", ")}`);
+    if (theme.availableTokens.length > 20) {
+      lines.push(`  ... and ${theme.availableTokens.length - 20} more`);
+    }
+    lines.push("");
+  }
+  
+  // Discovered Files
+  if (theme.discoveredFiles.length > 0) {
+    lines.push(`Theme Files Found: ${theme.discoveredFiles.join(", ")}`);
+  }
+  
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonance-brand-mcp",
-  "version": "1.3.51",
+  "version": "1.3.55",
   "description": "MCP Server for Sonance Brand Guidelines and Component Library - gives Claude instant access to brand colors, typography, and UI components.",
   "main": "dist/index.js",
   "type": "module",