workflow:ui-design:reference-page-generator

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)

---

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:

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