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

name, description, argument-hint, allowed-tools, auto-continue

name	description	argument-hint	allowed-tools	auto-continue
workflow:ui-design:import-from-code	Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis	[--base-path <path>] [--css "<glob>"] [--js "<glob>"] [--scss "<glob>"] [--html "<glob>"] [--style-files "<glob>"] [--session <id>]	Read,Write,Bash,Glob,Grep,Task,TodoWrite	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

/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

# 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:

# 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:

[
  {"content": "Phase 0: 发现和分类代码文件", "status": "in_progress", "activeForm": "发现代码文件"},
  {"content": "Phase 1: 并行Agent分析并生成completeness-report.json", "status": "pending", "activeForm": "生成design system"}
]

File Discovery Logic:

# 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:

[
  {"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

echo "[Phase 1] Starting parallel agent analysis (3 agents)"

Style Agent Task (style-completeness-report.json)

Agent Task:

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:

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:

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:

# 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:

[
  {"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