wp-tailwind-migrate

WP Tailwind Migrate

Convert a theme that was built on the plain-CSS path into a Tailwind-native one, in place, without changing how it looks.

Usage: /wp-tailwind-migrate <theme-path> [--page <slug>]
       /wp-tailwind-migrate wp-content/themes/acme
       /wp-tailwind-migrate wp-content/themes/acme --page contacto

--page <slug> migrates a single template instead of the whole theme — useful for a first careful pass before committing to the full conversion.

Read skills/wp-tailwind-system/SKILL.md before starting. It owns the decision ladder and the file layout that every step below assumes.

Step 0 — Baseline gate

Refuse to proceed unless the theme is in a git repo with a clean tree. An uncommitted change would be indistinguishable from a migration artifact.

Every path below lives either in the plugin (bin/…, skills/…, starter-theme/…) or in the theme (assets/css/…, functions.php). The cd in this block changes which one a bare relative path would hit — so run plugin scripts by their full path, ${CLAUDE_PLUGIN_ROOT}/bin/…, never as a bare relative path.

cd <theme-path>
pwd   # record this absolute path — Step 6 re-anchors on it, never on <theme-path>
git rev-parse --is-inside-work-tree >/dev/null 2>&1 \
  || { echo "Error: <theme-path> is not a git repo. Init one first."; exit 1; }
[ -z "$(git status --porcelain)" ] \
  || { echo "Error: uncommitted changes. Commit or stash before migrating."; exit 1; }
git commit -q --allow-empty -m "chore: baseline before /wp-tailwind-migrate"

The theme must already build with Tailwind v4 — check, do not assume

Every step below writes the v4 layout: @import "tailwindcss", a @theme block, the four assets/css/src/tailwindcss/ directories, and an assets/css/dist/main.css that Step 5 makes the theme's only stylesheet. A theme on Tailwind v3 has none of that. It has a tailwind.config.js, a PostCSS build, and it compiles its partials into a stylesheet WordPress requires to sit at the theme root — style.css, the file carrying the Theme Name: header. Run these steps against it and the "migration" becomes a v3 → v4 upgrade plus a restructure of every partial in the theme, on top of the conversion that was actually asked for.