sonance-brand-mcp 1.3.98 → 1.3.100

package/dist/assets/api/sonance-vision-apply/route.ts

@@ -88,6 +88,40 @@ interface BackupManifest {
 const BACKUP_ROOT = ".sonance-backups";
 const DEBUG_LOG_FILE = "sonance-debug.log";
 
+/**
+ * TWO-PHASE DESIGN ANALYSIS TYPES
+ * Phase 1 identifies problems, Phase 2 generates patches that reference those problems
+ */
+
+/** Categories of visual/UX problems that can be identified */
+type DesignProblemCategory = 'hierarchy' | 'spacing' | 'alignment' | 'feedback' | 'grouping';
+
+/** A specific visual problem identified in Phase 1 analysis */
+interface DesignProblem {
+  /** Unique identifier (e.g., "hierarchy-1", "spacing-2") */
+  id: string;
+  /** Problem category */
+  category: DesignProblemCategory;
+  /** Specific description of the issue */
+  description: string;
+  /** Visual impact severity */
+  severity: 'high' | 'medium' | 'low';
+  /** Hint for what to look for in the code */
+  codeHint?: string;
+}
+
+/** Extended patch that references a specific problem from Phase 1 */
+interface DesignPatch {
+  /** Reference to the problem this patch fixes */
+  problemId: string;
+  /** Exact code to find */
+  search: string;
+  /** Replacement code */
+  replace: string;
+  /** Explanation of how this fixes the problem */
+  rationale: string;
+}
+
 /**
  * Debug logging utility - writes to sonance-debug.log in project root
  * This helps diagnose issues with file discovery, validation, and revert
@@ -889,6 +923,139 @@ Be smart - use your knowledge of React patterns to identify what type of element
   }
 }
 
+/**
+ * PHASE 1: Design Problem Analysis
+ * 
+ * Analyzes the screenshot to identify specific visual/UX problems.
+ * This is a SEPARATE LLM call that ONLY identifies problems - no code changes.
+ * The problems are then passed to Phase 2 to generate targeted patches.
+ */
+async function analyzeDesignProblems(
+  screenshot: string,
+  fileContent: string,
+  userPrompt: string,
+  apiKey: string
+): Promise<DesignProblem[]> {
+  const anthropic = new Anthropic({ apiKey });
+  const base64Data = screenshot.split(",")[1] || screenshot;
+
+  debugLog("Phase 1 Design Analysis: Starting visual problem identification", {
+    promptPreview: userPrompt?.substring(0, 50),
+    fileContentLength: fileContent.length
+  });
+
+  try {
+    const response = await anthropic.messages.create({
+      model: "claude-sonnet-4-20250514",
+      max_tokens: 2048,
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "image",
+              source: {
+                type: "base64",
+                media_type: "image/png",
+                data: base64Data,
+              },
+            },
+            {
+              type: "text",
+              text: `You are a senior UI/UX designer. Analyze this screenshot and identify SPECIFIC visual problems.
+
+User's request: "${userPrompt}"
+
+Examine the UI for issues in these categories:
+
+1. HIERARCHY: Is there a clear visual focus? Are elements competing for attention?
+   - Look for: competing headings, unclear primary actions, visual clutter
+
+2. SPACING: Are related elements grouped? Is there awkward empty space?
+   - Look for: disconnected labels/values, uneven gaps, cramped or overly spread content
+
+3. ALIGNMENT: Do elements align naturally? Are there visual disconnects?
+   - Look for: misaligned text, floating elements, broken visual flow
+
+4. FEEDBACK: Are progress indicators, states, and actions clear?
+   - Look for: weak progress visualization, unclear states, orphaned status indicators
+
+5. GROUPING: Are related items visually connected? Do containers make sense?
+   - Look for: related content that appears separate, missing visual boundaries
+
+For each problem found, provide:
+- id: unique identifier (e.g., "hierarchy-1", "spacing-2")
+- category: one of [hierarchy, spacing, alignment, feedback, grouping]
+- description: specific description of what's wrong
+- severity: high/medium/low based on visual impact
+- codeHint: what to look for in the code to fix it
+
+Return ONLY a JSON array of problems. Example:
+[
+  {
+    "id": "grouping-1",
+    "category": "grouping",
+    "description": "The 'Essence Quality' label and '0% COMPLETE' badge appear visually disconnected - they should be grouped together",
+    "severity": "high",
+    "codeHint": "Check if label and badge are in separate containers or using absolute positioning"
+  },
+  {
+    "id": "spacing-1",
+    "category": "spacing",
+    "description": "Too much vertical gap between the header section and the quality indicator",
+    "severity": "medium",
+    "codeHint": "Look for large margin or padding values like mt-6, mb-8, py-6"
+  }
+]
+
+IMPORTANT:
+- Only identify problems that are actually visible in the screenshot
+- Be specific - vague problems lead to vague fixes
+- Maximum 5 problems - focus on the most impactful ones
+- If no significant problems are found, return an empty array []
+- Do NOT suggest code changes - only identify problems
+
+Return ONLY the JSON array, no other text.`,
+            },
+          ],
+        },
+      ],
+    });
+
+    const textBlock = response.content.find((block) => block.type === "text");
+    if (!textBlock || textBlock.type !== "text") {
+      debugLog("Phase 1 Design Analysis: No text response from LLM");
+      return [];
+    }
+
+    let jsonText = textBlock.text.trim();
+    
+    // Extract JSON from code fences if present
+    const jsonMatch = jsonText.match(/```(?:json)?\n?([\s\S]*?)\n?```/) ||
+                     jsonText.match(/\[[\s\S]*\]/);
+    if (jsonMatch) {
+      jsonText = jsonMatch[1] || jsonMatch[0];
+    }
+
+    const problems: DesignProblem[] = JSON.parse(jsonText);
+    
+    // Validate the structure
+    const validatedProblems = problems.filter(p => 
+      p.id && p.category && p.description && p.severity
+    ).slice(0, 5); // Maximum 5 problems
+
+    debugLog("Phase 1 Design Analysis: Identified problems", {
+      count: validatedProblems.length,
+      problems: validatedProblems.map(p => ({ id: p.id, category: p.category, severity: p.severity }))
+    });
+
+    return validatedProblems;
+  } catch (e) {
+    debugLog("Phase 1 Design Analysis: Failed to analyze", { error: String(e) });
+    return [];
+  }
+}
+
 /**
  * Search candidate files for JSX code matching the focused element
  * This helps identify which file actually contains the element the user clicked on
@@ -1342,65 +1509,166 @@ Output format:
 The "search" field must match the file EXACTLY (copy-paste from the code provided).`;
 
 /**
- * DESIGN REASONING PROMPT
- * Forces the LLM through a structured analysis before making design changes.
- * This prevents over-engineering and ensures thoughtful, targeted modifications.
+ * PHASE 2: Targeted Patch Generation Prompt
+ * 
+ * This prompt is used AFTER Phase 1 has identified specific problems.
+ * It requires each patch to reference a problem ID from Phase 1.
  */
