From e20979975608c7640940f26e171ee227372ed2a3 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Tue, 11 Nov 2025 21:36:18 +0800 Subject: [PATCH] refactor(ui-design): enhance conflict detection and validation processes in import-from-code workflow --- .claude/agents/ui-design-agent.md | 41 ++++++++++++++++++- .../workflow/ui-design/import-from-code.md | 24 ++++++++--- 2 files changed, 58 insertions(+), 7 deletions(-) diff --git a/.claude/agents/ui-design-agent.md b/.claude/agents/ui-design-agent.md index 01af1d9a..2a4618d1 100644 --- a/.claude/agents/ui-design-agent.md +++ b/.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:" ` to find all primary color definitions + * Semantic search: `rg --color=never -B2 -A0 "^\s*--primary:" ` 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**: diff --git a/.claude/commands/workflow/ui-design/import-from-code.md b/.claude/commands/workflow/ui-design/import-from-code.md index 756e2d12..b72a9190 100644 --- a/.claude/commands/workflow/ui-design/import-from-code.md +++ b/.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) ") ```