Claude-Code-Workflow/.claude/commands/workflow/ui-design/reference-page-generator.md

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

name	description	argument-hint	allowed-tools	auto-continue
workflow:ui-design:reference-page-generator	Generate multi-component reference pages and documentation from design run extraction	[--design-run <path>] [--package-name <name>] [--output-dir <path>]	Read,Write,Bash,Task,TodoWrite	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

/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)

Usage Examples

# Basic usage
/workflow:ui-design:reference-page-generator --design-run .workflow/WFS-123/design-run-456 --package-name main-app-style-v1

# Custom output directory
/workflow:ui-design:reference-page-generator --design-run .workflow/WFS-123/design-run-456 --package-name main-app-style-v1 --output-dir ./style-references

---

Execution Process

Phase 0: Setup & Validation

Purpose: Validate inputs, prepare output directory

Operations:

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

[
  {"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 layout templates to package directory (used as component reference)

Operations:

echo "[Phase 1] Preparing component data from design run"

# 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
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)"
echo "[Phase 1] Component data preparation complete"

TodoWrite:

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

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. ${design_run}/style-extraction/style-1/design-tokens.json (design tokens - REQUIRED)
  3. ${design_run}/animation-extraction/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

  ### Section 3: Components
  - Render all components from layout-templates.json (use layout_templates field)
  - Display all variants side-by-side
  - Show DOM structure with proper styling
  - Include usage code snippets in <details> tags

  ### Section 4: Spacing & Layout
  - Visual spacing scale
  - Border radius examples
  - Shadow depth examples

  ### 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
  - ✅ Display component DOM structures with proper styling
  - ✅ Include usage code snippets
  - ✅ Use Write() to save both files:
    - ${package_dir}/preview.html
    - ${package_dir}/preview.css
  - ❌ NO external research or MCP calls
`

TodoWrite:

[
  {"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)
    ├── 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
✓ 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

---