-const DESIGN_REASONING_PROMPT = `
+function buildPhase2DesignPrompt(problems: DesignProblem[]): string {
+  if (problems.length === 0) {
+    return ''; // No problems identified, skip design protocol
+  }
+
+  const problemsJson = JSON.stringify(problems, null, 2);
+  
+  return `
 ═══════════════════════════════════════════════════════════════════════════════
-DESIGN REASONING PROTOCOL (Follow BEFORE generating patches)
+PHASE 2: TARGETED PATCH GENERATION
 ═══════════════════════════════════════════════════════════════════════════════
 
-STEP 1 - VISUAL ANALYSIS:
-Before making any changes, analyze the current UI in the screenshot:
-• What type of component is this? (form wizard, modal, card, data table, sidebar, etc.)
-• What is currently working well that should be PRESERVED?
-• What specific visual issues exist? (inconsistent spacing, unclear hierarchy, alignment problems, clutter)
-
-STEP 2 - MINIMAL CHANGE PLAN:
-Identify the MINIMUM changes needed to address the user's request:
-• What 1-3 targeted fixes would solve the issue?
-• What should you explicitly NOT change?
-• Will these changes break existing functionality or visual balance?
-
-STEP 3 - GUARDRAILS CHECK:
-Before implementing, verify you are following these rules:
-• Am I preserving the existing layout structure? (flex stays flex, grid stays grid)
-• Am I keeping the existing color palette unless specifically asked to change it?
-• Am I making incremental improvements, NOT a complete restructure?
-• Am I keeping the same visual hierarchy and element positions?
-
-STEP 4 - IMPLEMENT:
-Only now generate patches for the targeted changes from Step 2.
-Each patch should be small and focused - prefer multiple small patches over one large rewrite.
+A visual analysis identified these specific problems in the UI:
+
+${problemsJson}
+
+YOUR TASK: Generate patches that fix ONLY these specific problems.
+
+STRICT RULES:
+1. Each patch MUST include a "problemId" field referencing one of the problems above
+2. Do NOT make changes unrelated to the identified problems
+3. Make the SMALLEST change that fixes each problem
+4. Do NOT change layout systems (flex→grid) unless absolutely necessary to fix a problem
+5. Preserve existing structure - adjust properties, don't restructure
+
+For each problem, find the exact code that causes it and create a targeted fix.
+
+OUTPUT FORMAT (note the problemId and rationale fields):
+{
+  "modifications": [{
+    "filePath": "components/Example.tsx",
+    "patches": [
+      {
+        "problemId": "grouping-1",
+        "search": "<Badge className=\"absolute right-4\">",
+        "replace": "<Badge className=\"ml-2\">",
+        "rationale": "Removes absolute positioning to group badge with label"
+      },
+      {
+        "problemId": "spacing-1",
+        "search": "className=\"mt-8\"",
+        "replace": "className=\"mt-4\"",
+        "rationale": "Reduces excessive vertical gap"
+      }
+    ]
+  }]
+}
+
+VALIDATION:
+- Patches without a valid problemId will be REJECTED
+- Patches that don't trace to an identified problem will be REJECTED
+- Each patch must have search, replace, problemId, and rationale fields
 `;
+}
 
 /**
- * DESIGN GUARDRAILS
- * Explicit constraints to prevent the LLM from over-engineering design changes.
+ * DESIGN DECISION RULES for Phase 2
  */
 const DESIGN_GUARDRAILS = `
 ═══════════════════════════════════════════════════════════════════════════════
