catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-05 01:50:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

Enhance UI Design Workflows with Intelligent Path Detection and Source Selection

Browse Source 
- 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.
This commit is contained in:
catlog22
2025-11-06 21:00:49 +08:00
parent 096621eee7
commit eeffa8a9e8
3 changed files with 838 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
.claude/commands/workflow/ui-design/explore-auto.md
View File

@@ -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: <images>' | '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

246
.claude/commands/workflow/ui-design/imitate-auto.md
View File

@@ -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")

613
.claude/commands/workflow/ui-design/import-from-code.md Normal file
View File

@@ -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 <path>] [--css \"<glob>\"] [--js \"<glob>\"] [--scss \"<glob>\"] [--html \"<glob>\"] [--style-files \"<glob>\"] [--session <id>]"
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 <path> Base directory for analysis (default: current directory)
--css "<glob>" CSS file glob pattern (e.g., "theme/*.css")
--scss "<glob>" SCSS file glob pattern (e.g., "styles/*.scss")
--js "<glob>" JavaScript file glob pattern (e.g., "theme/*.js")
--html "<glob>" HTML file glob pattern (e.g., "pages/*.html")
--style-files "<glob>" Universal style file glob (applies to CSS/SCSS/JS)
--session <id> 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: Initialize todo list -->
**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: Mark Phase 0 complete, start Phase 1 -->
**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: Mark all 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