build-visual

Build Visual Skill

Translates a visual design input (HTML/CSS export directory or screenshot image) into a complete, installable WordPress FSE block theme with a custom-{slug} naming prefix. This skill is the core engine for Phase 14's visual input mode — it reads a design, extracts tokens, scaffolds the FSE theme directory, downloads and bundles Google Fonts, activates the theme via WP-CLI, and generates a visual-specific SETUP.md.

Critical sequencing: This skill runs AFTER build-mcp Section 2 (MCP adapter activated, database re-exported) and BEFORE build-git Section 3 (dynamic .gitignore update adds custom-{slug} to tracked paths).

This skill expects the following variables to already be set by the calling command:

• BUILD_DIR — absolute path to the build directory (set by build-scaffold Section 2)
• WP — the WP-CLI command prefix (e.g., wp --path=$BUILD_DIR or the Docker equivalent, set by build-scaffold Section 4)
• VISUAL_PATH — path to the design input (directory or image file, set by COMMAND.md Section 1)
• SLUG — build slug (set by COMMAND.md Section 1)
• SITE_TITLE — site title (set by COMMAND.md Section 1)
• PLUGIN_DIR — absolute path to the CoWork plugin directory

Section 1: Input Detection and Design Parsing

Detect whether VISUAL_PATH is a directory (HTML/CSS export) or an image file (screenshot), then parse the design to prepare for token extraction.

1a: Input Type Detection

# VISUAL_PATH set by COMMAND.md Section 1 argument parsing
THEME_SLUG="custom-${SLUG}"
THEME_DIR="$BUILD_DIR/wp-content/themes/${THEME_SLUG}"

if [ -d "$VISUAL_PATH" ]; then
  # Check if directory actually contains HTML/CSS files
  HTML_COUNT=$(find "$VISUAL_PATH" -maxdepth 3 -name "*.html" -o -name "*.css" 2>/dev/null | wc -l | tr -d ' ')
  if [ "$HTML_COUNT" -gt 0 ]; then
    VISUAL_MODE="html-css"
    echo "[Build] Visual input: HTML/CSS export directory ($VISUAL_PATH) — $HTML_COUNT files found"
  else
    # Directory contains no HTML/CSS — check for images (Canva/Miro image-only exports)
    IMG_FILE=$(find "$VISUAL_PATH" -maxdepth 3 \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.webp" \) 2>/dev/null | sort -k5 -rn 2>/dev/null | head -1)
    if [ -n "$IMG_FILE" ]; then
      VISUAL_MODE="screenshot"
      VISUAL_PATH="$IMG_FILE"
      echo "[Build] Visual input: directory contained only images — switching to screenshot mode ($VISUAL_PATH)"
    else
      echo ""
      echo "ERROR: --visual directory contains no HTML, CSS, or image files: $VISUAL_PATH"
      echo ""
      exit 1
    fi
  fi
elif [ -f "$VISUAL_PATH" ]; then
  # Check file extension for supported image formats
  EXT=$(echo "${VISUAL_PATH##*.}" | tr '[:upper:]' '[:lower:]')
  case "$EXT" in
    png|jpg|jpeg|gif|webp|bmp|tiff)
      VISUAL_MODE="screenshot"
      echo "[Build] Visual input: Screenshot image ($VISUAL_PATH)"
      ;;
    *)
      echo ""
      echo "ERROR: --visual path must be a directory (HTML/CSS export) or an image file (png, jpg, jpeg, gif, webp, bmp, tiff)"
      echo ""
      exit 1
      ;;
  esac
else
  echo ""
  echo "ERROR: --visual path does not exist: $VISUAL_PATH"
  echo ""
  exit 1
fi

echo "[Build] VISUAL_MODE=$VISUAL_MODE, THEME_SLUG=$THEME_SLUG"