-DESIGN GUARDRAILS (MUST FOLLOW)
+DESIGN CONSTRAINTS
 ═══════════════════════════════════════════════════════════════════════════════
 
-❌ DO NOT:
-• Convert layout systems (do NOT change flex to grid or vice versa)
-• Restructure component hierarchy unless explicitly asked
-• Change color schemes unless specifically requested
-• Move elements to different positions unless asked
-• Rewrite entire sections - make targeted changes only
-• Add new wrapper elements or change semantic structure
-
-✓ DO:
-• Focus on spacing, padding, and margins for "cleaner" requests
-• Improve typography (font size, weight, line-height) for readability
-• Fix alignment issues within the existing structure
-• Adjust visual hierarchy through subtle styling, not restructuring
-• Make the smallest change that addresses the user's request
-• Preserve what is already working well
+✓ ALLOWED when fixing identified problems:
+• Adjust spacing (margin, padding) - e.g., mt-4 → mt-2
+• Adjust alignment within containers - e.g., items-start → items-center
+• Move elements within the same container to improve grouping
+• Adjust typography - font size, weight, line-height
+• Add/remove whitespace classes
+
+✗ FORBIDDEN (will cause rejection):
+• Changing layout system (flex → grid, grid → flex)
+• Restructuring component hierarchy
+• Wrapping elements in new containers (unless specifically needed for a grouping problem)
+• Removing or changing functionality
+• Changes without a problemId reference
+
+═══════════════════════════════════════════════════════════════════════════════
 `;
 
+/**
+ * Validate patches against identified problems
+ * Rejects patches that don't reference a valid problem ID
+ */
+function validateDesignPatches(
+  patches: Array<{ search: string; replace: string; problemId?: string; rationale?: string }>,
+  problems: DesignProblem[]
+): { valid: Array<{ search: string; replace: string; problemId: string; rationale: string }>; rejected: Array<{ patch: unknown; reason: string }> } {
+  const validProblemIds = new Set(problems.map(p => p.id));
+  const valid: Array<{ search: string; replace: string; problemId: string; rationale: string }> = [];
+  const rejected: Array<{ patch: unknown; reason: string }> = [];
+
+  for (const patch of patches) {
+    // Check for required fields
+    if (!patch.search || !patch.replace) {
+      rejected.push({ patch, reason: "Missing search or replace field" });
+      continue;
+    }
+
+    // For design-heavy requests, require problemId
+    if (!patch.problemId) {
+      rejected.push({ patch, reason: "Missing problemId - patch doesn't reference an identified problem" });
+      continue;
+    }
+
+    // Validate problemId exists in the problems list
+    if (!validProblemIds.has(patch.problemId)) {
+      rejected.push({ patch, reason: `Invalid problemId "${patch.problemId}" - not in identified problems list` });
+      continue;
+    }
+
+    // Check for forbidden structural changes
+    const searchLower = patch.search.toLowerCase();
+    const replaceLower = patch.replace.toLowerCase();
+    
+    // Detect flex → grid or grid → flex conversions
+    const hadFlex = searchLower.includes('flex') || searchLower.includes('items-') || searchLower.includes('justify-');
+    const hasGrid = replaceLower.includes('grid') && !searchLower.includes('grid');
+    const hadGrid = searchLower.includes('grid');
+    const hasFlex = (replaceLower.includes('flex') || replaceLower.includes('items-') || replaceLower.includes('justify-')) && !hadFlex;
+    
+    if ((hadFlex && hasGrid) || (hadGrid && hasFlex)) {
+      rejected.push({ patch, reason: "Forbidden: Changing layout system (flex ↔ grid)" });
+      continue;
+    }
+
+    // Detect space-y/space-x additions that fundamentally change layout
+    const addedSpaceY = replaceLower.includes('space-y') && !searchLower.includes('space-y');
+    const addedSpaceX = replaceLower.includes('space-x') && !searchLower.includes('space-x');
+    const hadJustifyBetween = searchLower.includes('justify-between');
+    
+    if ((addedSpaceY || addedSpaceX) && hadJustifyBetween) {
+      rejected.push({ patch, reason: "Forbidden: Converting flex layout to stack layout" });
+      continue;
+    }
+
+    valid.push({
+      search: patch.search,
+      replace: patch.replace,
+      problemId: patch.problemId,
+      rationale: patch.rationale || 'No rationale provided'
+    });
+  }
+
+  if (rejected.length > 0) {
+    debugLog("Design patch validation: Some patches rejected", {
+      validCount: valid.length,
+      rejectedCount: rejected.length,
+      rejected: rejected.map(r => ({ reason: r.reason, searchPreview: String(r.patch).substring(0, 50) }))
+    });
+  }
+
+  return { valid, rejected };
+}
+
 /**
  * Detect if a user request is design-heavy and needs the reasoning protocol.
  * Simple requests like "change button color to blue" don't need it.
@@ -1827,21 +2095,42 @@ User Request: "${userPrompt}"
 
 `;
 
-      // ========== DESIGN REASONING PROTOCOL ==========
-      // For design-heavy requests, add structured reasoning and guardrails
-      // This prevents over-engineering and ensures thoughtful changes
+      // ========== TWO-PHASE DESIGN ANALYSIS ==========
+      // Phase 1: Identify specific visual problems (separate LLM call)
+      // Phase 2: Generate patches that reference those problems
       const isDesignRequest = isDesignHeavyRequest(userPrompt || '');
