From eeffa8a9e8740a52df048b8c63071f3d4bbd2b78 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Thu, 6 Nov 2025 21:00:49 +0800 Subject: [PATCH] Enhance UI Design Workflows with Intelligent Path Detection and Source Selection - Updated explore-auto.md to include a new phase for intelligent path detection and source selection, allowing the system to identify existing file paths from prompts and images. - Introduced conditional code import and completeness assessment based on detected design sources (code only, visual only, hybrid). - Modified phase execution flow to accommodate new checks for style, animation, and layout completeness based on the design source. - Added error handling for missing design elements and user prompts for visual supplementation. - Enhanced imitate-auto.md with intelligent path detection and a new phase for code import and completeness assessment, ensuring a hybrid approach when applicable. - Implemented detailed reporting for each phase, including missing elements and recommendations for improvement. - Created a comprehensive import-from-code.md file outlining the workflow for importing design systems from code files, detailing the execution process and error handling. --- .../workflow/ui-design/explore-auto.md | 132 +++- .../workflow/ui-design/imitate-auto.md | 246 +++---- .../workflow/ui-design/import-from-code.md | 613 ++++++++++++++++++ 3 files changed, 838 insertions(+), 153 deletions(-) create mode 100644 .claude/commands/workflow/ui-design/import-from-code.md diff --git a/.claude/commands/workflow/ui-design/explore-auto.md b/.claude/commands/workflow/ui-design/explore-auto.md index 433afbe5..c2ca1af5 100644 --- a/.claude/commands/workflow/ui-design/explore-auto.md +++ b/.claude/commands/workflow/ui-design/explore-auto.md @@ -107,7 +107,43 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(* ## 6-Phase Execution -### Phase 0a: Intelligent Prompt Parsing +### Phase 0a: Intelligent Path Detection & Source Selection +```bash +# Step 1: Detect if prompt/images contain existing file paths +code_files_detected = false +code_base_path = null +has_visual_input = false + +IF --prompt: + # Extract potential file paths from prompt + potential_paths = extract_paths_from_text(--prompt) + FOR path IN potential_paths: + IF file_or_directory_exists(path): + code_files_detected = true + code_base_path = path + BREAK + +IF --images: + # Check if images parameter points to existing files + IF glob_matches_files(--images): + has_visual_input = true + +# Step 2: Determine design source strategy +design_source = "unknown" +IF code_files_detected AND has_visual_input: + design_source = "hybrid" # Both code and visual +ELSE IF code_files_detected: + design_source = "code_only" # Only code files +ELSE IF has_visual_input OR --prompt: + design_source = "visual_only" # Only visual/prompt +ELSE: + ERROR: "No design source provided (code files, images, or prompt required)" + EXIT 1 + +STORE: design_source, code_base_path, has_visual_input +``` + +### Phase 0a-2: Intelligent Prompt Parsing ```bash # Parse variant counts from prompt or use explicit/default values IF --prompt AND (NOT --style-variants OR NOT --layout-variants): @@ -267,29 +303,64 @@ detect_target_type(target_list): RETURN "component" IF component_matches > page_matches ELSE "page" ``` -### Phase 1: Style Extraction +### Phase 0d: Code Import & Completeness Assessment (Conditional) ```bash -command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " + - (--images ? "--images \"{images}\" " : "") + - (--prompt ? "--prompt \"{prompt}\" " : "") + - "--mode explore --variants {style_variants}" -SlashCommand(command) +IF design_source IN ["code_only", "hybrid"]: + REPORT: "πŸ” Phase 0d: Code Import ({design_source})" + command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" --base-path \"{code_base_path}\"" + SlashCommand(command) -# Output: {style_variants} style cards with design_attributes -# SlashCommand blocks until phase complete -# Upon completion, IMMEDIATELY execute Phase 2.3 (auto-continue) + style_report = Read("{base_path}/style-completeness-report.json") + animation_report = Read("{base_path}/animation-completeness-report.json") + layout_report = Read("{base_path}/layout-completeness-report.json") + + style_complete = style_report.status == "complete" + animation_complete = animation_report.status == "complete" + layout_complete = layout_report.status == "complete" + + missing_categories = [] + IF NOT style_complete: missing_categories.extend(style_report.missing.keys()) + IF NOT animation_complete: missing_categories.extend(animation_report.missing.keys()) + IF NOT layout_complete: missing_categories.extend(layout_report.missing.keys()) + + needs_visual_supplement = false + + IF design_source == "code_only" AND NOT (style_complete AND layout_complete): + REPORT: "⚠️ Missing: {', '.join(missing_categories)}" + REPORT: "Options: 'continue' | 'supplement: ' | 'cancel'" + user_response = WAIT_FOR_USER_INPUT() + MATCH user_response: + "continue" β†’ needs_visual_supplement = false + "supplement: ..." β†’ needs_visual_supplement = true; --images = extract_path(user_response) + "cancel" β†’ EXIT 0 + default β†’ needs_visual_supplement = false + ELSE IF design_source == "hybrid": + needs_visual_supplement = true + + STORE: needs_visual_supplement, style_complete, animation_complete, layout_complete ``` -### Phase 2.3: Animation Extraction (Optional - Interactive Mode) +### Phase 1: Style Extraction ```bash -# Animation extraction for motion design patterns -REPORT: "πŸš€ Phase 2.3: Animation Extraction (interactive mode)" -REPORT: " β†’ Mode: Interactive specification" -REPORT: " β†’ Purpose: Define motion design patterns" +IF design_source == "visual_only" OR needs_visual_supplement: + REPORT: "🎨 Phase 1: Style Extraction (variants: {style_variants})" + command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " + + (--images ? "--images \"{images}\" " : "") + + (--prompt ? "--prompt \"{prompt}\" " : "") + + "--mode explore --variants {style_variants}" + SlashCommand(command) +ELSE: + REPORT: "βœ… Phase 1: Style (Using Code Import)" +``` -command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive" - -SlashCommand(command) +### Phase 2.3: Animation Extraction +```bash +IF design_source == "visual_only" OR NOT animation_complete: + REPORT: "πŸš€ Phase 2.3: Animation Extraction" + command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive" + SlashCommand(command) +ELSE: + REPORT: "βœ… Phase 2.3: Animation (Using Code Import)" # Output: animation-tokens.json + animation-guide.md # SlashCommand blocks until phase complete @@ -299,23 +370,16 @@ SlashCommand(command) ### Phase 2.5: Layout Extraction ```bash targets_string = ",".join(inferred_target_list) -command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " + - (--images ? "--images \"{images}\" " : "") + - (--prompt ? "--prompt \"{prompt}\" " : "") + - "--targets \"{targets_string}\" " + - "--mode explore --variants {layout_variants} " + - "--device-type \"{device_type}\"" -REPORT: "πŸš€ Phase 2.5: Layout Extraction (explore mode)" -REPORT: " β†’ Targets: {targets_string}" -REPORT: " β†’ Layout variants: {layout_variants}" -REPORT: " β†’ Device: {device_type}" - -SlashCommand(command) - -# Output: layout-templates.json with {targets Γ— layout_variants} layout structures -# SlashCommand blocks until phase complete -# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue) +IF (design_source == "visual_only" OR needs_visual_supplement) OR (NOT layout_complete): + REPORT: "πŸš€ Phase 2.5: Layout Extraction ({targets_string}, variants: {layout_variants}, device: {device_type})" + command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " + + (--images ? "--images \"{images}\" " : "") + + (--prompt ? "--prompt \"{prompt}\" " : "") + + "--targets \"{targets_string}\" --mode explore --variants {layout_variants} --device-type \"{device_type}\"" + SlashCommand(command) +ELSE: + REPORT: "βœ… Phase 2.5: Layout (Using Code Import)" ``` ### Phase 3: UI Assembly diff --git a/.claude/commands/workflow/ui-design/imitate-auto.md b/.claude/commands/workflow/ui-design/imitate-auto.md index aec8037b..a2653402 100644 --- a/.claude/commands/workflow/ui-design/imitate-auto.md +++ b/.claude/commands/workflow/ui-design/imitate-auto.md @@ -115,6 +115,23 @@ ELSE: # Create base directory Bash(mkdir -p "{base_path}") +# Step 0.1: Intelligent Path Detection +code_files_detected = false +code_base_path = null +design_source = "web" # Default for imitate-auto + +IF --prompt: + # Extract potential file paths from prompt + potential_paths = extract_paths_from_text(--prompt) + FOR path IN potential_paths: + IF file_or_directory_exists(path): + code_files_detected = true + code_base_path = path + design_source = "hybrid" # Web + Code + BREAK + +STORE: design_source, code_base_path + # Parse url-map url_map_string = {--url-map} VALIDATE: url_map_string is not empty, "--url-map parameter is required" @@ -196,11 +213,79 @@ TodoWrite({todos: [ ]}) ``` +### Phase 0.5: Code Import & Completeness Assessment (Conditional) + +```bash +# Only execute if code files detected +IF design_source == "hybrid": + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + REPORT: "πŸ” Phase 0.5: Code Import & Analysis" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + REPORT: " β†’ Source: {code_base_path}" + REPORT: " β†’ Mode: Hybrid (Web + Code)" + + command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" " + + "--base-path \"{code_base_path}\"" + + TRY: + SlashCommand(command) + CATCH error: + WARN: "Code import failed: {error}" + WARN: "Falling back to web-only mode" + design_source = "web" + + IF design_source == "hybrid": + # Read completeness reports + style_report = Read("{base_path}/style-completeness-report.json") + animation_report = Read("{base_path}/animation-completeness-report.json") + layout_report = Read("{base_path}/layout-completeness-report.json") + + # Assess overall completeness + style_complete = style_report.status == "complete" + animation_complete = animation_report.status == "complete" + layout_complete = layout_report.status == "complete" + + # Aggregate missing content + missing_categories = [] + IF NOT style_complete: + missing_categories.extend(style_report.missing.keys()) + IF NOT animation_complete: + missing_categories.extend(animation_report.missing.keys()) + IF NOT layout_complete: + missing_categories.extend(layout_report.missing.keys()) + + # Report code analysis results + IF len(missing_categories) > 0: + REPORT: "" + REPORT: "⚠️ Code Analysis Partial" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + REPORT: "Missing Design Elements:" + FOR category IN missing_categories: + REPORT: " β€’ {category}" + REPORT: "" + REPORT: "Web screenshots will supplement missing elements" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + ELSE: + REPORT: "" + REPORT: "βœ… Code Analysis Complete" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + REPORT: "All design elements extracted from code" + REPORT: "Web screenshots will verify and enhance findings" + REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + + STORE: style_complete, animation_complete, layout_complete + +TodoWrite(mark_completed: "Initialize and parse url-map", + mark_in_progress: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})") +``` + ### Phase 1: Screenshot Capture (Dual Mode) ```bash REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" REPORT: "πŸš€ Phase 1: Screenshot Capture" +IF design_source == "hybrid": + REPORT: " β†’ Purpose: Verify and supplement code analysis" REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" IF capture_mode == "batch": @@ -264,161 +349,84 @@ TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} target mark_in_progress: "Extract style (visual tokens)") ``` -### Phase 2: Style Extraction (Visual Tokens) +### Phase 2: Style Extraction ```bash -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -REPORT: "πŸš€ Phase 2: Style Extraction" -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +# Determine if style extraction needed +skip_style = (design_source == "hybrid" AND style_complete) -# Use all screenshots as input to extract single design system -IF capture_mode == "batch": - images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}" -ELSE: # deep mode - images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}" - -# Build extraction prompt -IF --prompt: - user_guidance = {--prompt} - extraction_prompt = f"Extract visual style tokens from '{primary_target}'. User guidance: {user_guidance}" +IF skip_style: + REPORT: "βœ… Phase 2: Style (Using Code Import)" ELSE: - extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages." + REPORT: "πŸš€ Phase 2: Style Extraction" + IF capture_mode == "batch": + images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}" + ELSE: + images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}" -# Build url-map string for style-extract (enables computed styles extraction) -url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()]) + IF --prompt: + extraction_prompt = f"Extract visual style tokens from '{primary_target}'. {--prompt}" + ELSE: + IF design_source == "hybrid": + extraction_prompt = f"Extract visual style tokens from '{primary_target}' to supplement code-imported design tokens." + ELSE: + extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages." -# Call style-extract command (imitate mode, automatically uses single variant) -# Pass --urls to enable auto-trigger of computed styles extraction -extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate" - -TRY: + url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()]) + extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate" SlashCommand(extract_command) -CATCH error: - ERROR: "Style extraction failed: {error}" - ERROR: "Cannot proceed without visual tokens" - EXIT 1 -# Verify extraction results -design_tokens_path = "{base_path}/style-extraction/style-1/design-tokens.json" -style_guide_path = "{base_path}/style-extraction/style-1/style-guide.md" - -IF NOT exists(design_tokens_path) OR NOT exists(style_guide_path): - ERROR: "style-extract did not generate required files" - EXIT 1 - -TodoWrite(mark_completed: "Extract style (complete design systems)", - mark_in_progress: "Extract animation (CSS auto mode)") +TodoWrite(mark_completed: "Extract style", mark_in_progress: "Extract animation") ``` -### Phase 2.3: Animation Extraction (CSS Auto Mode) +### Phase 2.3: Animation Extraction ```bash -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -REPORT: "πŸš€ Phase 2.3: Animation Extraction" -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +skip_animation = (design_source == "hybrid" AND animation_complete) -# Build URL list for animation-extract (auto mode for CSS extraction) -url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()]) - -# Call animation-extract command (auto mode for CSS animation extraction) -# Pass --urls to auto-trigger CSS animation/transition extraction via Chrome DevTools -animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto" - -TRY: +IF skip_animation: + REPORT: "βœ… Phase 2.3: Animation (Using Code Import)" +ELSE: + REPORT: "πŸš€ Phase 2.3: Animation Extraction" + url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()]) + animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto" SlashCommand(animation_extract_command) -CATCH error: - ERROR: "Animation extraction failed: {error}" - ERROR: "Cannot proceed without animation tokens" - EXIT 1 -# Verify animation extraction results -animation_tokens_path = "{base_path}/animation-extraction/animation-tokens.json" -animation_guide_path = "{base_path}/animation-extraction/animation-guide.md" - -IF NOT exists(animation_tokens_path) OR NOT exists(animation_guide_path): - ERROR: "animation-extract did not generate required files" - EXIT 1 - -TodoWrite(mark_completed: "Extract animation (CSS auto mode)", - mark_in_progress: "Extract layout (structure templates)") ``` -### Phase 2.5: Layout Extraction (Structure Templates) +### Phase 2.5: Layout Extraction ```bash -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -REPORT: "πŸš€ Phase 2.5: Layout Extraction" -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" +skip_layout = (design_source == "hybrid" AND layout_complete) -# Build URL map for layout-extract -url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()]) - -# Call layout-extract command (imitate mode for structure replication) -# Pass --urls to enable auto-trigger of DOM structure extraction -layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate" - -TRY: +IF skip_layout: + REPORT: "βœ… Phase 2.5: Layout (Using Code Import)" +ELSE: + REPORT: "πŸš€ Phase 2.5: Layout Extraction" + url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()]) + layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate" SlashCommand(layout_extract_command) -CATCH error: - ERROR: "Layout extraction failed: {error}" - ERROR: "Cannot proceed without layout templates" - EXIT 1 -# Verify layout extraction results -layout_templates_path = "{base_path}/layout-extraction/layout-templates.json" - -IF NOT exists(layout_templates_path): - ERROR: "layout-extract did not generate layout-templates.json" - EXIT 1 - -TodoWrite(mark_completed: "Extract layout (structure templates)", - mark_in_progress: f"Assemble UI for {len(target_names)} targets") +TodoWrite(mark_completed: "Extract layout", mark_in_progress: "Assemble UI") ``` -### Phase 3: Batch UI Assembly +### Phase 3: UI Assembly ```bash -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" REPORT: "πŸš€ Phase 3: UI Assembly" -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" - -# Call generate command (pure assembler - combines layout templates + design tokens) generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1" +SlashCommand(generate_command) -TRY: - SlashCommand(generate_command) -CATCH error: - ERROR: "UI assembly failed: {error}" - ERROR: "Layout templates or design tokens may be invalid" - EXIT 1 - -# Verify assembly results -prototypes_dir = "{base_path}/prototypes" -generated_html_files = Glob(f"{prototypes_dir}/*-style-1-layout-1.html") -generated_count = len(generated_html_files) - -IF generated_count < len(target_names): - WARN: "⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}" - -TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets", - mark_in_progress: session_id ? "Integrate design system" : "Standalone completion") +TodoWrite(mark_completed: "Assemble UI", mark_in_progress: session_id ? "Integrate design system" : "Completion") ``` ### Phase 4: Design System Integration ```bash -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -REPORT: "πŸš€ Phase 4: Design System Integration" -REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" - IF session_id: + REPORT: "πŸš€ Phase 4: Design System Integration" update_command = f"/workflow:ui-design:update --session {session_id}" - - TRY: - SlashCommand(update_command) - CATCH error: - WARN: "⚠️ Design system integration failed: {error}" - WARN: "Prototypes available at {base_path}/prototypes/" + SlashCommand(update_command) # Update metadata metadata = Read("{base_path}/.run-metadata.json") diff --git a/.claude/commands/workflow/ui-design/import-from-code.md b/.claude/commands/workflow/ui-design/import-from-code.md new file mode 100644 index 00000000..e0b637b9 --- /dev/null +++ b/.claude/commands/workflow/ui-design/import-from-code.md @@ -0,0 +1,613 @@ +--- +name: workflow:ui-design:import-from-code +description: Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis +argument-hint: "[--base-path ] [--css \"\"] [--js \"\"] [--scss \"\"] [--html \"\"] [--style-files \"\"] [--session ]" +allowed-tools: Read,Write,Bash,Glob,Grep,Task,TodoWrite +auto-continue: true +--- + +# UI Design: Import from Code + +## Overview + +Extract design system tokens from source code files (CSS/SCSS/JS/TS/HTML) using parallel agent analysis. Each agent can reference any file type for cross-source token extraction, and directly generates completeness reports with findings and gaps. + +**Key Characteristics**: +- Executes parallel agent analysis (3 agents: Style, Animation, Layout) +- Each agent can read ALL file types (CSS/SCSS/JS/TS/HTML) for cross-reference +- Direct completeness reporting without synthesis phase +- Graceful failure handling with detailed missing content analysis +- Returns concrete analysis results with recommendations + +## Core Functionality + +- **File Discovery**: Auto-discover or target specific CSS/SCSS/JS/HTML files +- **Parallel Analysis**: 3 agents extract tokens simultaneously with cross-file-type support +- **Completeness Reporting**: Each agent reports found tokens, missing content, and recommendations +- **Cross-Source Extraction**: Agents can reference any file type (e.g., Style agent can read JS theme configs) + +## Usage + +### Command Syntax + +```bash +/workflow:ui-design:import-from-code [FLAGS] + +# Flags +--base-path Base directory for analysis (default: current directory) +--css "" CSS file glob pattern (e.g., "theme/*.css") +--scss "" SCSS file glob pattern (e.g., "styles/*.scss") +--js "" JavaScript file glob pattern (e.g., "theme/*.js") +--html "" HTML file glob pattern (e.g., "pages/*.html") +--style-files "" Universal style file glob (applies to CSS/SCSS/JS) +--session Session identifier for workflow tracking +``` + +### Usage Examples + +```bash +# Basic usage - auto-discover all files +/workflow:ui-design:import-from-code --base-path ./ + +# Target specific directories +/workflow:ui-design:import-from-code --base-path ./src --css "theme/*.css" --js "theme/*.js" + +# Tailwind config only +/workflow:ui-design:import-from-code --js "tailwind.config.js" + +# CSS framework import +/workflow:ui-design:import-from-code --css "styles/**/*.scss" --html "components/**/*.html" + +# Universal style files +/workflow:ui-design:import-from-code --style-files "**/theme.*" +``` + +--- + +## Execution Process + +### Step 1: Setup & File Discovery + +**Purpose**: Initialize session, discover and categorize code files + +**Operations**: + +```bash +# 1. Initialize directories +base_path="${base_path:-.}" +intermediates_dir="${base_path}/.intermediates/import-analysis" +mkdir -p "$intermediates_dir" + +echo "[Phase 0] File Discovery Started" +``` + + + +**TodoWrite**: +```json +[ + {"content": "Phase 0: ε‘ηŽ°ε’Œεˆ†η±»δ»£η ζ–‡δ»Ά", "status": "in_progress", "activeForm": "ε‘ηŽ°δ»£η ζ–‡δ»Ά"}, + {"content": "Phase 1: 幢葌Agentεˆ†ζžεΉΆη”Ÿζˆcompleteness-report.json", "status": "pending", "activeForm": "η”Ÿζˆdesign system"} +] +``` + +**File Discovery Logic**: + +```bash +# 2. Discover files by type +cd "$base_path" || exit 1 + +# CSS files +if [ -n "$css" ]; then + find . -type f -name "*.css" | grep -E "$css" > "$intermediates_dir/css-files.txt" +elif [ -n "$style_files" ]; then + find . -type f -name "*.css" | grep -E "$style_files" > "$intermediates_dir/css-files.txt" +else + find . -type f -name "*.css" -not -path "*/node_modules/*" -not -path "*/dist/*" > "$intermediates_dir/css-files.txt" +fi + +# SCSS files +if [ -n "$scss" ]; then + find . -type f \( -name "*.scss" -o -name "*.sass" \) | grep -E "$scss" > "$intermediates_dir/scss-files.txt" +elif [ -n "$style_files" ]; then + find . -type f \( -name "*.scss" -o -name "*.sass" \) | grep -E "$style_files" > "$intermediates_dir/scss-files.txt" +else + find . -type f \( -name "*.scss" -o -name "*.sass" \) -not -path "*/node_modules/*" -not -path "*/dist/*" > "$intermediates_dir/scss-files.txt" +fi + +# JavaScript files (theme/style related) +if [ -n "$js" ]; then + find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) | grep -E "$js" > "$intermediates_dir/js-files.txt" +elif [ -n "$style_files" ]; then + find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) | grep -E "$style_files" > "$intermediates_dir/js-files.txt" +else + # Look for common theme/style file patterns + find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) -not -path "*/node_modules/*" -not -path "*/dist/*" | \ + grep -iE "(theme|style|color|token|design)" > "$intermediates_dir/js-files.txt" || touch "$intermediates_dir/js-files.txt" +fi + +# HTML files +if [ -n "$html" ]; then + find . -type f \( -name "*.html" -o -name "*.htm" \) | grep -E "$html" > "$intermediates_dir/html-files.txt" +else + find . -type f \( -name "*.html" -o -name "*.htm" \) -not -path "*/node_modules/*" -not -path "*/dist/*" > "$intermediates_dir/html-files.txt" +fi + +# 3. Count discovered files +css_count=$(wc -l < "$intermediates_dir/css-files.txt" 2>/dev/null || echo 0) +scss_count=$(wc -l < "$intermediates_dir/scss-files.txt" 2>/dev/null || echo 0) +js_count=$(wc -l < "$intermediates_dir/js-files.txt" 2>/dev/null || echo 0) +html_count=$(wc -l < "$intermediates_dir/html-files.txt" 2>/dev/null || echo 0) + +echo "[Phase 0] Discovered: CSS=$css_count, SCSS=$scss_count, JS=$js_count, HTML=$html_count" +``` + + + +**TodoWrite**: +```json +[ + {"content": "Phase 0: ε‘ηŽ°ε’Œεˆ†η±»δ»£η ζ–‡δ»Ά", "status": "completed", "activeForm": "ε‘ηŽ°δ»£η ζ–‡δ»Ά"}, + {"content": "Phase 1: 幢葌Agentεˆ†ζžεΉΆη”Ÿζˆcompleteness-report.json", "status": "in_progress", "activeForm": "η”Ÿζˆdesign system"} +] +``` + +--- + +### Step 2: Parallel Agent Analysis + +**Purpose**: Three agents analyze all file types in parallel, each producing completeness-report.json + +**Operations**: +- **Style Agent**: Extracts visual tokens (colors, typography, spacing) from ALL files (CSS/SCSS/JS/HTML) +- **Animation Agent**: Extracts animations/transitions from ALL files +- **Layout Agent**: Extracts layout patterns/component structures from ALL files + +**Validation**: +- Each agent can reference any file type (not restricted to single type) +- Direct output: Each agent generates completeness-report.json with findings + missing content +- No synthesis needed: Agents produce final output directly + +```bash +echo "[Phase 1] Starting parallel agent analysis (3 agents)" +``` + +#### Style Agent Task (style-completeness-report.json) + +**Agent Task**: + +```javascript +Task(ui-design-agent): ` + [STYLE_TOKENS_EXTRACTION] + Extract visual design tokens (colors, typography, spacing, shadows, borders) from ALL file types + + MODE: style-extraction | BASE_PATH: ${base_path} + + ## Input Files (Can reference ANY file type) + + **CSS/SCSS files (${css_count})**: + $(cat "${intermediates_dir}/css-files.txt" 2>/dev/null | head -20) + + **JavaScript/TypeScript files (${js_count})**: + $(cat "${intermediates_dir}/js-files.txt" 2>/dev/null | head -20) + + **HTML files (${html_count})**: + $(cat "${intermediates_dir}/html-files.txt" 2>/dev/null | head -20) + + ## Extraction Strategy + + **You can read ALL file types** - Cross-reference for better extraction: + 1. **CSS/SCSS**: Primary source for colors, typography, spacing, shadows, borders + 2. **JavaScript/TypeScript**: Theme objects (styled-components, Tailwind config, CSS-in-JS tokens) + 3. **HTML**: Inline styles, class usage patterns, component examples + + **Smart inference** - Fill gaps using cross-source data: + - Missing CSS colors? Check JS theme objects + - Missing spacing scale? Infer from existing values in any file type + - Missing typography? Check font-family usage in CSS + HTML + JS configs + + ## Output Requirements + + Generate 1 file: ${base_path}/style-completeness-report.json + + ### Structure: + { + "agent": "style-agent", + "status": "complete" | "partial" | "failed", + "analysis_time": "ISO8601 timestamp", + "files_analyzed": { + "css": ["list of CSS/SCSS files read"], + "js": ["list of JS/TS files read"], + "html": ["list of HTML files read"] + }, + "found": { + "colors": { + "count": 12, + "tokens": [ + {"value": "#0066cc", "variable": "--color-primary", "source": "file.css:23", "type": "brand"} + ], + "categories": { + "brand": 3, + "semantic": 4, + "surface": 2, + "text": 2, + "border": 1 + } + }, + "typography": { + "count": 8, + "font_families": [ + {"value": "system-ui, sans-serif", "variable": "--font-base", "source": "theme.js:12"} + ], + "font_sizes": [...], + "font_weights": [...], + "line_heights": [...], + "letter_spacing": [...] + }, + "spacing": { + "count": 12, + "tokens": [ + {"value": "0.25rem", "variable": "--spacing-1", "source": "styles.css:5"} + ], + "system_type": "8px-grid | 4px-grid | custom | none" + }, + "shadows": { + "count": 4, + "tokens": [ + {"value": "0 1px 2px rgba(0,0,0,0.05)", "variable": "--shadow-sm", "source": "theme.css:45"} + ] + }, + "borders": { + "radius": [...], + "width": [...], + "colors": [...] + }, + "breakpoints": { + "count": 5, + "tokens": [ + {"value": "640px", "variable": "$breakpoint-sm", "source": "media.scss:3"} + ] + } + }, + "missing": { + "colors": { + "categories": ["accent", "warning"], + "reason": "No accent or warning colors found in any file type" + }, + "typography": { + "items": ["letter-spacing scale"], + "reason": "No letter-spacing tokens found" + }, + "spacing": { + "items": ["negative spacing"], + "reason": "No negative spacing tokens found" + } + }, + "recommendations": [ + "Define accent color for interactive elements", + "Add semantic colors (warning, error, success)", + "Complete letter-spacing scale for typography system" + ] + } + + ## Completeness Criteria + - **colors**: β‰₯5 categories (brand, semantic, surface, text, border), β‰₯10 tokens + - **typography**: β‰₯3 font families, β‰₯8 sizes, β‰₯5 weights + - **spacing**: β‰₯8 values in consistent system + - **shadows**: β‰₯3 elevation levels + - **borders**: β‰₯3 radius values, β‰₯2 widths + + ## Critical Requirements + - βœ… Can read ANY file type (CSS/SCSS/JS/TS/HTML) - not restricted to CSS only + - βœ… Use Read() tool for each file you want to analyze + - βœ… Cross-reference between file types for better extraction + - βœ… Extract all visual token types systematically + - βœ… Report MISSING content with specific reasons + - βœ… Use Write() immediately to save: ${base_path}/style-completeness-report.json + - βœ… If no data found, report as "failed" with detailed missing analysis + - ❌ NO external research or MCP calls +` +``` + +#### Animation Agent Task (animation-completeness-report.json) + +**Agent Task**: + +```javascript +Task(ui-design-agent): ` + [ANIMATION_TOKENS_EXTRACTION] + Extract animation/transition tokens from ALL file types + + MODE: animation-extraction | BASE_PATH: ${base_path} + + ## Input Files (Can reference ANY file type) + + **CSS/SCSS files (${css_count})**: + $(cat "${intermediates_dir}/css-files.txt" 2>/dev/null | head -20) + + **JavaScript/TypeScript files (${js_count})**: + $(cat "${intermediates_dir}/js-files.txt" 2>/dev/null | head -20) + + **HTML files (${html_count})**: + $(cat "${intermediates_dir}/html-files.txt" 2>/dev/null | head -20) + + ## Extraction Strategy + + **You can read ALL file types** - Find animations anywhere: + 1. **CSS/SCSS**: @keyframes, transition properties, animation properties + 2. **JavaScript/TypeScript**: Animation configs (Framer Motion, GSAP, CSS-in-JS animations) + 3. **HTML**: Inline animation styles, data-animation attributes + + **Cross-reference**: + - CSS animations referenced in JS configs + - JS animation libraries with CSS class triggers + - HTML elements with animation classes/attributes + + ## Output Requirements + + Generate 1 file: ${base_path}/animation-completeness-report.json + + ### Structure: + { + "agent": "animation-agent", + "status": "complete" | "partial" | "failed", + "analysis_time": "ISO8601 timestamp", + "files_analyzed": { + "css": ["list of CSS/SCSS files read"], + "js": ["list of JS/TS files read"], + "html": ["list of HTML files read"] + }, + "framework_detected": "framer-motion | gsap | css-animations | react-spring | none", + "found": { + "durations": { + "count": 3, + "tokens": [ + {"value": "150ms", "variable": "--duration-fast", "source": "animations.css:12"} + ] + }, + "easing": { + "count": 4, + "tokens": [ + {"value": "cubic-bezier(0.4, 0, 0.2, 1)", "variable": "--ease-in-out", "source": "theme.js:45"} + ] + }, + "keyframes": { + "count": 5, + "animations": [ + {"name": "fadeIn", "keyframes": {...}, "source": "styles.css:67"} + ] + }, + "transitions": { + "count": 8, + "properties": ["opacity", "transform", "background-color"] + } + }, + "missing": { + "durations": { + "items": ["slow duration (>500ms)"], + "reason": "No slow animation durations found" + }, + "easing": { + "items": ["bounce easing"], + "reason": "No bounce or spring easing functions" + }, + "keyframes": { + "items": ["slide animations"], + "reason": "No slide-in/slide-out keyframes found" + } + }, + "recommendations": [ + "Add slow duration for complex animations", + "Define spring/bounce easing for interactive feedback", + "Create slide animations for drawer/modal transitions" + ] + } + + ## Completeness Criteria + - **durations**: β‰₯3 (fast, medium, slow) + - **easing**: β‰₯3 functions (ease-in, ease-out, ease-in-out) + - **keyframes**: β‰₯3 animation types (fade, scale, slide) + - **transitions**: β‰₯5 properties defined + + ## Critical Requirements + - βœ… Can read ANY file type (CSS/SCSS/JS/TS/HTML) + - βœ… Use Read() tool for each file you want to analyze + - βœ… Detect animation framework if used + - βœ… Extract all animation-related tokens + - βœ… Report MISSING content with specific reasons + - βœ… Use Write() immediately to save: ${base_path}/animation-completeness-report.json + - βœ… If no data found, report as "failed" with detailed missing analysis + - ❌ NO external research or MCP calls +` +``` + +#### Layout Agent Task (layout-completeness-report.json) + +**Agent Task**: + +```javascript +Task(ui-design-agent): ` + [LAYOUT_PATTERNS_EXTRACTION] + Extract layout patterns and component structures from ALL file types + + MODE: layout-extraction | BASE_PATH: ${base_path} + + ## Input Files (Can reference ANY file type) + + **CSS/SCSS files (${css_count})**: + $(cat "${intermediates_dir}/css-files.txt" 2>/dev/null | head -20) + + **JavaScript/TypeScript files (${js_count})**: + $(cat "${intermediates_dir}/js-files.txt" 2>/dev/null | head -20) + + **HTML files (${html_count})**: + $(cat "${intermediates_dir}/html-files.txt" 2>/dev/null | head -20) + + ## Extraction Strategy + + **You can read ALL file types** - Find layout patterns anywhere: + 1. **CSS/SCSS**: Grid systems, flexbox utilities, layout classes, media queries + 2. **JavaScript/TypeScript**: Layout components (React/Vue), grid configurations, responsive logic + 3. **HTML**: Layout structures, semantic patterns, component hierarchies + + **Cross-reference**: + - HTML structure + CSS classes β†’ layout system + - JS components + CSS styles β†’ component patterns + - Responsive classes across all file types + + ## Output Requirements + + Generate 1 file: ${base_path}/layout-completeness-report.json + + ### Structure: + { + "agent": "layout-agent", + "status": "complete" | "partial" | "failed", + "analysis_time": "ISO8601 timestamp", + "files_analyzed": { + "css": ["list of CSS/SCSS files read"], + "js": ["list of JS/TS files read"], + "html": ["list of HTML files read"] + }, + "naming_convention": "BEM | SMACSS | utility-first | css-modules | custom", + "found": { + "layout_system": { + "type": "12-column | flexbox | css-grid | custom", + "confidence": "high | medium | low", + "container_classes": ["container", "wrapper"], + "row_classes": ["row"], + "column_classes": ["col-1", "col-md-6"], + "source_files": ["grid.css", "Layout.jsx"] + }, + "components": { + "count": 5, + "patterns": { + "button": { + "base_class": "btn", + "variants": ["btn-primary", "btn-secondary"], + "sizes": ["btn-sm", "btn-lg"], + "states": ["hover", "active", "disabled"], + "source": "button.css:12" + }, + "card": {...}, + "input": {...} + } + }, + "responsive": { + "breakpoint_prefixes": ["sm:", "md:", "lg:", "xl:"], + "mobile_first": true, + "source": "responsive.scss:5" + } + }, + "missing": { + "layout_system": { + "items": ["gap utilities"], + "reason": "No gap/gutter utilities found in grid system" + }, + "components": { + "items": ["modal", "dropdown", "tabs"], + "reason": "Common interactive components not found" + }, + "responsive": { + "items": ["container queries"], + "reason": "Only media queries found, no container queries" + } + }, + "recommendations": [ + "Add gap utilities for consistent spacing in grid layouts", + "Define modal/dropdown/tabs component patterns", + "Consider container queries for component-level responsiveness" + ] + } + + ## Completeness Criteria + - **layout_system**: Clear grid/flexbox system identified + - **components**: β‰₯5 component patterns (button, card, input, modal, dropdown) + - **responsive**: β‰₯3 breakpoints, clear mobile-first strategy + - **naming_convention**: Consistent pattern identified + + ## Critical Requirements + - βœ… Can read ANY file type (CSS/SCSS/JS/TS/HTML) + - βœ… Use Read() tool for each file you want to analyze + - βœ… Identify naming conventions and layout systems + - βœ… Extract component patterns with variants and states + - βœ… Report MISSING content with specific reasons + - βœ… Use Write() immediately to save: ${base_path}/layout-completeness-report.json + - βœ… If no data found, report as "failed" with detailed missing analysis + - ❌ NO external research or MCP calls +` +``` + +**Wait for All Agents**: + +```bash +# Note: Agents run in parallel and write separate completeness reports +# Each agent generates its own completeness-report.json directly +# No synthesis phase needed +echo "[Phase 1] Parallel agent analysis complete" +``` + + + +**TodoWrite**: +```json +[ + {"content": "Phase 0: ε‘ηŽ°ε’Œεˆ†η±»δ»£η ζ–‡δ»Ά", "status": "completed", "activeForm": "ε‘ηŽ°δ»£η ζ–‡δ»Ά"}, + {"content": "Phase 1: 幢葌Agentεˆ†ζžεΉΆη”Ÿζˆcompleteness-report.json", "status": "completed", "activeForm": "η”Ÿζˆdesign system"} +] +``` + +--- + +## Output Files + +### Generated Files + +**Location**: `${base_path}/` + +**Files**: +1. **style-completeness-report.json** + - Style agent analysis results + - Found tokens: colors, typography, spacing, shadows, borders + - Missing content: specific gaps with reasons + - Recommendations: actionable improvement suggestions + +2. **animation-completeness-report.json** + - Animation agent analysis results + - Found tokens: durations, easing, keyframes, transitions + - Framework detection: framer-motion, gsap, css-animations, etc. + - Missing content: animation gaps with reasons + +3. **layout-completeness-report.json** + - Layout agent analysis results + - Found patterns: layout system, components, responsive design + - Naming convention: BEM, SMACSS, utility-first, etc. + - Missing content: layout/component gaps with reasons + +**Intermediate Files**: `.intermediates/import-analysis/` +- `css-files.txt` - Discovered CSS/SCSS files +- `js-files.txt` - Discovered JS/TS files +- `html-files.txt` - Discovered HTML files + +--- + +## Error Handling + +### Common Errors + +| Error | Cause | Resolution | +|-------|-------|------------| +| No files discovered | Glob patterns too restrictive or wrong base-path | Check glob patterns and base-path, verify file locations | +| Agent reports "failed" status | No tokens found in any file | Review file content, check if files contain design tokens | +| Empty completeness reports | Files exist but contain no extractable tokens | Manually verify token definitions in source files | +| Missing file type | Specific file type not discovered | Use explicit glob flags (--css, --js, --html, --scss) | + +--- + +## Best Practices + +1. **Use auto-discovery for full projects**: Omit glob flags to discover all files automatically +2. **Target specific directories for speed**: Use `--base-path` + specific globs for focused analysis +3. **Cross-reference agent reports**: Compare all three completeness reports to identify gaps +4. **Review missing content**: Check `missing` field in reports for actionable improvements +5. **Verify file discovery**: Check `.intermediates/import-analysis/*-files.txt` if agents report no data