claude-code-workflow 6.2.4 → 6.2.5

package/.claude/commands/workflow/ui-design/reference-page-generator.md

@@ -1,356 +0,0 @@
----
-name: workflow:ui-design:reference-page-generator
-description: Generate multi-component reference pages and documentation from design run extraction
-argument-hint: "[--design-run <path>] [--package-name <name>] [--output-dir <path>]"
-allowed-tools: Read,Write,Bash,Task,TodoWrite
-auto-continue: true
----
-
-# UI Design: Reference Page Generator
-
-## Overview
-
-Converts design run extraction results into shareable reference package with:
-- Interactive multi-component preview (preview.html + preview.css)
-- Component layout templates (layout-templates.json)
-
-**Role**: Takes existing design run (from `import-from-code` or other extraction commands) and generates preview pages for easy reference.
-
-## Usage
-
-### Command Syntax
-
-```bash
-/workflow:ui-design:reference-page-generator [FLAGS]
-
-# Flags
---design-run <path>      Design run directory path (required)
---package-name <name>    Package name for reference (required)
---output-dir <path>      Output directory (default: .workflow/reference_style)
-```
-
----
-
-## Execution Process
-
-```
-Input Parsing:
-   ├─ Parse flags: --design-run, --package-name, --output-dir
-   └─ Validation:
-      ├─ --design-run and --package-name REQUIRED
-      └─ Package name format: lowercase, alphanumeric, hyphens only
-
-Phase 0: Setup & Validation
-   ├─ Step 1: Validate required parameters
-   ├─ Step 2: Validate package name format
-   ├─ Step 3: Validate design run exists
-   ├─ Step 4: Check required extraction files (design-tokens.json, layout-templates.json)
-   └─ Step 5: Setup output directory
-
-Phase 1: Prepare Component Data
-   ├─ Step 1: Copy layout templates
-   ├─ Step 2: Copy design tokens
-   └─ Step 3: Copy animation tokens (optional)
-
-Phase 2: Preview Generation (Agent)
-   └─ Generate preview.html + preview.css via ui-design-agent
-```
-
-### Phase 0: Setup & Validation
-
-**Purpose**: Validate inputs, prepare output directory
-
-**Operations**:
-
-```bash
-# 1. Validate required parameters
-if [ -z "$design_run" ] || [ -z "$package_name" ]; then
-  echo "ERROR: --design-run and --package-name are required"
-  echo "USAGE: /workflow:ui-design:reference-page-generator --design-run <path> --package-name <name>"
-  exit 1
-fi
-
-# 2. Validate package name format (lowercase, alphanumeric, hyphens only)
-if ! [[ "$package_name" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
-  echo "ERROR: Invalid package name. Use lowercase, alphanumeric, and hyphens only."
-  echo "EXAMPLE: main-app-style-v1"
-  exit 1
-fi
-
-# 3. Validate design run exists
-if [ ! -d "$design_run" ]; then
-  echo "ERROR: Design run not found: $design_run"
-  echo "HINT: Run '/workflow:ui-design:import-from-code' first to create design run"
-  exit 1
-fi
-
-# 4. Check required extraction files exist
-required_files=(
-  "$design_run/style-extraction/style-1/design-tokens.json"
-  "$design_run/layout-extraction/layout-templates.json"
-)
-
-for file in "${required_files[@]}"; do
-  if [ ! -f "$file" ]; then
-    echo "ERROR: Required file not found: $file"
-    echo "HINT: Ensure design run has style and layout extraction results"
-    exit 1
-  fi
-done
-
-# 5. Setup output directory and validate
-output_dir="${output_dir:-.workflow/reference_style}"
-package_dir="${output_dir}/${package_name}"
-
-# Check if package directory exists and is not empty
-if [ -d "$package_dir" ] && [ "$(ls -A $package_dir 2>/dev/null)" ]; then
-  # Directory exists - check if it's a valid package or just a directory
-  if [ -f "$package_dir/metadata.json" ]; then
-    # Valid package - safe to overwrite
-    existing_version=$(jq -r '.version // "unknown"' "$package_dir/metadata.json" 2>/dev/null || echo "unknown")
-    echo "INFO: Overwriting existing package '$package_name' (version: $existing_version)"
-  else
-    # Directory exists but not a valid package
-    echo "ERROR: Directory '$package_dir' exists but is not a valid package"
-    echo "Use a different package name or remove the directory manually"
-    exit 1
-  fi
-fi
-
-mkdir -p "$package_dir"
-
-echo "[Phase 0] Setup Complete"
-echo "  Design Run: $design_run"
-echo "  Package: $package_name"
-echo "  Output: $package_dir"
-```
-
-<!-- TodoWrite: Initialize todo list -->
-
-**TodoWrite**:
-```json
-[
-  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
-  {"content": "Phase 1: 准备组件数据", "status": "in_progress", "activeForm": "复制布局模板"},
-  {"content": "Phase 2: 生成预览页面", "status": "pending", "activeForm": "生成预览"}
-]
-```
-
----
-
-### Phase 1: Prepare Component Data
-
-**Purpose**: Copy required files from design run to package directory
-
-**Operations**:
-
-```bash
-echo "[Phase 1] Preparing component data from design run"
-
-# 1. Copy layout templates as component patterns
-cp "${design_run}/layout-extraction/layout-templates.json" "${package_dir}/layout-templates.json"
-
-if [ ! -f "${package_dir}/layout-templates.json" ]; then
-  echo "ERROR: Failed to copy layout templates"
-  exit 1
-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"
-```
-
-<!-- TodoWrite: Mark Phase 1 complete, start Phase 2 -->
-
-**TodoWrite**:
-```json
-[
-  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
-  {"content": "Phase 2: 生成预览页面", "status": "in_progress", "activeForm": "生成预览"}
-]
-```
-
----
-
-### Phase 2: Preview Generation (Final Phase)
-
-**Purpose**: Generate interactive multi-component preview (preview.html + preview.css)
-
-**Agent Task**:
-
-```javascript
-Task(ui-design-agent): `
-  [PREVIEW_SHOWCASE_GENERATION]
-  Generate interactive multi-component showcase panel for reference package
-
-  PACKAGE_DIR: ${package_dir} | PACKAGE_NAME: ${package_name}
-
-  ## Input Files (MUST READ ALL)
-
-  1. ${package_dir}/layout-templates.json (component layout patterns - REQUIRED)
-  2. ${package_dir}/design-tokens.json (design tokens - REQUIRED)
-  3. ${package_dir}/animation-tokens.json (optional, if exists)
-
-  ## Generation Task
-
-  Create interactive showcase with these sections:
-
-  ### Section 1: Colors
-  - Display all color categories as color swatches
-  - Show hex/rgb values
-  - Group by: brand, semantic, surface, text, border
-
-  ### Section 2: Typography
-  - Display typography scale (font sizes, weights)
-  - Show typography combinations if available
-  - Include font family examples
-  - **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
-    * Common sizes table (small_text, body_text, heading)
-    * Common combinations with use cases
-
-  ### Section 3: Components
-  - Render all components from layout-templates.json (use layout_templates field)
-  - **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
-    * **Display usage_guide** (from layout-templates.json):
-      - Common sizes table with dimensions and use cases
-      - Variant recommendations (when to use primary/secondary/etc)
-      - Usage context list (typical scenarios)
-      - Accessibility tips checklist
-  - **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
-  - Display all variants side-by-side
-  - Show DOM structure with proper styling
-  - Include usage code snippets in <details> tags
-  - Clearly label component types (universal vs specialized)
-
-  ### Section 4: Spacing & Layout
-  - Visual spacing scale
-  - Border radius examples
-  - Shadow depth examples
-  - **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
-    * Size guide table (tight/normal/loose categories)
-    * Common patterns with use cases and pixel values
-
-  ### Section 5: Animations (if available)
-  - Animation duration examples
-  - Easing function demonstrations
-
-  ## Output Requirements
-
-  Generate 2 files:
-  1. ${package_dir}/preview.html
-  2. ${package_dir}/preview.css
-
-  ### preview.html Structure:
-  - Complete standalone HTML file
-  - Responsive design with mobile-first approach
-  - Sticky navigation for sections
-  - Interactive component demonstrations
-  - Code snippets in collapsible <details> elements
-  - Footer with package metadata
-
-  ### preview.css Structure:
-  - CSS Custom Properties from design-tokens.json
-  - Typography combination classes
-  - Component classes from layout-templates.json
-  - Preview page layout styles
-  - Interactive demo styles
-
-  ## Critical Requirements
-  - ✅ Read ALL input files (layout-templates.json, design-tokens.json, animation-tokens.json if exists)
-  - ✅ Generate complete, interactive showcase HTML
-  - ✅ All CSS uses var() references to design tokens
-  - ✅ Display ALL components from layout-templates.json
-  - ✅ **Separate universal components from specialized components** in the showcase
-  - ✅ Display component DOM structures with proper styling
-  - ✅ Include usage code snippets
-  - ✅ Label each component type clearly (Universal / Specialized)
-  - ✅ **Display usage recommendations** when available:
-    - Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
-    - Components: usage_guide for universal components (from layout-templates)
-    - Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
-  - ✅ Gracefully handle missing usage data (display sections only if data exists)
-  - ✅ Use Write() to save both files:
-    - ${package_dir}/preview.html
-    - ${package_dir}/preview.css
-  - ❌ NO external research or MCP calls
-`
-```
-
-<!-- TodoWrite: Mark all complete -->
-
-**TodoWrite**:
-```json
-[
-  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
-  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
-  {"content": "Phase 2: 生成预览页面", "status": "completed", "activeForm": "生成预览"}
-]
-```
-
----
-
-## Output Structure
-
-```
-${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)
-```
-
-## Completion Message
-
-```
-✅ Preview package generated!
-
-Package: {package_name}
-Location: {package_dir}
-
-Files:
-✓ layout-templates.json    {component_count} components
-✓ 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
-```
-
-## Error Handling
-
-### Common Errors
-
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Missing --design-run or --package-name | Required parameters not provided | Provide both flags |
-| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
-| Design run not found | Incorrect path or design run doesn't exist | Verify design run path, run import-from-code first |
-| Missing extraction files | Design run incomplete | Ensure design run has style-extraction and layout-extraction results |
-| Layout templates copy failed | layout-templates.json not found | Run import-from-code with Layout Agent first |
-| Preview generation failed | Invalid design tokens | Check design-tokens.json format |
-
----
-