+      let identifiedProblems: DesignProblem[] = [];
       
-      if (isDesignRequest) {
-        debugLog("Design-heavy request detected, adding reasoning protocol", {
+      if (isDesignRequest && screenshot) {
+        debugLog("Design-heavy request detected, running Phase 1 analysis", {
           prompt: userPrompt?.substring(0, 50),
           triggerKeywords: ['redesign', 'better', 'improve', 'cleaner', 'layout', 'modernize']
             .filter(k => userPrompt?.toLowerCase().includes(k))
         });
         
-        textContent += DESIGN_REASONING_PROMPT;
-        textContent += DESIGN_GUARDRAILS;
-        textContent += '\n';
+        // Phase 1: Analyze the screenshot to identify specific problems
+        // This is a SEPARATE LLM call that only identifies problems
+        const fileContentForAnalysis = recommendedFileContent?.content || pageContext.pageContent || '';
+        identifiedProblems = await analyzeDesignProblems(
+          screenshot,
+          fileContentForAnalysis,
+          userPrompt || '',
+          apiKey
+        );
+        
+        debugLog("Phase 1 complete: Problems identified", {
+          problemCount: identifiedProblems.length,
+          problems: identifiedProblems.map(p => `${p.id}: ${p.description.substring(0, 50)}`)
+        });
+        
+        // Add Phase 2 prompt with the identified problems
+        if (identifiedProblems.length > 0) {
+          textContent += buildPhase2DesignPrompt(identifiedProblems);
+          textContent += DESIGN_GUARDRAILS;
+          textContent += '\n';
+        } else {
+          debugLog("No problems identified - proceeding with standard edit");
+        }
       }
 
       // ========== TARGET COMPONENT ONLY (with line numbers) ==========
@@ -2366,9 +2655,41 @@ This is better than generating patches with made-up code.`,
           // New patch-based approach
           console.log(`[Apply-First] Applying ${mod.patches.length} patches to ${mod.filePath}`);
           
+          // DESIGN VALIDATION: For design-heavy requests, validate patches have problemIds
+          let patchesToApply = mod.patches;
+          if (isDesignRequest && identifiedProblems.length > 0) {
+            const validationResult = validateDesignPatches(mod.patches, identifiedProblems);
+            
+            if (validationResult.rejected.length > 0) {
+              debugLog("Design patch validation rejected some patches", {
+                filePath: mod.filePath,
+                validCount: validationResult.valid.length,
+                rejectedCount: validationResult.rejected.length,
+                rejectedReasons: validationResult.rejected.map(r => r.reason)
+              });
+              console.warn(`[Apply-First] ${validationResult.rejected.length} patches rejected for missing/invalid problemId`);
+            }
+            
+            // Only use validated patches
+            if (validationResult.valid.length === 0) {
+              patchErrors.push(`${mod.filePath}: All patches were rejected - they don't reference identified problems`);
+              continue;
+            }
+            
+            // Log which problems are being fixed
+            const problemsBeingFixed = [...new Set(validationResult.valid.map(p => p.problemId))];
+            debugLog("Design patches validated", {
+              filePath: mod.filePath,
+              problemsBeingFixed,
+              patchCount: validationResult.valid.length
+            });
+            
+            patchesToApply = validationResult.valid;
+          }
+          
           // PRE-VALIDATION: Check if all search strings exist in the file BEFORE applying
           const preValidationErrors: string[] = [];
-          for (const patch of mod.patches) {
+          for (const patch of patchesToApply) {
             const normalizedSearch = patch.search.replace(/\\n/g, "\n");
             if (!originalContent.includes(normalizedSearch)) {
               // Try fuzzy match as fallback
@@ -2407,7 +2728,7 @@ This is better than generating patches with made-up code.`,
             continue;
           }
           
-          const patchResult = applyPatches(originalContent, mod.patches);
+          const patchResult = applyPatches(originalContent, patchesToApply);
           
           if (!patchResult.success) {
             const failedMessages = patchResult.failedPatches.map(
@@ -2417,15 +2738,15 @@ This is better than generating patches with made-up code.`,
             
             // If some patches succeeded, use partial result
             if (patchResult.appliedPatches > 0) {
-              console.warn(`[Apply-First] ${patchResult.appliedPatches}/${mod.patches.length} patches applied to ${mod.filePath}`);
+              console.warn(`[Apply-First] ${patchResult.appliedPatches}/${patchesToApply.length} patches applied to ${mod.filePath}`);
               modifiedContent = patchResult.modifiedContent;
-              explanation += ` (${patchResult.appliedPatches}/${mod.patches.length} patches applied)`;
+              explanation += ` (${patchResult.appliedPatches}/${patchesToApply.length} patches applied)`;
             } else {
               continue; // Skip this file entirely if no patches worked
             }
           } else {
             modifiedContent = patchResult.modifiedContent;
-            console.log(`[Apply-First] All ${mod.patches.length} patches applied successfully to ${mod.filePath}`);
+            console.log(`[Apply-First] All ${patchesToApply.length} patches applied successfully to ${mod.filePath}`);
           }
           
           // AST VALIDATION: Use Babel parser to catch actual syntax errors

package/dist/assets/api/sonance-vision-edit/route.ts

@@ -84,6 +84,40 @@ interface VisionEditResponse {
 
 const DEBUG_LOG_FILE = "sonance-debug.log";
 
+/**
+ * TWO-PHASE DESIGN ANALYSIS TYPES
+ * Phase 1 identifies problems, Phase 2 generates patches that reference those problems
+ */
+
+/** Categories of visual/UX problems that can be identified */
+type DesignProblemCategory = 'hierarchy' | 'spacing' | 'alignment' | 'feedback' | 'grouping';
+
+/** A specific visual problem identified in Phase 1 analysis */
+interface DesignProblem {
+  /** Unique identifier (e.g., "hierarchy-1", "spacing-2") */
+  id: string;
+  /** Problem category */
+  category: DesignProblemCategory;
+  /** Specific description of the issue */
+  description: string;
+  /** Visual impact severity */
+  severity: 'high' | 'medium' | 'low';
+  /** Hint for what to look for in the code */
+  codeHint?: string;
+}
+
+/** Extended patch that references a specific problem from Phase 1 */
+interface DesignPatch {
+  /** Reference to the problem this patch fixes */
+  problemId: string;
+  /** Exact code to find */
+  search: string;
+  /** Replacement code */
+  replace: string;
+  /** Explanation of how this fixes the problem */
+  rationale: string;
+}
+
 /**
  * Debug logging utility - writes to sonance-debug.log in project root
  * This helps diagnose issues with file discovery, validation, and revert
@@ -885,6 +919,139 @@ Be smart - use your knowledge of React patterns to identify what type of element
   }
 }
 
+/**
+ * PHASE 1: Design Problem Analysis
+ * 
+ * Analyzes the screenshot to identify specific visual/UX problems.
+ * This is a SEPARATE LLM call that ONLY identifies problems - no code changes.
+ * The problems are then passed to Phase 2 to generate targeted patches.
+ */
+async function analyzeDesignProblems(
+  screenshot: string,
+  fileContent: string,
+  userPrompt: string,
+  apiKey: string
+): Promise<DesignProblem[]> {
+  const anthropic = new Anthropic({ apiKey });
+  const base64Data = screenshot.split(",")[1] || screenshot;
+
+  debugLog("Phase 1 Design Analysis: Starting visual problem identification", {
+    promptPreview: userPrompt?.substring(0, 50),
+    fileContentLength: fileContent.length
+  });
+
+  try {
+    const response = await anthropic.messages.create({
+      model: "claude-sonnet-4-20250514",
+      max_tokens: 2048,
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "image",
+              source: {
+                type: "base64",
+                media_type: "image/png",
+                data: base64Data,
+              },
+            },
+            {
+              type: "text",
+              text: `You are a senior UI/UX designer. Analyze this screenshot and identify SPECIFIC visual problems.
+
+User's request: "${userPrompt}"
+
+Examine the UI for issues in these categories:
+
+1. HIERARCHY: Is there a clear visual focus? Are elements competing for attention?
+   - Look for: competing headings, unclear primary actions, visual clutter
+
+2. SPACING: Are related elements grouped? Is there awkward empty space?
+   - Look for: disconnected labels/values, uneven gaps, cramped or overly spread content
+
+3. ALIGNMENT: Do elements align naturally? Are there visual disconnects?
+   - Look for: misaligned text, floating elements, broken visual flow
+
+4. FEEDBACK: Are progress indicators, states, and actions clear?
+   - Look for: weak progress visualization, unclear states, orphaned status indicators
+
+5. GROUPING: Are related items visually connected? Do containers make sense?
+   - Look for: related content that appears separate, missing visual boundaries
+
+For each problem found, provide:
+- id: unique identifier (e.g., "hierarchy-1", "spacing-2")
+- category: one of [hierarchy, spacing, alignment, feedback, grouping]
+- description: specific description of what's wrong
+- severity: high/medium/low based on visual impact
+- codeHint: what to look for in the code to fix it
+
+Return ONLY a JSON array of problems. Example:
+[
+  {
+    "id": "grouping-1",
+    "category": "grouping",
+    "description": "The 'Essence Quality' label and '0% COMPLETE' badge appear visually disconnected - they should be grouped together",
+    "severity": "high",
+    "codeHint": "Check if label and badge are in separate containers or using absolute positioning"
+  },
+  {
+    "id": "spacing-1",
+    "category": "spacing",
+    "description": "Too much vertical gap between the header section and the quality indicator",
+    "severity": "medium",
+    "codeHint": "Look for large margin or padding values like mt-6, mb-8, py-6"
+  }
+]
+
+IMPORTANT:
+- Only identify problems that are actually visible in the screenshot
+- Be specific - vague problems lead to vague fixes
+- Maximum 5 problems - focus on the most impactful ones
+- If no significant problems are found, return an empty array []
+- Do NOT suggest code changes - only identify problems
+
+Return ONLY the JSON array, no other text.`,
+            },
+          ],
+        },
+      ],
+    });
+
+    const textBlock = response.content.find((block) => block.type === "text");
+    if (!textBlock || textBlock.type !== "text") {
+      debugLog("Phase 1 Design Analysis: No text response from LLM");
+      return [];
+    }
+
+    let jsonText = textBlock.text.trim();
+    
+    // Extract JSON from code fences if present
+    const jsonMatch = jsonText.match(/```(?:json)?\n?([\s\S]*?)\n?```/) ||
+                     jsonText.match(/\[[\s\S]*\]/);
+    if (jsonMatch) {
+      jsonText = jsonMatch[1] || jsonMatch[0];
+    }
+
+    const problems: DesignProblem[] = JSON.parse(jsonText);
+    
+    // Validate the structure
+    const validatedProblems = problems.filter(p => 
+      p.id && p.category && p.description && p.severity
+    ).slice(0, 5); // Maximum 5 problems
+
+    debugLog("Phase 1 Design Analysis: Identified problems", {
+      count: validatedProblems.length,
+      problems: validatedProblems.map(p => ({ id: p.id, category: p.category, severity: p.severity }))
+    });
+
+    return validatedProblems;
+  } catch (e) {
+    debugLog("Phase 1 Design Analysis: Failed to analyze", { error: String(e) });
+    return [];
+  }
+}
+
 /**
  * Search candidate files for JSX code matching the focused element
  * This helps identify which file actually contains the element the user clicked on
@@ -1338,65 +1505,166 @@ Output format:
 The "search" field must match the file EXACTLY (copy-paste from the code provided).`;
 
 /**
- * DESIGN REASONING PROMPT
- * Forces the LLM through a structured analysis before making design changes.
- * This prevents over-engineering and ensures thoughtful, targeted modifications.
+ * PHASE 2: Targeted Patch Generation Prompt
+ * 
+ * This prompt is used AFTER Phase 1 has identified specific problems.
+ * It requires each patch to reference a problem ID from Phase 1.
  */
