sonance-brand-mcp 1.3.53 → 1.3.55

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

@@ -4,11 +4,53 @@
  * 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
  */
@@ -27,8 +69,208 @@ export interface DiscoveredTheme {
   
   // 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
  */
@@ -221,49 +463,120 @@ export function extractAvailableTokens(cssVariables: Record<string, string>): st
   return [...new Set([...tokens, ...commonTokens])];
 }
 
+// ============================================================================
+// CONTRAST ANALYSIS
+// ============================================================================
+
 /**
  * Analyze CSS variables to identify contrast relationships
- * Returns warnings about potentially problematic color combinations
+ * Calculates actual WCAG contrast ratios and returns warnings for failing combinations
  */
 export function analyzeContrastRelationships(
   cssVariables: Record<string, string>
-): { warnings: string[]; goodPairs: { bg: string; text: string }[] } {
-  const warnings: string[] = [];
-  const goodPairs: { bg: string; text: string }[] = [];
+): ContrastAnalysis {
+  const warnings: ContrastWarning[] = [];
+  const safePatterns: SafePattern[] = [];
   
-  // Common pattern: --{name} is background, --{name}-foreground is text
-  // Check if foreground values look like they might have contrast issues
+  // 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 bgValue = value;
-      const fgValue = cssVariables[foregroundVar];
+      const fgRgb = parseColorToRgb(cssVariables[foregroundVar]);
       
-      // Simple heuristic: if both values reference same color or are similar
-      // This is a basic check - real contrast would need color parsing
-      if (bgValue === fgValue) {
-        warnings.push(
-          `WARNING: ${varName} and ${foregroundVar} have identical values - text will be invisible`
-        );
+      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);
       
-      // Add as a known pair (user should verify contrast)
-      goodPairs.push({
-        bg: `bg-${baseName}`,
-        text: `text-${baseName}-foreground`,
-      });
+      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, goodPairs };
+  return { warnings, safePatterns };
 }
 
+// ============================================================================
+// MAIN ENTRY POINTS
+// ============================================================================
+
 /**
  * Main entry point: Discover theme from a project
  */
@@ -308,11 +621,15 @@ export async function discoverTheme(projectRoot: string): Promise<DiscoveredThem
   // 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[] = [];
@@ -369,6 +686,57 @@ export function formatThemeForPrompt(theme: DiscoveredTheme): string {
     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(", ")}`);
@@ -385,4 +753,3 @@ export function formatThemeForPrompt(theme: DiscoveredTheme): string {
   
   return lines.join("\n");
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonance-brand-mcp",
-  "version": "1.3.53",
+  "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",