refactor(ui-design): enhance conflict detection and validation processes in import-from-code workflow

.claude/agents/ui-design-agent.md

@@ -65,8 +65,19 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes
    - Data Source: Existing source code files (CSS/SCSS/JS/TS/HTML)
    - Code Snippets: Extract complete code blocks from source files
    - MCP: ❌ NO research (extract only)
-   - Process: Read discovered-files.json → Read source files → Extract tokens with code snippets
-   - Record in: `_metadata.code_snippets` or `extraction_metadata.code_snippets` with source location, line numbers, context type
+   - Process: Read discovered-files.json → Read source files → Detect conflicts → Extract tokens with conflict resolution
+   - Record in: `_metadata.code_snippets` with source location, line numbers, context type
+   - CRITICAL Validation:
+     * Detect conflicting token definitions across multiple files
+     * Read and analyze semantic comments (/* ... */) to understand intent
+     * For core tokens (primary, secondary, accent): Verify against overall color scheme
+     * Report conflicts in `_metadata.conflicts` with all definitions and selection reasoning
+     * NO inference, NO normalization - faithful extraction with explicit conflict resolution
+   - Fast Conflict Detection (Use Bash/Grep):
+     * Quick scan: `rg --color=never -n "^\s*--primary:" <files>` to find all primary color definitions
+     * Semantic search: `rg --color=never -B2 -A0 "^\s*--primary:" <files>` to capture comments
+     * Multi-file comparison: Compare definitions across discovered CSS/JS files
+     * Pattern: Search → Compare values → If different → Read full context → Record conflict
 
 2. **Explore/Text Mode** (Source: `style-extract`, `layout-extract`, `animation-extract`)
    - Data Source: User prompts, visual references, images, URLs
@@ -299,6 +310,23 @@ body {
     "version": "string - W3C version",
     "created": "ISO timestamp",
     "source": "string - code-import|explore|text",
+    "conflicts": [
+      {
+        "token_name": "string - which token has conflicts",
+        "category": "string - colors|typography|etc",
+        "definitions": [
+          {
+            "value": "string - token value",
+            "source_file": "string - absolute path",
+            "line_number": "number",
+            "context": "string - surrounding comment or null",
+            "semantic_intent": "string - interpretation of definition"
+          }
+        ],
+        "selected_value": "string - final chosen value",
+        "selection_reason": "string - why this value was chosen"
+      }
+    ],
     "code_snippets": [
       {
         "category": "string - colors|typography|spacing|etc",
@@ -318,9 +346,18 @@ body {
 - All color values MUST use OKLCH format
 - Typography font_families MUST include Google Fonts with fallback stacks
 - Spacing MUST use systematic scale (multiples of base unit)
+- _metadata.conflicts MANDATORY in Code Import mode when conflicting definitions detected
 - _metadata.code_snippets ONLY present in Code Import mode
 - component_styles is optional but recommended
 
+**Conflict Resolution Rules** (Code Import Mode):
+- MUST detect when same token has different values across files
+- MUST read semantic comments (/* ... */) surrounding definitions
+- MUST prioritize definitions with semantic intent over bare values
+- MUST record ALL definitions in conflicts array, not just selected one
+- MUST explain selection_reason referencing semantic context
+- For core theme tokens (primary, secondary, accent): MUST verify selected value aligns with overall color scheme described in comments
+
 ### layout-templates.json
 
 **Required Top-Level Fields**:

.claude/commands/workflow/ui-design/import-from-code.md

@@ -163,10 +163,11 @@ Task(subagent_type="ui-design-agent",
   - JavaScript/TypeScript: Theme configs (Tailwind, styled-components, CSS-in-JS)
   - HTML: Inline styles, usage patterns
 
-  **Step 3: Smart inference for gaps**
-  - Infer missing tokens from existing patterns
-  - Normalize inconsistent values into systematic scales
-  - Fill missing categories from cross-file references
+  **Step 3: Validation and Conflict Detection**
+  - Report missing tokens WITHOUT inference (mark as "missing" in _metadata.completeness)
+  - Detect and report inconsistent values across files (list ALL variants with file:line sources)
+  - Report missing categories WITHOUT auto-filling (document gaps for manual review)
+  - CRITICAL: Verify core tokens (primary, secondary, accent) against semantic comments in source code
 
   ## Output Files
 
@@ -178,6 +179,7 @@ Task(subagent_type="ui-design-agent",
      - Add \"_metadata.extraction_source\": \"code_import\"
      - Add \"_metadata.files_analyzed\": {css, js, html file lists}
      - Add \"_metadata.completeness\": {status, missing_categories, recommendations}
+     - Add \"_metadata.conflicts\": Array of conflicting definitions (MANDATORY if conflicts exist)
      - Add \"_metadata.code_snippets\": Map of code snippets (see below)
      - Include \"source\" field for each token (e.g., \"file.css:23\")
 
@@ -198,12 +200,24 @@ Task(subagent_type="ui-design-agent",
   - Typical ranges: Simple declarations (1-5 lines), Utility classes (5-15 lines), Complete configs (15-50 lines)
   - Preserve original formatting and indentation
 
+  **Conflict Detection and Reporting**:
+  - When the same token is defined differently across multiple files, record in `_metadata.conflicts`
+  - Follow Agent schema for conflicts array structure (see ui-design-agent.md)
+  - Each conflict MUST include: token_name, category, all definitions with context, selected_value, selection_reason
+  - Selection priority:
+    1. Definitions with semantic comments explaining intent (/* Blue theme */, /* Primary brand color */)
+    2. Definitions that align with overall color scheme described in comments
+    3. When in doubt, report ALL variants and flag for manual review in completeness.recommendations
+
   ## Code Import Specific Requirements
   - ✅ Read discovered-files.json FIRST to get file paths
   - ✅ Track extraction source for each token (file:line)
   - ✅ Record complete code snippets in _metadata.code_snippets (complete blocks with dependencies/comments)
   - ✅ Include completeness assessment in _metadata
-  - ✅ Normalize inconsistent values into systematic scales
+  - ✅ Report inconsistent values with ALL source locations in _metadata.conflicts (DO NOT auto-normalize or choose)
+  - ✅ CRITICAL: Verify core theme tokens (primary, secondary, accent) match source code semantic intent
+  - ✅ When conflicts exist, prefer definitions with semantic comments explaining intent
+  - ❌ NO inference, NO smart filling, NO automatic conflict resolution
   - ❌ NO external research or web searches (code-only extraction)
 ")
 ```