-const DESIGN_REASONING_PROMPT = `
+function buildPhase2DesignPrompt(problems: DesignProblem[]): string {
+  if (problems.length === 0) {
+    return ''; // No problems identified, skip design protocol
+  }
+
+  const problemsJson = JSON.stringify(problems, null, 2);
+  
+  return `
 ═══════════════════════════════════════════════════════════════════════════════
-DESIGN REASONING PROTOCOL (Follow BEFORE generating patches)
+PHASE 2: TARGETED PATCH GENERATION
 ═══════════════════════════════════════════════════════════════════════════════
 
-STEP 1 - VISUAL ANALYSIS:
-Before making any changes, analyze the current UI in the screenshot:
-• What type of component is this? (form wizard, modal, card, data table, sidebar, etc.)
-• What is currently working well that should be PRESERVED?
-• What specific visual issues exist? (inconsistent spacing, unclear hierarchy, alignment problems, clutter)
-
-STEP 2 - MINIMAL CHANGE PLAN:
-Identify the MINIMUM changes needed to address the user's request:
-• What 1-3 targeted fixes would solve the issue?
-• What should you explicitly NOT change?
-• Will these changes break existing functionality or visual balance?
-
-STEP 3 - GUARDRAILS CHECK:
-Before implementing, verify you are following these rules:
-• Am I preserving the existing layout structure? (flex stays flex, grid stays grid)
-• Am I keeping the existing color palette unless specifically asked to change it?
-• Am I making incremental improvements, NOT a complete restructure?
-• Am I keeping the same visual hierarchy and element positions?
-
-STEP 4 - IMPLEMENT:
-Only now generate patches for the targeted changes from Step 2.
-Each patch should be small and focused - prefer multiple small patches over one large rewrite.
+A visual analysis identified these specific problems in the UI:
+
+${problemsJson}
+
+YOUR TASK: Generate patches that fix ONLY these specific problems.
+
+STRICT RULES:
+1. Each patch MUST include a "problemId" field referencing one of the problems above
+2. Do NOT make changes unrelated to the identified problems
+3. Make the SMALLEST change that fixes each problem
+4. Do NOT change layout systems (flex→grid) unless absolutely necessary to fix a problem
+5. Preserve existing structure - adjust properties, don't restructure
+
+For each problem, find the exact code that causes it and create a targeted fix.
+
+OUTPUT FORMAT (note the problemId and rationale fields):
+{
+  "modifications": [{
+    "filePath": "components/Example.tsx",
+    "patches": [
+      {
+        "problemId": "grouping-1",
+        "search": "<Badge className=\"absolute right-4\">",
+        "replace": "<Badge className=\"ml-2\">",
+        "rationale": "Removes absolute positioning to group badge with label"
+      },
+      {
+        "problemId": "spacing-1",
+        "search": "className=\"mt-8\"",
+        "replace": "className=\"mt-4\"",
+        "rationale": "Reduces excessive vertical gap"
+      }
+    ]
+  }]
+}
+
+VALIDATION:
+- Patches without a valid problemId will be REJECTED
+- Patches that don't trace to an identified problem will be REJECTED
+- Each patch must have search, replace, problemId, and rationale fields
 `;
+}
 
 /**
- * DESIGN GUARDRAILS
- * Explicit constraints to prevent the LLM from over-engineering design changes.
+ * DESIGN DECISION RULES for Phase 2
  */
 const DESIGN_GUARDRAILS = `
 ═══════════════════════════════════════════════════════════════════════════════
