From 02ee426af062b50c7977e28bbf6dc8138265ed6a Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 15 Nov 2025 16:30:40 +0800 Subject: [PATCH] Refactor UI Design Commands: Replace `/workflow:ui-design:update` with `/workflow:ui-design:design-sync` - Deleted the `list` command for design runs. - Removed the `update` command and its associated documentation. - Introduced `design-sync` command to synchronize finalized design system references to brainstorming artifacts. - Updated command references in `COMMAND_REFERENCE.md`, `GETTING_STARTED.md`, and `GETTING_STARTED_CN.md` to reflect the new command structure. - Ensured all related documentation and output styles are consistent with the new command naming and functionality. --- .claude/commands/workflow/resume.md | 105 --- .../commands/workflow/ui-design/capture.md | 380 ----------- .../ui-design/{update.md => design-sync.md} | 18 +- .../workflow/ui-design/explore-layers.md | 611 ------------------ .claude/commands/workflow/ui-design/list.md | 174 ----- .../agent-workflow-coordination.md | 21 - COMMAND_REFERENCE.md | 2 +- COMMAND_SPEC.md | 8 +- GETTING_STARTED.md | 4 +- GETTING_STARTED_CN.md | 4 +- 10 files changed, 12 insertions(+), 1315 deletions(-) delete mode 100644 .claude/commands/workflow/resume.md delete mode 100644 .claude/commands/workflow/ui-design/capture.md rename .claude/commands/workflow/ui-design/{update.md => design-sync.md} (94%) delete mode 100644 .claude/commands/workflow/ui-design/explore-layers.md delete mode 100644 .claude/commands/workflow/ui-design/list.md delete mode 100644 .claude/output-styles/agent-workflow-coordination.md diff --git a/.claude/commands/workflow/resume.md b/.claude/commands/workflow/resume.md deleted file mode 100644 index 98dc253a..00000000 --- a/.claude/commands/workflow/resume.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -name: resume -description: Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection -argument-hint: "session-id for workflow session to resume" -allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*) ---- - -# Sequential Workflow Resume Command - -## Usage -```bash -/workflow:resume "" -``` - -## Purpose -**Sequential command coordination for workflow resumption** by first analyzing current session status, then continuing execution with special resume context. This command orchestrates intelligent session resumption through two-step process. - -## Command Coordination Workflow - -### Phase 1: Status Analysis -1. **Call status command**: Execute `/workflow:status` to analyze current session state -2. **Verify session information**: Check session ID, progress, and current task status -3. **Identify resume point**: Determine where workflow was interrupted - -### Phase 2: Resume Execution -1. **Call execute with resume flag**: Execute `/workflow:execute --resume-session="{session-id}"` -2. **Pass session context**: Provide analyzed session information to execute command -3. **Direct agent execution**: Skip discovery phase, directly enter TodoWrite and agent execution - -## Implementation Protocol - -### Sequential Command Execution -```bash -# Phase 1: Analyze current session status -SlashCommand(command="/workflow:status") - -# Phase 2: Resume execution with special flag -SlashCommand(command="/workflow:execute --resume-session=\"{session-id}\"") -``` - -### Progress Tracking -```javascript -TodoWrite({ - todos: [ - { - content: "Analyze current session status and progress", - status: "in_progress", - activeForm: "Analyzing session status" - }, - { - content: "Resume workflow execution with session context", - status: "pending", - activeForm: "Resuming workflow execution" - } - ] -}); -``` - -## Resume Information Flow - -### Status Analysis Results -The `/workflow:status` command provides: -- **Session ID**: Current active session identifier -- **Current Progress**: Completed, in-progress, and pending tasks -- **Interruption Point**: Last executed task and next pending task -- **Session State**: Overall workflow status - -### Execute Command Context -The special `--resume-session` flag tells `/workflow:execute`: -- **Skip Discovery**: Don't search for sessions, use provided session ID -- **Direct Execution**: Go straight to TodoWrite generation and agent launching -- **Context Restoration**: Use existing session state and summaries -- **Resume Point**: Continue from identified interruption point - -## Error Handling - -### Session Validation Failures -- **Session not found**: Report missing session, suggest available sessions -- **Session inactive**: Recommend activating session first -- **Status command fails**: Retry once, then report analysis failure - -### Execute Resumption Failures -- **No pending tasks**: Report workflow completion status -- **Execute command fails**: Report resumption failure, suggest manual intervention - -## Success Criteria -1. **Status analysis complete**: Session state properly analyzed and reported -2. **Execute command launched**: Resume execution started with proper context -3. **Agent coordination**: TodoWrite and agent execution initiated successfully -4. **Context preservation**: Session state and progress properly maintained - -## Related Commands - -**Prerequisite Commands**: -- `/workflow:plan` or `/workflow:execute` - Workflow must be in progress or paused - -**Called by This Command** (2 phases): -- `/workflow:status` - Phase 1: Analyze current session status and identify resume point -- `/workflow:execute` - Phase 2: Resume execution with `--resume-session` flag - -**Follow-up Commands**: -- None - Workflow continues automatically via `/workflow:execute` - ---- -*Sequential command coordination for workflow session resumption* \ No newline at end of file diff --git a/.claude/commands/workflow/ui-design/capture.md b/.claude/commands/workflow/ui-design/capture.md deleted file mode 100644 index c080ee09..00000000 --- a/.claude/commands/workflow/ui-design/capture.md +++ /dev/null @@ -1,380 +0,0 @@ ---- -name: capture -description: Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping -argument-hint: --url-map "target:url,..." [--design-id ] [--session ] -allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__* ---- - -# Batch Screenshot Capture (/workflow:ui-design:capture) - -## Overview -Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes multiple URLs in parallel. - -**Strategy**: MCP → Playwright → Chrome → Manual -**Output**: Flat structure `screenshots/{target}.png` - -## Phase 1: Initialize & Parse - -### Step 1: Determine Base Path & Generate Design ID -```bash -# Priority: --design-id > session (latest) > standalone (create new) -if [ -n "$DESIGN_ID" ]; then - # Use provided design ID - relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit) - if [ -z "$relative_path" ]; then - echo "ERROR: Design run not found: $DESIGN_ID" - echo "HINT: Run '/workflow:ui-design:list' to see available design runs" - exit 1 - fi -elif [ -n "$SESSION_ID" ]; then - # Find latest in session or create new - relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2) - if [ -z "$relative_path" ]; then - design_id="design-run-$(date +%Y%m%d)-$RANDOM" - relative_path=".workflow/WFS-$SESSION_ID/${design_id}" - fi -else - # Create new standalone design run - design_id="design-run-$(date +%Y%m%d)-$RANDOM" - relative_path=".workflow/${design_id}" -fi - -# Create directory and convert to absolute path -bash(mkdir -p "$relative_path"/screenshots) -base_path=$(cd "$relative_path" && pwd) - -# Extract and display design_id -design_id=$(basename "$base_path") -echo "✓ Design ID: $design_id" -echo "✓ Base path: $base_path" -``` - -### Step 2: Parse URL Map -```javascript -// Input: "home:https://linear.app, pricing:https://linear.app/pricing" -url_entries = [] - -FOR pair IN split(params["--url-map"], ","): - parts = pair.split(":", 1) - - IF len(parts) != 2: - ERROR: "Invalid format: {pair}. Expected: 'target:url'" - EXIT 1 - - target = parts[0].strip().lower().replace(" ", "-") - url = parts[1].strip() - - // Validate target name - IF NOT regex_match(target, r"^[a-z0-9][a-z0-9_-]*$"): - ERROR: "Invalid target: {target}" - EXIT 1 - - // Add https:// if missing - IF NOT url.startswith("http"): - url = f"https://{url}" - - url_entries.append({target, url}) -``` - -**Output**: `base_path`, `url_entries[]` - -### Step 3: Initialize Todos -```javascript -TodoWrite({todos: [ - {content: "Parse url-map", status: "completed", activeForm: "Parsing"}, - {content: "Detect MCP tools", status: "in_progress", activeForm: "Detecting"}, - {content: "Capture screenshots", status: "pending", activeForm: "Capturing"}, - {content: "Verify results", status: "pending", activeForm: "Verifying"} -]}) -``` - -## Phase 2: Detect Screenshot Tools - -### Step 1: Check MCP Availability -```javascript -// List available MCP servers -all_resources = ListMcpResourcesTool() -available_servers = unique([r.server for r in all_resources]) - -// Check Chrome DevTools MCP -chrome_devtools = "chrome-devtools" IN available_servers -chrome_screenshot = check_tool_exists("mcp__chrome-devtools__take_screenshot") - -// Check Playwright MCP -playwright_mcp = "playwright" IN available_servers -playwright_screenshot = check_tool_exists("mcp__playwright__screenshot") - -// Determine primary tool -IF chrome_devtools AND chrome_screenshot: - tool = "chrome-devtools" -ELSE IF playwright_mcp AND playwright_screenshot: - tool = "playwright" -ELSE: - tool = null -``` - -**Output**: `tool` (chrome-devtools | playwright | null) - -### Step 2: Check Local Fallback -```bash -# Only if MCP unavailable -bash(which playwright 2>/dev/null || echo "") -bash(which google-chrome || which chrome || which chromium 2>/dev/null || echo "") -``` - -**Output**: `local_tools[]` - -## Phase 3: Capture Screenshots - -### Screenshot Format Options - -**PNG Format** (default, lossless): -- **Pros**: Lossless quality, best for detailed UI screenshots -- **Cons**: Larger file sizes (typically 200-500 KB per screenshot) -- **Parameters**: `format: "png"` (no quality parameter) -- **Use case**: High-fidelity UI replication, design system extraction - -**WebP Format** (optional, lossy/lossless): -- **Pros**: Smaller file sizes with good quality (50-70% smaller than PNG) -- **Cons**: Requires quality parameter, slight quality loss at high compression -- **Parameters**: `format: "webp", quality: 90` (80-100 recommended) -- **Use case**: Batch captures, network-constrained environments - -**JPEG Format** (optional, lossy): -- **Pros**: Smallest file sizes -- **Cons**: Lossy compression, not recommended for UI screenshots -- **Parameters**: `format: "jpeg", quality: 90` -- **Use case**: Photo-heavy pages, not recommended for UI design - -### Step 1: MCP Capture (If Available) -```javascript -IF tool == "chrome-devtools": - // Get or create page - pages = mcp__chrome-devtools__list_pages() - - IF pages.length == 0: - mcp__chrome-devtools__new_page({url: url_entries[0].url}) - page_idx = 0 - ELSE: - page_idx = 0 - - mcp__chrome-devtools__select_page({pageIdx: page_idx}) - - // Capture each URL - FOR entry IN url_entries: - mcp__chrome-devtools__navigate_page({url: entry.url, timeout: 30000}) - bash(sleep 2) - - // PNG format doesn't support quality parameter - // Use PNG for lossless quality (larger files) - mcp__chrome-devtools__take_screenshot({ - fullPage: true, - format: "png", - filePath: f"{base_path}/screenshots/{entry.target}.png" - }) - - // Alternative: Use WebP with quality for smaller files - // mcp__chrome-devtools__take_screenshot({ - // fullPage: true, - // format: "webp", - // quality: 90, - // filePath: f"{base_path}/screenshots/{entry.target}.webp" - // }) - -ELSE IF tool == "playwright": - FOR entry IN url_entries: - mcp__playwright__screenshot({ - url: entry.url, - output_path: f"{base_path}/screenshots/{entry.target}.png", - full_page: true, - timeout: 30000 - }) -``` - -### Step 2: Local Fallback (If MCP Failed) -```bash -# Try Playwright CLI -bash(playwright screenshot "$url" "$output_file" --full-page --timeout 30000) - -# Try Chrome headless -bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$url") -``` - -### Step 3: Manual Mode (If All Failed) -``` -⚠️ Manual Screenshot Required - -Failed URLs: - home: https://linear.app - Save to: .workflow/design-run-20250110/screenshots/home.png - -Steps: - 1. Visit URL in browser - 2. Take full-page screenshot - 3. Save to path above - 4. Type 'ready' to continue - -Options: ready | skip | abort -``` - -## Phase 4: Verification - -### Step 1: Scan Captured Files -```bash -bash(ls -1 $base_path/screenshots/*.{png,jpg,jpeg,webp} 2>/dev/null) -bash(du -h $base_path/screenshots/*.png 2>/dev/null) -``` - -### Step 2: Generate Metadata -```javascript -captured_files = Glob(f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}") -captured_targets = [basename_no_ext(f) for f in captured_files] - -metadata = { - "timestamp": current_timestamp(), - "total_requested": len(url_entries), - "total_captured": len(captured_targets), - "screenshots": [] -} - -FOR entry IN url_entries: - is_captured = entry.target IN captured_targets - - metadata.screenshots.append({ - "target": entry.target, - "url": entry.url, - "captured": is_captured, - "path": f"{base_path}/screenshots/{entry.target}.png" IF is_captured ELSE null, - "size_kb": file_size_kb IF is_captured ELSE null - }) - -Write(f"{base_path}/screenshots/capture-metadata.json", JSON.stringify(metadata)) -``` - -**Output**: `capture-metadata.json` - -## Completion - -### Todo Update -```javascript -TodoWrite({todos: [ - {content: "Parse url-map", status: "completed", activeForm: "Parsing"}, - {content: "Detect MCP tools", status: "completed", activeForm: "Detecting"}, - {content: "Capture screenshots", status: "completed", activeForm: "Capturing"}, - {content: "Verify results", status: "completed", activeForm: "Verifying"} -]}) -``` - -### Output Message -``` -✅ Batch screenshot capture complete! - -Summary: -- Requested: {total_requested} -- Captured: {total_captured} -- Success rate: {success_rate}% -- Method: {tool || "Local fallback"} - -Output: -{base_path}/screenshots/ -├── home.png (245.3 KB) -├── pricing.png (198.7 KB) -└── capture-metadata.json - -Next: /workflow:ui-design:extract --images "screenshots/*.png" -``` - -## Simple Bash Commands - -### Path Operations -```bash -# Find design directory -bash(find .workflow -type d -name "design-run-*" | head -1) - -# Create screenshot directory -bash(mkdir -p $BASE_PATH/screenshots) -``` - -### Tool Detection -```bash -# Check MCP -all_resources = ListMcpResourcesTool() - -# Check local tools -bash(which playwright 2>/dev/null) -bash(which google-chrome 2>/dev/null) -``` - -### Verification -```bash -# List captures -bash(ls -1 $base_path/screenshots/*.png 2>/dev/null) - -# File sizes -bash(du -h $base_path/screenshots/*.png) -``` - -## Output Structure - -``` -{base_path}/ -└── screenshots/ - ├── home.png - ├── pricing.png - ├── about.png - └── capture-metadata.json -``` - -## Error Handling - -### Common Errors -``` -ERROR: Invalid url-map format -→ Use: "target:url, target2:url2" - -ERROR: png screenshots do not support 'quality' -→ PNG format is lossless, no quality parameter needed -→ Remove quality parameter OR switch to webp/jpeg format - -ERROR: MCP unavailable -→ Using local fallback - -ERROR: All tools failed -→ Manual mode activated -``` - -### Format-Specific Errors -``` -❌ Wrong: format: "png", quality: 90 -✅ Right: format: "png" - -✅ Or use: format: "webp", quality: 90 -✅ Or use: format: "jpeg", quality: 90 -``` - -### Recovery -- **Partial success**: Keep successful captures -- **Retry**: Re-run with failed targets only -- **Manual**: Follow interactive guidance - -## Quality Checklist - -- [ ] All requested URLs processed -- [ ] File sizes > 1KB (valid images) -- [ ] Metadata JSON generated -- [ ] No missing targets (or documented) - -## Key Features - -- **MCP-first**: Prioritize managed tools -- **Multi-tier fallback**: 4 layers (MCP → Local → Manual) -- **Batch processing**: Parallel capture -- **Error tolerance**: Partial failures handled -- **Structured output**: Flat, predictable - -## Integration - -**Input**: `--url-map` (multiple target:url pairs) -**Output**: `screenshots/*.png` + `capture-metadata.json` -**Called by**: `/workflow:ui-design:imitate-auto`, `/workflow:ui-design:explore-auto` -**Next**: `/workflow:ui-design:extract` or `/workflow:ui-design:explore-layers` diff --git a/.claude/commands/workflow/ui-design/update.md b/.claude/commands/workflow/ui-design/design-sync.md similarity index 94% rename from .claude/commands/workflow/ui-design/update.md rename to .claude/commands/workflow/ui-design/design-sync.md index e654d98f..064e0211 100644 --- a/.claude/commands/workflow/ui-design/update.md +++ b/.claude/commands/workflow/ui-design/design-sync.md @@ -1,11 +1,11 @@ --- -name: update -description: Update brainstorming artifacts with finalized design system references from selected prototypes +name: design-sync +description: Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption argument-hint: --session [--selected-prototypes ""] allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*) --- -# Design Update Command +# Design Sync Command ## Overview @@ -349,15 +349,3 @@ After update, verify: - **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow -## Why Main Claude Execution? - -This command is executed directly by main Claude (not delegated to an Agent) because: - -1. **Simple Reference Generation**: Only generating file paths, not complex synthesis -2. **Context Preservation**: Main Claude has full session and conversation context -3. **Minimal Transformation**: Primarily updating references, not analyzing content -4. **Path Resolution**: Requires precise relative path calculation -5. **Edit Operations**: Better error recovery for Edit conflicts -6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates - -This ensures reliable, lightweight integration without Agent handoff overhead. diff --git a/.claude/commands/workflow/ui-design/explore-layers.md b/.claude/commands/workflow/ui-design/explore-layers.md deleted file mode 100644 index c0f157ce..00000000 --- a/.claude/commands/workflow/ui-design/explore-layers.md +++ /dev/null @@ -1,611 +0,0 @@ ---- -name: explore-layers -description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer -argument-hint: --url --depth <1-5> [--design-id ] [--session ] -allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__* ---- - -# Interactive Layer Exploration (/workflow:ui-design:explore-layers) - -## Overview -Single-URL depth-controlled interactive capture. Progressively explores UI layers from pages to Shadow DOM. - -**Depth Levels**: -- `1` = Page (full-page screenshot) -- `2` = Elements (key components) -- `3` = Interactions (modals, dropdowns) -- `4` = Embedded (iframes, widgets) -- `5` = Shadow DOM (web components) - -**Requirements**: Chrome DevTools MCP - -## Phase 1: Setup & Validation - -### Step 1: Parse Parameters -```javascript -url = params["--url"] -depth = int(params["--depth"]) - -// Validate URL -IF NOT url.startswith("http"): - url = f"https://{url}" - -// Validate depth -IF depth NOT IN [1, 2, 3, 4, 5]: - ERROR: "Invalid depth: {depth}. Use 1-5" - EXIT 1 -``` - -### Step 2: Determine Base Path -```bash -# Priority: --design-id > --session > create new -if [ -n "$DESIGN_ID" ]; then - # Exact match by design ID - relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit) - if [ -z "$relative_path" ]; then - echo "ERROR: Design run not found: $DESIGN_ID" - echo "HINT: Run '/workflow:ui-design:list' to see available design runs" - exit 1 - fi -elif [ -n "$SESSION_ID" ]; then - # Find latest in session or create new - relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2) - if [ -z "$relative_path" ]; then - design_id="design-run-$(date +%Y%m%d)-$RANDOM" - relative_path=".workflow/WFS-$SESSION_ID/${design_id}" - fi -else - # Create new standalone design run - design_id="design-run-$(date +%Y%m%d)-$RANDOM" - relative_path=".workflow/${design_id}" -fi - -# Create directory structure and convert to absolute path -bash(mkdir -p "$relative_path") -base_path=$(cd "$relative_path" && pwd) - -# Extract and display design_id -design_id=$(basename "$base_path") -echo "✓ Design ID: $design_id" -echo "✓ Base path: $base_path" - -# Create depth directories -bash(for i in $(seq 1 $depth); do mkdir -p "$base_path"/screenshots/depth-$i; done) -``` - -**Output**: `url`, `depth`, `base_path` - -### Step 3: Validate MCP Availability -```javascript -all_resources = ListMcpResourcesTool() -chrome_devtools = "chrome-devtools" IN [r.server for r in all_resources] - -IF NOT chrome_devtools: - ERROR: "explore-layers requires Chrome DevTools MCP" - ERROR: "Install: npm i -g @modelcontextprotocol/server-chrome-devtools" - EXIT 1 -``` - -### Step 4: Initialize Todos -```javascript -todos = [ - {content: "Setup and validation", status: "completed", activeForm: "Setting up"} -] - -FOR level IN range(1, depth + 1): - todos.append({ - content: f"Depth {level}: {DEPTH_NAMES[level]}", - status: "pending", - activeForm: f"Capturing depth {level}" - }) - -todos.append({content: "Generate layer map", status: "pending", activeForm: "Mapping"}) - -TodoWrite({todos}) -``` - -## Phase 2: Navigate & Load Page - -### Step 1: Get or Create Browser Page -```javascript -pages = mcp__chrome-devtools__list_pages() - -IF pages.length == 0: - mcp__chrome-devtools__new_page({url: url, timeout: 30000}) - page_idx = 0 -ELSE: - page_idx = 0 - mcp__chrome-devtools__select_page({pageIdx: page_idx}) - mcp__chrome-devtools__navigate_page({url: url, timeout: 30000}) - -bash(sleep 3) // Wait for page load -``` - -**Output**: `page_idx` - -## Phase 3: Depth 1 - Page Level - -### Step 1: Capture Full Page -```javascript -TodoWrite(mark_in_progress: "Depth 1: Page") - -output_file = f"{base_path}/screenshots/depth-1/full-page.png" - -mcp__chrome-devtools__take_screenshot({ - fullPage: true, - format: "png", - quality: 90, - filePath: output_file -}) - -layer_map = { - "url": url, - "depth": depth, - "layers": { - "depth-1": { - "type": "page", - "captures": [{ - "name": "full-page", - "path": output_file, - "size_kb": file_size_kb(output_file) - }] - } - } -} - -TodoWrite(mark_completed: "Depth 1: Page") -``` - -**Output**: `depth-1/full-page.png` - -## Phase 4: Depth 2 - Element Level (If depth >= 2) - -### Step 1: Analyze Page Structure -```javascript -IF depth < 2: SKIP - -TodoWrite(mark_in_progress: "Depth 2: Elements") - -snapshot = mcp__chrome-devtools__take_snapshot() - -// Filter key elements -key_types = ["nav", "header", "footer", "aside", "button", "form", "article"] -key_elements = [ - el for el in snapshot.interactiveElements - if el.type IN key_types OR el.role IN ["navigation", "banner", "main"] -][:10] // Limit to top 10 -``` - -### Step 2: Capture Element Screenshots -```javascript -depth_2_captures = [] - -FOR idx, element IN enumerate(key_elements): - element_name = sanitize(element.text[:20] or element.type) or f"element-{idx}" - output_file = f"{base_path}/screenshots/depth-2/{element_name}.png" - - TRY: - mcp__chrome-devtools__take_screenshot({ - uid: element.uid, - format: "png", - quality: 85, - filePath: output_file - }) - - depth_2_captures.append({ - "name": element_name, - "type": element.type, - "path": output_file, - "size_kb": file_size_kb(output_file) - }) - CATCH error: - REPORT: f"Skip {element_name}: {error}" - -layer_map.layers["depth-2"] = { - "type": "elements", - "captures": depth_2_captures -} - -TodoWrite(mark_completed: "Depth 2: Elements") -``` - -**Output**: `depth-2/{element}.png` × N - -## Phase 5: Depth 3 - Interaction Level (If depth >= 3) - -### Step 1: Analyze Interactive Triggers -```javascript -IF depth < 3: SKIP - -TodoWrite(mark_in_progress: "Depth 3: Interactions") - -// Detect structure -structure = mcp__chrome-devtools__evaluate_script({ - function: `() => ({ - modals: document.querySelectorAll('[role="dialog"], .modal').length, - dropdowns: document.querySelectorAll('[role="menu"], .dropdown').length, - tooltips: document.querySelectorAll('[role="tooltip"], [title]').length - })` -}) - -// Identify triggers -triggers = [] -FOR element IN snapshot.interactiveElements: - IF element.attributes CONTAINS ("data-toggle", "aria-haspopup"): - triggers.append({ - uid: element.uid, - type: "modal" IF "modal" IN element.classes ELSE "dropdown", - trigger: "click", - text: element.text - }) - ELSE IF element.attributes CONTAINS ("title", "data-tooltip"): - triggers.append({ - uid: element.uid, - type: "tooltip", - trigger: "hover", - text: element.text - }) - -triggers = triggers[:10] // Limit -``` - -### Step 2: Trigger Interactions & Capture -```javascript -depth_3_captures = [] - -FOR idx, trigger IN enumerate(triggers): - layer_name = f"{trigger.type}-{sanitize(trigger.text[:15]) or idx}" - output_file = f"{base_path}/screenshots/depth-3/{layer_name}.png" - - TRY: - // Trigger interaction - IF trigger.trigger == "click": - mcp__chrome-devtools__click({uid: trigger.uid}) - ELSE: - mcp__chrome-devtools__hover({uid: trigger.uid}) - - bash(sleep 1) - - // Capture - mcp__chrome-devtools__take_screenshot({ - fullPage: false, // Viewport only - format: "png", - quality: 90, - filePath: output_file - }) - - depth_3_captures.append({ - "name": layer_name, - "type": trigger.type, - "trigger_method": trigger.trigger, - "path": output_file, - "size_kb": file_size_kb(output_file) - }) - - // Dismiss (ESC key) - mcp__chrome-devtools__evaluate_script({ - function: `() => { - document.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape'})); - }` - }) - bash(sleep 0.5) - - CATCH error: - REPORT: f"Skip {layer_name}: {error}" - -layer_map.layers["depth-3"] = { - "type": "interactions", - "triggers": structure, - "captures": depth_3_captures -} - -TodoWrite(mark_completed: "Depth 3: Interactions") -``` - -**Output**: `depth-3/{interaction}.png` × N - -## Phase 6: Depth 4 - Embedded Level (If depth >= 4) - -### Step 1: Detect Iframes -```javascript -IF depth < 4: SKIP - -TodoWrite(mark_in_progress: "Depth 4: Embedded") - -iframes = mcp__chrome-devtools__evaluate_script({ - function: `() => { - return Array.from(document.querySelectorAll('iframe')).map(iframe => ({ - src: iframe.src, - id: iframe.id || 'iframe', - title: iframe.title || 'untitled' - })).filter(i => i.src && i.src.startsWith('http')); - }` -}) -``` - -### Step 2: Capture Iframe Content -```javascript -depth_4_captures = [] - -FOR idx, iframe IN enumerate(iframes): - iframe_name = f"iframe-{sanitize(iframe.title or iframe.id)}-{idx}" - output_file = f"{base_path}/screenshots/depth-4/{iframe_name}.png" - - TRY: - // Navigate to iframe URL in new tab - mcp__chrome-devtools__new_page({url: iframe.src, timeout: 30000}) - bash(sleep 2) - - mcp__chrome-devtools__take_screenshot({ - fullPage: true, - format: "png", - quality: 90, - filePath: output_file - }) - - depth_4_captures.append({ - "name": iframe_name, - "url": iframe.src, - "path": output_file, - "size_kb": file_size_kb(output_file) - }) - - // Close iframe tab - current_pages = mcp__chrome-devtools__list_pages() - mcp__chrome-devtools__close_page({pageIdx: current_pages.length - 1}) - - CATCH error: - REPORT: f"Skip {iframe_name}: {error}" - -layer_map.layers["depth-4"] = { - "type": "embedded", - "captures": depth_4_captures -} - -TodoWrite(mark_completed: "Depth 4: Embedded") -``` - -**Output**: `depth-4/iframe-*.png` × N - -## Phase 7: Depth 5 - Shadow DOM (If depth = 5) - -### Step 1: Detect Shadow Roots -```javascript -IF depth < 5: SKIP - -TodoWrite(mark_in_progress: "Depth 5: Shadow DOM") - -shadow_elements = mcp__chrome-devtools__evaluate_script({ - function: `() => { - const elements = Array.from(document.querySelectorAll('*')); - return elements - .filter(el => el.shadowRoot) - .map((el, idx) => ({ - tag: el.tagName.toLowerCase(), - id: el.id || \`shadow-\${idx}\`, - innerHTML: el.shadowRoot.innerHTML.substring(0, 100) - })); - }` -}) -``` - -### Step 2: Capture Shadow DOM Components -```javascript -depth_5_captures = [] - -FOR idx, shadow IN enumerate(shadow_elements): - shadow_name = f"shadow-{sanitize(shadow.id)}" - output_file = f"{base_path}/screenshots/depth-5/{shadow_name}.png" - - TRY: - // Inject highlight script - mcp__chrome-devtools__evaluate_script({ - function: `() => { - const el = document.querySelector('${shadow.tag}${shadow.id ? "#" + shadow.id : ""}'); - if (el) { - el.scrollIntoView({behavior: 'smooth', block: 'center'}); - el.style.outline = '3px solid red'; - } - }` - }) - - bash(sleep 0.5) - - // Full-page screenshot (component highlighted) - mcp__chrome-devtools__take_screenshot({ - fullPage: false, - format: "png", - quality: 90, - filePath: output_file - }) - - depth_5_captures.append({ - "name": shadow_name, - "tag": shadow.tag, - "path": output_file, - "size_kb": file_size_kb(output_file) - }) - - CATCH error: - REPORT: f"Skip {shadow_name}: {error}" - -layer_map.layers["depth-5"] = { - "type": "shadow-dom", - "captures": depth_5_captures -} - -TodoWrite(mark_completed: "Depth 5: Shadow DOM") -``` - -**Output**: `depth-5/shadow-*.png` × N - -## Phase 8: Generate Layer Map - -### Step 1: Compile Metadata -```javascript -TodoWrite(mark_in_progress: "Generate layer map") - -// Calculate totals -total_captures = sum(len(layer.captures) for layer in layer_map.layers.values()) -total_size_kb = sum( - sum(c.size_kb for c in layer.captures) - for layer in layer_map.layers.values() -) - -layer_map["summary"] = { - "timestamp": current_timestamp(), - "total_depth": depth, - "total_captures": total_captures, - "total_size_kb": total_size_kb -} - -Write(f"{base_path}/screenshots/layer-map.json", JSON.stringify(layer_map, indent=2)) - -TodoWrite(mark_completed: "Generate layer map") -``` - -**Output**: `layer-map.json` - -## Completion - -### Todo Update -```javascript -all_todos_completed = true -TodoWrite({todos: all_completed_todos}) -``` - -### Output Message -``` -✅ Interactive layer exploration complete! - -Configuration: -- URL: {url} -- Max depth: {depth} -- Layers explored: {len(layer_map.layers)} - -Capture Summary: - Depth 1 (Page): {depth_1_count} screenshot(s) - Depth 2 (Elements): {depth_2_count} screenshot(s) - Depth 3 (Interactions): {depth_3_count} screenshot(s) - Depth 4 (Embedded): {depth_4_count} screenshot(s) - Depth 5 (Shadow DOM): {depth_5_count} screenshot(s) - -Total: {total_captures} captures ({total_size_kb:.1f} KB) - -Output Structure: -{base_path}/screenshots/ -├── depth-1/ -│ └── full-page.png -├── depth-2/ -│ ├── navbar.png -│ └── footer.png -├── depth-3/ -│ ├── modal-login.png -│ └── dropdown-menu.png -├── depth-4/ -│ └── iframe-analytics.png -├── depth-5/ -│ └── shadow-button.png -└── layer-map.json - -Next: /workflow:ui-design:extract --images "screenshots/**/*.png" -``` - -## Simple Bash Commands - -### Directory Setup -```bash -# Create depth directories -bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done) -``` - -### Validation -```bash -# Check MCP -all_resources = ListMcpResourcesTool() - -# Count captures per depth -bash(ls $base_path/screenshots/depth-{1..5}/*.png 2>/dev/null | wc -l) -``` - -### File Operations -```bash -# List all captures -bash(find $base_path/screenshots -name "*.png" -type f) - -# Total size -bash(du -sh $base_path/screenshots) -``` - -## Output Structure - -``` -{base_path}/screenshots/ -├── depth-1/ -│ └── full-page.png -├── depth-2/ -│ ├── {element}.png -│ └── ... -├── depth-3/ -│ ├── {interaction}.png -│ └── ... -├── depth-4/ -│ ├── iframe-*.png -│ └── ... -├── depth-5/ -│ ├── shadow-*.png -│ └── ... -└── layer-map.json -``` - -## Depth Level Details - -| Depth | Name | Captures | Time | Use Case | -|-------|------|----------|------|----------| -| 1 | Page | Full page | 30s | Quick preview | -| 2 | Elements | Key components | 1-2min | Component library | -| 3 | Interactions | Modals, dropdowns | 2-4min | UI flows | -| 4 | Embedded | Iframes | 3-6min | Complete context | -| 5 | Shadow DOM | Web components | 4-8min | Full coverage | - -## Error Handling - -### Common Errors -``` -ERROR: Chrome DevTools MCP required -→ Install: npm i -g @modelcontextprotocol/server-chrome-devtools - -ERROR: Invalid depth -→ Use: 1-5 - -ERROR: Interaction trigger failed -→ Some modals may be skipped, check layer-map.json -``` - -### Recovery -- **Partial success**: Lower depth captures preserved -- **Trigger failures**: Interaction layer may be incomplete -- **Iframe restrictions**: Cross-origin iframes skipped - -## Quality Checklist - -- [ ] All depths up to specified level captured -- [ ] layer-map.json generated with metadata -- [ ] File sizes valid (> 500 bytes) -- [ ] Interaction triggers executed -- [ ] Shadow DOM elements highlighted - -## Key Features - -- **Depth-controlled**: Progressive capture 1-5 levels -- **Interactive triggers**: Click/hover for hidden layers -- **Iframe support**: Embedded content captured -- **Shadow DOM**: Web component internals -- **Structured output**: Organized by depth - -## Integration - -**Input**: Single URL + depth level (1-5) -**Output**: Hierarchical screenshots + layer-map.json -**Complements**: `/workflow:ui-design:capture` (multi-URL batch) -**Next**: `/workflow:ui-design:extract` for design analysis diff --git a/.claude/commands/workflow/ui-design/list.md b/.claude/commands/workflow/ui-design/list.md deleted file mode 100644 index 11ccafe0..00000000 --- a/.claude/commands/workflow/ui-design/list.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -name: list -description: List all available design runs with metadata (session, created time, prototype count) -argument-hint: [--session ] -allowed-tools: Bash(*), Read(*) ---- - -# List Design Runs (/workflow:ui-design:list) - -## Overview -List all available UI design runs across sessions or within a specific session. Displays design IDs with metadata for easy reference. - -**Output**: Formatted list with design-id, session, created time, and prototype count - -## Implementation - -### Step 1: Determine Search Scope -```bash -# Priority: --session > all sessions -search_path=$(if [ -n "$SESSION_ID" ]; then - echo ".workflow/WFS-$SESSION_ID" -else - echo ".workflow" -fi) -``` - -### Step 2: Find and Display Design Runs -```bash -echo "Available design runs:" -echo "" - -# Find all design-run directories -found_count=0 -while IFS= read -r line; do - timestamp=$(echo "$line" | cut -d' ' -f1) - path=$(echo "$line" | cut -d' ' -f2-) - - # Extract design_id from path - design_id=$(basename "$path") - - # Extract session from path - session_id=$(echo "$path" | grep -oP 'WFS-\K[^/]+' || echo "standalone") - - # Format created date - created_at=$(date -d "@${timestamp%.*}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "unknown") - - # Count prototypes - prototype_count=$(find "$path/prototypes" -name "*.html" 2>/dev/null | wc -l) - - # Display formatted output - echo " - $design_id" - echo " Session: $session_id" - echo " Created: $created_at" - echo " Prototypes: $prototype_count" - echo "" - - found_count=$((found_count + 1)) -done < <(find "$search_path" -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr) - -# Summary -if [ $found_count -eq 0 ]; then - echo " No design runs found." - echo "" - if [ -n "$SESSION_ID" ]; then - echo "💡 HINT: Try running '/workflow:ui-design:explore-auto' to create a design run" - else - echo "💡 HINT: Try running '/workflow:ui-design:explore-auto --session ' to create a design run" - fi -else - echo "Total: $found_count design run(s)" - echo "" - echo "💡 USE: /workflow:ui-design:generate --design-id \"\"" - echo " OR: /workflow:ui-design:generate --session \"\"" -fi -``` - -### Step 3: Execute List Command -```bash -Bash( - description: "List all UI design runs with metadata", - command: " - search_path=\"${search_path}\" - SESSION_ID=\"${SESSION_ID:-}\" - - echo 'Available design runs:' - echo '' - - found_count=0 - while IFS= read -r line; do - timestamp=\$(echo \"\$line\" | cut -d' ' -f1) - path=\$(echo \"\$line\" | cut -d' ' -f2-) - - design_id=\$(basename \"\$path\") - session_id=\$(echo \"\$path\" | grep -oP 'WFS-\\K[^/]+' || echo 'standalone') - created_at=\$(date -d \"@\${timestamp%.*}\" '+%Y-%m-%d %H:%M' 2>/dev/null || echo 'unknown') - prototype_count=\$(find \"\$path/prototypes\" -name '*.html' 2>/dev/null | wc -l) - - echo \" - \$design_id\" - echo \" Session: \$session_id\" - echo \" Created: \$created_at\" - echo \" Prototypes: \$prototype_count\" - echo '' - - found_count=\$((found_count + 1)) - done < <(find \"\$search_path\" -name 'design-run-*' -type d -printf '%T@ %p\\n' 2>/dev/null | sort -nr) - - if [ \$found_count -eq 0 ]; then - echo ' No design runs found.' - echo '' - if [ -n \"\$SESSION_ID\" ]; then - echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto\\' to create a design run' - else - echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto --session \\' to create a design run' - fi - else - echo \"Total: \$found_count design run(s)\" - echo '' - echo '💡 USE: /workflow:ui-design:generate --design-id \"\"' - echo ' OR: /workflow:ui-design:generate --session \"\"' - fi - " -) -``` - -## Example Output - -### With Session Filter -``` -$ /workflow:ui-design:list --session ui-redesign - -Available design runs: - - - design-run-20250109-143052 - Session: ui-redesign - Created: 2025-01-09 14:30 - Prototypes: 12 - - - design-run-20250109-101534 - Session: ui-redesign - Created: 2025-01-09 10:15 - Prototypes: 6 - -Total: 2 design run(s) - -💡 USE: /workflow:ui-design:generate --design-id "" - OR: /workflow:ui-design:generate --session "" -``` - -### All Sessions -``` -$ /workflow:ui-design:list - -Available design runs: - - - design-run-20250109-143052 - Session: ui-redesign - Created: 2025-01-09 14:30 - Prototypes: 12 - - - design-run-20250108-092314 - Session: landing-page - Created: 2025-01-08 09:23 - Prototypes: 3 - - - design-run-20250107-155623 - Session: standalone - Created: 2025-01-07 15:56 - Prototypes: 8 - -Total: 3 design run(s) - -💡 USE: /workflow:ui-design:generate --design-id "" - OR: /workflow:ui-design:generate --session "" -``` diff --git a/.claude/output-styles/agent-workflow-coordination.md b/.claude/output-styles/agent-workflow-coordination.md deleted file mode 100644 index c33ad0fc..00000000 --- a/.claude/output-styles/agent-workflow-coordination.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: Workflow Coordination -description: Core coordination principles for multi-agent development workflows ---- -## Core Agent Coordination Principles - -### Planning First Principle - -**Purpose**: Thorough upfront planning reduces risk, improves quality, and prevents costly rework. - - -### TodoWrite Coordination Rules - -1. **TodoWrite FIRST**: Always create TodoWrite entries *before* complex task execution begins. -2. **Context Before Implementation**: Context gathering must complete before implementation tasks begin. -3. **Agent Coordination**: Each agent is responsible for updating the status of its assigned todo. -4. **Progress Visibility**: Provides clear workflow state visibility to stakeholders. - -6. **Checkpoint Safety**: State is saved automatically after each agent completes its work. -7. **Interrupt/Resume**: The system must support full state preservation and restoration. - diff --git a/COMMAND_REFERENCE.md b/COMMAND_REFERENCE.md index a7ea841f..c73ad5e6 100644 --- a/COMMAND_REFERENCE.md +++ b/COMMAND_REFERENCE.md @@ -92,7 +92,7 @@ These commands orchestrate complex, multi-phase development processes, from plan | `/workflow:ui-design:style-extract` | Extract design style from reference images or text prompts using Claude's analysis. | | `/workflow:ui-design:layout-extract` | Extract structural layout information from reference images, URLs, or text prompts. | | `/workflow:ui-design:generate` | Assemble UI prototypes by combining layout templates with design tokens (pure assembler). | -| `/workflow:ui-design:update` | Update brainstorming artifacts with finalized design system references. | +| `/workflow:ui-design:design-sync` | Synchronize finalized design system references to brainstorming artifacts. | | `/workflow:ui-design:animation-extract` | Extract animation and transition patterns from URLs, CSS, or interactive questioning. | ### Internal Tools diff --git a/COMMAND_SPEC.md b/COMMAND_SPEC.md index 330c6191..afc65819 100644 --- a/COMMAND_SPEC.md +++ b/COMMAND_SPEC.md @@ -420,13 +420,13 @@ Specialized workflow for UI/UX design, from style extraction to prototype genera /workflow:ui-design:generate --session WFS-design-run ``` -### **/workflow:ui-design:update** -- **Syntax**: `/workflow:ui-design:update --session ...` -- **Responsibilities**: Synchronizes the finalized design system references into the core brainstorming artifacts (`synthesis-specification.md`) to make them available for the planning phase. +### **/workflow:ui-design:design-sync** +- **Syntax**: `/workflow:ui-design:design-sync --session [--selected-prototypes ""]` +- **Responsibilities**: Synchronizes the finalized design system references into the core brainstorming artifacts (`role analysis documents`) to make them available for the planning phase. - **Agent Calls**: None. - **Example**: ```bash - /workflow:ui-design:update --session WFS-my-app + /workflow:ui-design:design-sync --session WFS-my-app ``` ### **/workflow:ui-design:animation-extract** diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index d7de18f9..53ef62ee 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -100,8 +100,8 @@ For UI-focused projects, start with design exploration before implementation: ** # Step 1: Generate UI design variations (auto-creates session) /workflow:ui-design:explore-auto --prompt "A modern, clean admin dashboard login page" -# Step 2: Review designs in compare.html, then update brainstorming artifacts -/workflow:ui-design:update --session --selected-prototypes "login-v1,login-v2" +# Step 2: Review designs in compare.html, then sync design system to brainstorming artifacts +/workflow:ui-design:design-sync --session --selected-prototypes "login-v1,login-v2" # Step 3: Generate implementation plan with design references /workflow:plan diff --git a/GETTING_STARTED_CN.md b/GETTING_STARTED_CN.md index d77f7ca5..1c903297 100644 --- a/GETTING_STARTED_CN.md +++ b/GETTING_STARTED_CN.md @@ -100,8 +100,8 @@ # 第 1 步：生成 UI 设计变体（自动创建会话） /workflow:ui-design:explore-auto --prompt "一个现代、简洁的管理后台登录页面" -# 第 2 步：在 compare.html 中审查设计，然后更新头脑风暴工件 -/workflow:ui-design:update --session --selected-prototypes "login-v1,login-v2" +# 第 2 步：在 compare.html 中审查设计，然后同步设计系统到头脑风暴工件 +/workflow:ui-design:design-sync --session --selected-prototypes "login-v1,login-v2" # 第 3 步：使用设计引用生成实现计划 /workflow:plan