diff --git a/.claude/agents/ui-design-agent.md b/.claude/agents/ui-design-agent.md index 37e09fcc..c01c3b6d 100644 --- a/.claude/agents/ui-design-agent.md +++ b/.claude/agents/ui-design-agent.md @@ -59,37 +59,39 @@ You execute 6 distinct task types organized into 3 patterns. Each task includes **Purpose**: Generate complete design system components (execution phase) **Task Types**: -- `[DESIGN_SYSTEM_GENERATION_TASK]` - Generate design tokens + style guide -- `[LAYOUT_TEMPLATE_GENERATION_TASK]` - Generate layout templates with DOM structure -- `[ANIMATION_TOKEN_GENERATION_TASK]` - Generate animation tokens + guide +- `[DESIGN_SYSTEM_GENERATION_TASK]` - Generate design tokens with code snippets +- `[LAYOUT_TEMPLATE_GENERATION_TASK]` - Generate layout templates with DOM structure and code snippets +- `[ANIMATION_TOKEN_GENERATION_TASK]` - Generate animation tokens with code snippets **Common Process**: 1. **Load Context**: User selections (from Pattern 1) OR reference materials OR computed styles 2. **Apply Standards**: WCAG AA, OKLCH, semantic naming, accessibility 3. **MCP Research**: Query Exa for modern patterns and best practices (when applicable) 4. **Generate System**: Complete token/template system following specifications -5. **Write Files Immediately**: JSON + Markdown documentation +5. **Record Code Snippets**: When in code import mode, capture complete code blocks with context +6. **Write Files Immediately**: JSON files with embedded code snippets (when applicable) **Design System Generation**: - **Input**: Selected design direction OR visual references, computed styles (if available), user refinements - **Output**: - `{base_path}/style-extraction/style-{id}/design-tokens.json` (W3C format, OKLCH colors) - - `{base_path}/style-extraction/style-{id}/style-guide.md` - **Content**: Complete token system (colors, typography, spacing, opacity, shadows, border_radius, breakpoints, component_styles, typography.combinations) +- **Code Snippets** (when in code import mode): Record complete code blocks in `_metadata.code_snippets` with source location, line numbers, and context type - **MCP Use**: Research modern color palettes, typography trends, design system patterns **Layout Template Generation**: - **Input**: Selected layout concepts OR visual references, device type, DOM structure data (if available) - **Output**: `{base_path}/layout-extraction/layout-templates.json` - **Content**: For each target - semantic DOM structure (HTML5 + ARIA), CSS layout rules using var() placeholders, device optimizations, responsive breakpoints +- **Code Snippets** (when in code import mode): Record complete component/structure code in `extraction_metadata.code_snippets` (HTML, CSS utilities, React components) - **Focus**: Structure ONLY - no visual styling (colors, fonts belong in design tokens) **Animation Token Generation**: - **Input**: Extracted CSS animations, user specification (if available), design tokens context - **Output**: - `{base_path}/animation-extraction/animation-tokens.json` - - `{base_path}/animation-extraction/animation-guide.md` - **Content**: Duration scales, easing functions, keyframes, interaction patterns, transition utilities +- **Code Snippets** (when in code import mode): Record complete animation blocks in `_metadata.code_snippets` (@keyframes, transition configs, JS animations) - **Synthesis**: Normalize CSS extractions into semantic token system **Key Principles**: @@ -481,13 +483,16 @@ layout_results = mcp__exa__web_search_exa( ### Tool Operations **File Operations**: -- **Read**: Load design tokens, layout strategies, project artifacts +- **Read**: Load design tokens, layout strategies, project artifacts, source code files (for code import) + - When reading source code for extraction, capture complete code blocks with context + - Record file paths and line numbers for snippet tracking - **Write**: **PRIMARY RESPONSIBILITY** - Generate and write files directly to the file system - Agent MUST use Write() tool to create all output files - Agent receives ABSOLUTE file paths from orchestrator (e.g., `{base_path}/style-consolidation/style-1/design-tokens.json`) - Agent MUST create directories if they don't exist (use Bash `mkdir -p` if needed) - Agent MUST verify each file write operation succeeds - Agent does NOT return file contents as text with labeled sections + - When in code import mode, embed code snippets in `_metadata.code_snippets` or `extraction_metadata.code_snippets` - **Edit**: Update token definitions, refine layout strategies when files already exist **Path Handling**: @@ -503,8 +508,8 @@ layout_results = mcp__exa__web_search_exa( - If write fails, report error immediately with details - Example completion report: ``` - ✅ Written: style-1/design-tokens.json (12.5 KB) - ✅ Written: style-1/style-guide.md (8.3 KB) + ✅ Written: style-1/design-tokens.json (18.7 KB) + ✅ Recorded: 47 code snippets in _metadata.code_snippets ``` ## Quality Assurance @@ -596,6 +601,7 @@ layout_results = mcp__exa__web_search_exa( - ✅ Use mobile-first responsive design with token-based breakpoints - ✅ Implement semantic HTML5 with ARIA attributes (Pattern 2 & 3) - ✅ Execute MCP research for modern patterns (Pattern 1 & 2 when applicable) +- ✅ Record complete code snippets when in code import mode (_metadata.code_snippets with location, lines, snippet, context) **Target Independence**: - ✅ Process EXACTLY ONE target per task diff --git a/.claude/commands/workflow/ui-design/import-from-code.md b/.claude/commands/workflow/ui-design/import-from-code.md index 04b3268e..4937b961 100644 --- a/.claude/commands/workflow/ui-design/import-from-code.md +++ b/.claude/commands/workflow/ui-design/import-from-code.md @@ -98,9 +98,9 @@ echo " Output: $discovery_file" ```json [ {"content": "Phase 0: 发现和分类代码文件", "status": "in_progress", "activeForm": "发现代码文件"}, - {"content": "Phase 1.1: Style Agent - 提取视觉token (design-tokens.json, style-guide.md)", "status": "pending", "activeForm": "提取视觉token"}, - {"content": "Phase 1.2: Animation Agent - 提取动画token (animation-tokens.json, animation-guide.md)", "status": "pending", "activeForm": "提取动画token"}, - {"content": "Phase 1.3: Layout Agent - 提取布局模式 (layout-templates.json, layout-guide.md)", "status": "pending", "activeForm": "提取布局模式"} + {"content": "Phase 1.1: Style Agent - 提取视觉token及代码片段 (design-tokens.json + code_snippets)", "status": "pending", "activeForm": "提取视觉token"}, + {"content": "Phase 1.2: Animation Agent - 提取动画token及代码片段 (animation-tokens.json + code_snippets)", "status": "pending", "activeForm": "提取动画token"}, + {"content": "Phase 1.3: Layout Agent - 提取布局模式及代码片段 (layout-templates.json + code_snippets)", "status": "pending", "activeForm": "提取布局模式"} ] ``` @@ -163,23 +163,7 @@ Task(ui-design-agent): ` - JavaScript/TypeScript: Theme configs (Tailwind, styled-components, CSS-in-JS) - HTML: Inline styles, usage patterns - **Step 3: CLI-Assisted Analysis (Optional)** - - **When to use**: Large codebases (>20 files), complex framework detection, or ambiguous patterns - - **Tools available**: gemini, qwen (use gemini first, qwen as fallback) - - **Usage pattern**: - \`\`\`bash - cd ${source} && gemini -p " - PURPOSE: Analyze style system in codebase - TASK: • Identify design token patterns • Extract color/typography scales • Detect framework usage - MODE: analysis - CONTEXT: @**/*.{css,scss,ts,tsx,js,jsx} - EXPECTED: Design token patterns with file references - RULES: Focus on systematic patterns, include source file locations | analysis=READ-ONLY - " - \`\`\` - - **Integration**: Use CLI output to guide file reading and token extraction - - **Step 4: Smart inference for gaps** + **Step 3: Smart inference for gaps** - Infer missing tokens from existing patterns - Normalize inconsistent values into systematic scales - Fill missing categories from cross-file references @@ -194,19 +178,32 @@ Task(ui-design-agent): ` - Add "_metadata.extraction_source": "code_import" - Add "_metadata.files_analyzed": {css, js, html file lists} - Add "_metadata.completeness": {status, missing_categories, recommendations} + - Add "_metadata.code_snippets": Map of code snippets (see below) - Include "source" field for each token (e.g., "file.css:23") - 2. **style-guide.md** - - Design philosophy and usage guide - - List extracted tokens by category - - Document missing elements and recommendations + **Code Snippet Recording**: + - For each extracted token, record the actual code snippet in `_metadata.code_snippets` + - Structure: + ```json + "code_snippets": { + "file.css:23": { + "lines": "23-27", + "snippet": ":root {\n --color-primary: oklch(0.5555 0.15 270);\n /* Primary brand color */\n --color-primary-hover: oklch(0.6 0.15 270);\n}", + "context": "css-variable" + } + } + ``` + - Context types: "css-variable" | "css-class" | "js-object" | "js-theme-config" | "inline-style" + - Record complete code blocks with all dependencies and relevant comments + - Typical ranges: Simple declarations (1-5 lines), Utility classes (5-15 lines), Complete configs (15-50 lines) + - Preserve original formatting and indentation ## Code Import Specific Requirements - ✅ Read discovered-files.json FIRST to get file paths - ✅ Track extraction source for each token (file:line) + - ✅ Record complete code snippets in _metadata.code_snippets (complete blocks with dependencies/comments) - ✅ Include completeness assessment in _metadata - ✅ Normalize inconsistent values into systematic scales - - ✅ May use gemini/qwen CLI for analysis assistance (optional, for complex cases) - ❌ NO external research or web searches (code-only extraction) ` ``` @@ -238,23 +235,7 @@ Task(ui-design-agent): ` - JavaScript/TypeScript: Animation frameworks (Framer Motion, GSAP), CSS-in-JS - HTML: Inline styles, data-animation attributes - **Step 3: CLI-Assisted Analysis (Optional)** - - **When to use**: Framework detection, complex animation configs, or large file sets - - **Tools available**: gemini, qwen (use gemini first, qwen as fallback) - - **Usage pattern**: - \`\`\`bash - cd ${source} && gemini -p " - PURPOSE: Detect animation framework and extract animation tokens - TASK: • Identify animation framework (Framer Motion, GSAP, CSS) • Extract keyframes and transitions • Find animation timing functions - MODE: analysis - CONTEXT: @**/*.{css,scss,ts,tsx,js,jsx} - EXPECTED: Framework name, animation patterns with file references - RULES: Focus on animation-specific code, include source locations | analysis=READ-ONLY - " - \`\`\` - - **Integration**: Use CLI output to identify framework and guide extraction - - **Step 4: Framework detection & normalization** + **Step 3: Framework detection & normalization** - Detect animation frameworks used (css-animations | framer-motion | gsap | none) - Normalize into semantic token system - Cross-reference CSS animations with JS configs @@ -269,18 +250,22 @@ Task(ui-design-agent): ` - Add "_metadata.framework_detected" - Add "_metadata.files_analyzed" - Add "_metadata.completeness" + - Add "_metadata.code_snippets": Map of code snippets (same format as Style Agent) - Include "source" field for each token - 2. **animation-guide.md** - - Animation system overview - - Framework-specific usage guidelines + **Code Snippet Recording**: + - Record actual animation/transition code in `_metadata.code_snippets` + - Context types: "css-keyframes" | "css-transition" | "js-animation" | "framer-motion" | "gsap" + - Record complete blocks: @keyframes animations (10-30 lines), transition configs (5-15 lines), JS animation objects (15-50 lines) + - Include all animation steps, timing functions, and related comments + - Preserve original formatting and framework-specific syntax ## Code Import Specific Requirements - ✅ Read discovered-files.json FIRST to get file paths - ✅ Detect animation framework if present - ✅ Track extraction source for each token (file:line) + - ✅ Record complete code snippets in _metadata.code_snippets (complete animation blocks with all steps/timing) - ✅ Normalize framework-specific syntax into standard tokens - - ✅ May use gemini/qwen CLI for framework detection (optional, for complex cases) - ❌ NO external research or web searches (code-only extraction) ` ``` @@ -312,23 +297,7 @@ Task(ui-design-agent): ` - JavaScript/TypeScript: Layout components (React/Vue), grid configs - HTML: Semantic structure, component hierarchies - **Step 3: CLI-Assisted Analysis (Optional)** - - **When to use**: Complex component hierarchies, framework detection, or large component sets - - **Tools available**: gemini, qwen (use gemini first, qwen as fallback) - - **Usage pattern**: - \`\`\`bash - cd ${source} && gemini -p " - PURPOSE: Analyze layout system and component structure - TASK: • Detect naming convention (BEM/utility-first/css-modules) • Identify layout system (grid/flexbox) • Extract component patterns and responsive breakpoints - MODE: analysis - CONTEXT: @**/*.{css,scss,ts,tsx,js,jsx} - EXPECTED: Layout system type, naming convention, component patterns with file references - RULES: Focus on structural patterns, include breakpoints and responsive strategy | analysis=READ-ONLY - " - \`\`\` - - **Integration**: Use CLI output to identify conventions and guide component extraction - - **Step 4: System identification** + **Step 3: System identification** - Detect naming convention (BEM | SMACSS | utility-first | css-modules) - Identify layout system (12-column | flexbox | css-grid | custom) - Extract responsive strategy and breakpoints @@ -347,26 +316,25 @@ Task(ui-design-agent): ` * layout_system: {type, confidence, source_files} * responsive: {breakpoints, mobile_first, source} * completeness: {status, missing_items, recommendations} + * code_snippets: Map of code snippets (same format as Style Agent) - For each component in "layout_templates": * Include "source" field (file:line) * dom_structure with semantic HTML5 * css_layout_rules using var() placeholders - 2. **layout-guide.md** - - Layout System Overview: Document detected naming convention and layout system - - Component Patterns: List extracted components with variants and states - - Responsive Strategy: Explain breakpoint system and mobile-first approach - - Usage Guidelines: How to use the extracted patterns - - Code Examples: Show actual usage from source files - - Missing Patterns: Document gaps and recommendations + **Code Snippet Recording**: + - Record actual layout/component code in `extraction_metadata.code_snippets` + - Context types: "css-grid" | "css-flexbox" | "css-utility" | "html-structure" | "react-component" + - Record complete blocks: Utility classes (5-15 lines), HTML structures (10-30 lines), React components (20-100 lines) + - For components: include HTML structure + associated CSS rules + component logic + - Preserve original formatting and framework-specific syntax ## Code Import Specific Requirements - ✅ Read discovered-files.json FIRST to get file paths - ✅ Detect and document naming conventions - ✅ Identify layout system with confidence level - ✅ Extract component variants and states from usage patterns - - ✅ Generate BOTH JSON + MD files for complete documentation - - ✅ May use gemini/qwen CLI for system detection (optional, for complex cases) + - ✅ Record complete code snippets in extraction_metadata.code_snippets (complete components/structures) - ❌ NO external research or web searches (code-only extraction) ` ``` @@ -395,14 +363,11 @@ echo "[Phase 1] Parallel agent analysis complete" ${base_path}/ ├── style-extraction/ │ └── style-1/ -│ ├── design-tokens.json # Production-ready design tokens -│ └── style-guide.md # Design philosophy and usage +│ └── design-tokens.json # Production-ready design tokens with code snippets ├── animation-extraction/ -│ ├── animation-tokens.json # Animation/transition tokens -│ └── animation-guide.md # Animation usage guide +│ └── animation-tokens.json # Animation/transition tokens with code snippets ├── layout-extraction/ -│ ├── layout-templates.json # Layout patterns and component structures -│ └── layout-guide.md # Layout system usage guide +│ └── layout-templates.json # Layout patterns with code snippets └── .intermediates/ └── import-analysis/ └── discovered-files.json # All discovered files (JSON format) @@ -412,32 +377,20 @@ ${base_path}/ 1. **style-extraction/style-1/design-tokens.json** - Production-ready design tokens - Categories: colors, typography, spacing, opacity, border_radius, shadows, breakpoints - - Metadata: extraction_source, files_analyzed, completeness assessment + - Metadata: extraction_source, files_analyzed, completeness assessment, **code_snippets** + - **Code snippets**: Complete code blocks from source files (CSS variables, theme configs, inline styles) -2. **style-extraction/style-1/style-guide.md** - - Design system overview - - Token categories and usage - - Missing elements and recommendations - -3. **animation-extraction/animation-tokens.json** +2. **animation-extraction/animation-tokens.json** - Animation tokens: duration, easing, transitions, keyframes, interactions - Framework detection: css-animations, framer-motion, gsap, etc. - - Metadata: extraction_source, completeness assessment + - Metadata: extraction_source, completeness assessment, **code_snippets** + - **Code snippets**: Complete animation blocks (@keyframes, transition configs, JS animations) -4. **animation-extraction/animation-guide.md** - - Animation system overview - - Usage guidelines and examples - -5. **layout-extraction/layout-templates.json** +3. **layout-extraction/layout-templates.json** - Layout templates for each discovered component - - Extraction metadata: naming_convention, layout_system, responsive strategy + - Extraction metadata: naming_convention, layout_system, responsive strategy, **code_snippets** - Component patterns with DOM structure and CSS rules - -6. **layout-extraction/layout-guide.md** - - Layout system overview and detected conventions - - Component patterns documentation - - Responsive strategy and breakpoint usage - - Code examples from source files + - **Code snippets**: Complete component/structure code (HTML, CSS utilities, React components) **Intermediate Files**: `.intermediates/import-analysis/` - `discovered-files.json` - All discovered files in JSON format with counts and metadata diff --git a/.claude/commands/workflow/ui-design/reference-page-generator.md b/.claude/commands/workflow/ui-design/reference-page-generator.md index 42b1223a..c1c3ee42 100644 --- a/.claude/commands/workflow/ui-design/reference-page-generator.md +++ b/.claude/commands/workflow/ui-design/reference-page-generator.md @@ -127,17 +127,16 @@ echo " Output: $package_dir" ### Phase 1: Prepare Component Data -**Purpose**: Copy layout templates to package directory (used as component reference) +**Purpose**: Copy required files from design run to package directory **Operations**: ```bash echo "[Phase 1] Preparing component data from design run" -# Copy layout templates as component patterns +# 1. Copy layout templates as component patterns cp "${design_run}/layout-extraction/layout-templates.json" "${package_dir}/layout-templates.json" -# Verify copy if [ ! -f "${package_dir}/layout-templates.json" ]; then echo "ERROR: Failed to copy layout templates" exit 1 @@ -145,8 +144,25 @@ fi # Count components from layout templates component_count=$(jq -r '.layout_templates | length // 0' "${package_dir}/layout-templates.json" 2>/dev/null || echo 0) - echo " ✓ Layout templates copied (${component_count} components)" + +# 2. Copy design tokens (required for preview generation) +cp "${design_run}/style-extraction/style-1/design-tokens.json" "${package_dir}/design-tokens.json" + +if [ ! -f "${package_dir}/design-tokens.json" ]; then + echo "ERROR: Failed to copy design tokens" + exit 1 +fi +echo " ✓ Design tokens copied" + +# 3. Copy animation tokens if exists (optional) +if [ -f "${design_run}/animation-extraction/animation-tokens.json" ]; then + cp "${design_run}/animation-extraction/animation-tokens.json" "${package_dir}/animation-tokens.json" + echo " ✓ Animation tokens copied" +else + echo " ○ Animation tokens not found (optional)" +fi + echo "[Phase 1] Component data preparation complete" ``` @@ -178,8 +194,8 @@ Task(ui-design-agent): ` ## Input Files (MUST READ ALL) 1. ${package_dir}/layout-templates.json (component layout patterns - REQUIRED) - 2. ${design_run}/style-extraction/style-1/design-tokens.json (design tokens - REQUIRED) - 3. ${design_run}/animation-extraction/animation-tokens.json (optional, if exists) + 2. ${package_dir}/design-tokens.json (design tokens - REQUIRED) + 3. ${package_dir}/animation-tokens.json (optional, if exists) ## Generation Task @@ -264,6 +280,8 @@ Task(ui-design-agent): ` ${output_dir}/ └── ${package_name}/ ├── layout-templates.json # Layout templates (copied from design run) + ├── design-tokens.json # Design tokens (copied from design run) + ├── animation-tokens.json # Animation tokens (copied from design run, optional) ├── preview.html # Interactive showcase (NEW) └── preview.css # Showcase styling (NEW) ``` @@ -278,8 +296,10 @@ Location: {package_dir} Files: ✓ layout-templates.json {component_count} components -✓ preview.html Interactive showcase -✓ preview.css Showcase styling +✓ design-tokens.json Design tokens +✓ animation-tokens.json Animation tokens {if exists: "✓" else: "○ (not found)"} +✓ preview.html Interactive showcase +✓ preview.css Showcase styling Open preview: file://{absolute_path_to_package_dir}/preview.html