-DESIGN GUARDRAILS (MUST FOLLOW)
+DESIGN CONSTRAINTS
 ═══════════════════════════════════════════════════════════════════════════════
 
-❌ DO NOT:
-• Convert layout systems (do NOT change flex to grid or vice versa)
-• Restructure component hierarchy unless explicitly asked
-• Change color schemes unless specifically requested
-• Move elements to different positions unless asked
-• Rewrite entire sections - make targeted changes only
-• Add new wrapper elements or change semantic structure
-
-✓ DO:
-• Focus on spacing, padding, and margins for "cleaner" requests
-• Improve typography (font size, weight, line-height) for readability
-• Fix alignment issues within the existing structure
-• Adjust visual hierarchy through subtle styling, not restructuring
-• Make the smallest change that addresses the user's request
-• Preserve what is already working well
+✓ ALLOWED when fixing identified problems:
+• Adjust spacing (margin, padding) - e.g., mt-4 → mt-2
+• Adjust alignment within containers - e.g., items-start → items-center
+• Move elements within the same container to improve grouping
+• Adjust typography - font size, weight, line-height
+• Add/remove whitespace classes
+
+✗ FORBIDDEN (will cause rejection):
+• Changing layout system (flex → grid, grid → flex)
+• Restructuring component hierarchy
+• Wrapping elements in new containers (unless specifically needed for a grouping problem)
+• Removing or changing functionality
+• Changes without a problemId reference
+
+═══════════════════════════════════════════════════════════════════════════════
 `;
 
+/**
+ * Validate patches against identified problems
+ * Rejects patches that don't reference a valid problem ID
+ */
+function validateDesignPatches(
+  patches: Array<{ search: string; replace: string; problemId?: string; rationale?: string }>,
+  problems: DesignProblem[]
+): { valid: Array<{ search: string; replace: string; problemId: string; rationale: string }>; rejected: Array<{ patch: unknown; reason: string }> } {
+  const validProblemIds = new Set(problems.map(p => p.id));
+  const valid: Array<{ search: string; replace: string; problemId: string; rationale: string }> = [];
+  const rejected: Array<{ patch: unknown; reason: string }> = [];
+
+  for (const patch of patches) {
+    // Check for required fields
+    if (!patch.search || !patch.replace) {
+      rejected.push({ patch, reason: "Missing search or replace field" });
+      continue;
+    }
+
+    // For design-heavy requests, require problemId
+    if (!patch.problemId) {
+      rejected.push({ patch, reason: "Missing problemId - patch doesn't reference an identified problem" });
+      continue;
+    }
+
+    // Validate problemId exists in the problems list
+    if (!validProblemIds.has(patch.problemId)) {
+      rejected.push({ patch, reason: `Invalid problemId "${patch.problemId}" - not in identified problems list` });
+      continue;
+    }
+
+    // Check for forbidden structural changes
+    const searchLower = patch.search.toLowerCase();
+    const replaceLower = patch.replace.toLowerCase();
+    
+    // Detect flex → grid or grid → flex conversions
+    const hadFlex = searchLower.includes('flex') || searchLower.includes('items-') || searchLower.includes('justify-');
+    const hasGrid = replaceLower.includes('grid') && !searchLower.includes('grid');
+    const hadGrid = searchLower.includes('grid');
+    const hasFlex = (replaceLower.includes('flex') || replaceLower.includes('items-') || replaceLower.includes('justify-')) && !hadFlex;
+    
+    if ((hadFlex && hasGrid) || (hadGrid && hasFlex)) {
+      rejected.push({ patch, reason: "Forbidden: Changing layout system (flex ↔ grid)" });
+      continue;
+    }
+
+    // Detect space-y/space-x additions that fundamentally change layout
+    const addedSpaceY = replaceLower.includes('space-y') && !searchLower.includes('space-y');
+    const addedSpaceX = replaceLower.includes('space-x') && !searchLower.includes('space-x');
+    const hadJustifyBetween = searchLower.includes('justify-between');
+    
+    if ((addedSpaceY || addedSpaceX) && hadJustifyBetween) {
+      rejected.push({ patch, reason: "Forbidden: Converting flex layout to stack layout" });
+      continue;
+    }
+
+    valid.push({
+      search: patch.search,
+      replace: patch.replace,
+      problemId: patch.problemId,
+      rationale: patch.rationale || 'No rationale provided'
+    });
+  }
+
+  if (rejected.length > 0) {
+    debugLog("Design patch validation: Some patches rejected", {
+      validCount: valid.length,
+      rejectedCount: rejected.length,
+      rejected: rejected.map(r => ({ reason: r.reason, searchPreview: String(r.patch).substring(0, 50) }))
+    });
+  }
+
+  return { valid, rejected };
+}
+
 /**
  * Detect if a user request is design-heavy and needs the reasoning protocol.
  * Simple requests like "change button color to blue" don't need it.
@@ -1796,21 +2064,42 @@ User Request: "${userPrompt}"
 
 `;
 
-      // ========== DESIGN REASONING PROTOCOL ==========
-      // For design-heavy requests, add structured reasoning and guardrails
-      // This prevents over-engineering and ensures thoughtful changes
+      // ========== TWO-PHASE DESIGN ANALYSIS ==========
+      // Phase 1: Identify specific visual problems (separate LLM call)
+      // Phase 2: Generate patches that reference those problems
       const isDesignRequest = isDesignHeavyRequest(userPrompt || '');
+      let identifiedProblems: DesignProblem[] = [];
       
-      if (isDesignRequest) {
-        debugLog("Design-heavy request detected, adding reasoning protocol", {
+      if (isDesignRequest && screenshot) {
+        debugLog("Design-heavy request detected, running Phase 1 analysis", {
           prompt: userPrompt?.substring(0, 50),
           triggerKeywords: ['redesign', 'better', 'improve', 'cleaner', 'layout', 'modernize']
             .filter(k => userPrompt?.toLowerCase().includes(k))
         });
         
-        textContent += DESIGN_REASONING_PROMPT;
-        textContent += DESIGN_GUARDRAILS;
-        textContent += '\n';
+        // Phase 1: Analyze the screenshot to identify specific problems
+        // This is a SEPARATE LLM call that only identifies problems
+        const fileContentForAnalysis = recommendedFileContent?.content || pageContext.pageContent || '';
+        identifiedProblems = await analyzeDesignProblems(
+          screenshot,
+          fileContentForAnalysis,
+          userPrompt || '',
+          apiKey
+        );
+        
+        debugLog("Phase 1 complete: Problems identified", {
+          problemCount: identifiedProblems.length,
+          problems: identifiedProblems.map(p => `${p.id}: ${p.description.substring(0, 50)}`)
+        });
+        
+        // Add Phase 2 prompt with the identified problems
+        if (identifiedProblems.length > 0) {
+          textContent += buildPhase2DesignPrompt(identifiedProblems);
+          textContent += DESIGN_GUARDRAILS;
+          textContent += '\n';
+        } else {
+          debugLog("No problems identified - proceeding with standard edit");
+        }
       }
 
       // ========== TARGET COMPONENT ONLY (with line numbers) ==========
@@ -2339,9 +2628,46 @@ This is better than generating patches with made-up code.`,
           // New patch-based approach
           console.log(`[Vision Mode] Applying ${mod.patches.length} patches to ${mod.filePath}`);
           
+          // DESIGN VALIDATION: For design-heavy requests, validate patches have problemIds
+          let patchesToApply = mod.patches;
+          if (isDesignRequest && identifiedProblems.length > 0) {
+            const validationResult = validateDesignPatches(mod.patches, identifiedProblems);
+            
+            if (validationResult.rejected.length > 0) {
+              debugLog("Design patch validation rejected some patches", {
+                filePath: mod.filePath,
+                validCount: validationResult.valid.length,
+                rejectedCount: validationResult.rejected.length,
+                rejectedReasons: validationResult.rejected.map(r => r.reason)
+              });
+              console.warn(`[Vision Mode] ${validationResult.rejected.length} patches rejected for missing/invalid problemId`);
+            }
+            
+            // Only use validated patches
+            if (validationResult.valid.length === 0) {
+              patchErrors.push(`${mod.filePath}: All patches were rejected - they don't reference identified problems`);
+              continue;
+            }
+            
+            // Log which problems are being fixed
+            const problemsBeingFixed = [...new Set(validationResult.valid.map(p => p.problemId))];
+            debugLog("Design patches validated", {
+              filePath: mod.filePath,
+              problemsBeingFixed,
+              patchCount: validationResult.valid.length
+            });
+            
+            // Map validated patches to Patch interface (rationale -> explanation)
+            patchesToApply = validationResult.valid.map(p => ({
+              search: p.search,
+              replace: p.replace,
+              explanation: `[${p.problemId}] ${p.rationale}`
+            }));
+          }
+          
           // PRE-VALIDATION: Check if all search strings exist in the file BEFORE applying
           const preValidationErrors: string[] = [];
-          for (const patch of mod.patches) {
+          for (const patch of patchesToApply) {
             const normalizedSearch = patch.search.replace(/\\n/g, "\n");
             if (!originalContent.includes(normalizedSearch)) {
               // Try fuzzy match as fallback
@@ -2380,7 +2706,7 @@ This is better than generating patches with made-up code.`,
             continue;
           }
           
-          const patchResult = applyPatches(originalContent, mod.patches);
+          const patchResult = applyPatches(originalContent, patchesToApply);
           
           if (!patchResult.success) {
             const failedMessages = patchResult.failedPatches.map(
@@ -2390,15 +2716,15 @@ This is better than generating patches with made-up code.`,
             
             // If some patches succeeded, use partial result
             if (patchResult.appliedPatches > 0) {
-              console.warn(`[Vision Mode] ${patchResult.appliedPatches}/${mod.patches.length} patches applied to ${mod.filePath}`);
+              console.warn(`[Vision Mode] ${patchResult.appliedPatches}/${patchesToApply.length} patches applied to ${mod.filePath}`);
               modifiedContent = patchResult.modifiedContent;
-              explanation += ` (${patchResult.appliedPatches}/${mod.patches.length} patches applied)`;
+              explanation += ` (${patchResult.appliedPatches}/${patchesToApply.length} patches applied)`;
             } else {
               continue; // Skip this file entirely if no patches worked
             }
           } else {
             modifiedContent = patchResult.modifiedContent;
-            console.log(`[Vision Mode] All ${mod.patches.length} patches applied successfully to ${mod.filePath}`);
+            console.log(`[Vision Mode] All ${patchesToApply.length} patches applied successfully to ${mod.filePath}`);
           }
           
           // AST VALIDATION: Use Babel parser to catch actual syntax errors

package/package.json

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