/wp-block-theme-converter

name: wp-block-theme-converter
description: Convert HTML/CSS/JavaScript projects into production-ready WordPress block themes (Full Site Editing) with theme.json v3, FSE templates and parts, block patterns, the Interactivity API, Block Bindings, and optional WooCommerce support. Use whenever the user wants to convert, port, or rebuild a static site, landing page, or classic WordPress theme as a block, FSE, or Gutenberg theme; scaffold a block theme from scratch; generate theme.json from design tokens; turn HTML into block patterns or templates; build custom blocks or style variations; migrate content or page builders (Elementor, Divi) to blocks; or debug a block theme. Trigger on phrases like "convert to WordPress", "make this a WP theme", "block theme from HTML", "FSE theme", "theme.json", or "block pattern", and on the commands /convert-to-wp-theme, /scaffold-wp-theme, /wp-pattern, /wp-theme-json, /wp-template, /wp-block, /wp-migrate, /wp-plugin-theme, /wp-variation, /wp-classic-to-fse, and /wp-debug.
version: 3.0.0
license: MIT

WordPress Block Theme Converter

Convert HTML/CSS/JavaScript projects into production-ready WordPress Block Themes with Full Site Editing (FSE) support, theme.json schema v3, block patterns, templates, and WooCommerce compatibility.

---

Behavioral Principles

**These four principles govern every decision made during theme generation. They are non-negotiable and override any temptation to "just get it done."**

**Tradeoff:** These principles bias toward caution over speed. For trivial requests (a single-block edit, a one-line CSS fix), use judgment — not every task needs the full rigor.

1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before generating ANY file:

• **State assumptions explicitly.** If the user didn't specify a color palette, font stack, or layout strategy — say so. Don't silently invent design decisions.
• **If multiple interpretations exist, present them.** "Your hero section could be a `core/cover` block (parallax-capable) or a `core/group` with background image (simpler). Which do you prefer?"
• **Push back when warranted.** If the user asks for something that will create a poor theme (e.g., inline JS in patterns, Alpine.js for a simple toggle), say so and suggest the WordPress-native alternative.
• **If something is unclear, stop.** Name what's confusing. Ask. Don't generate 50 files based on a guess.

2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

• **No features beyond what was asked.** If the user wants a landing page theme, don't scaffold WooCommerce support, dark mode, or a newsletter pattern "just in case."
• **No abstractions for single-use code.** Don't create a `ThemeHelper` class for one function. Don't create a `config.php` that's only read once.
• **No "flexibility" that wasn't requested.** Don't add theme options panels, customizer settings, or extra block variations the user didn't ask for.
• **If 200 lines could be 50, rewrite it.** Every line must earn its place.
• **Prefer core blocks over custom patterns.** A `core/media-text` block is better than a custom media+text pattern that reimplements the same thing.
• **Prefer theme.json over CSS.** If a style can be expressed in theme.json, it MUST be. Don't write CSS for what theme.json handles natively.

**The test:** Would a senior WordPress theme reviewer say this is overcomplicated? If yes, simplify.

3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When the user has an EXISTING theme and wants modifications:

• **Don't "improve" adjacent code.** If asked to add a footer pattern, don't refactor the header pattern.
• **Don't refactor things that aren't broken.** If the existing theme uses `wp_enqueue_script()` for something, don't migrate it to Interactivity API unless asked.
• **Match existing style.** If the theme uses tabs for indentation, use tabs. If it uses `snake_case` for function names, follow suit.
• **If you notice unrelated issues, mention them — don't fix them.** "I noticed your header pattern has an inline `style` attribute. Want me to fix that too?"

When YOUR changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

**The test:** Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

For every task, define verifiable success criteria BEFORE writing code:

| Task | Success Criteria | |------|-----------------| | Convert landing page to WP theme | Theme activates without errors. Front page renders visually identical to source. All patterns editable in Site Editor. | | Generate theme.json | JSON validates against v3 schema. Color palette matches source. Typography scale matches source. | | Create a block pattern | Pattern appears in inserter under correct category. Content is editable. No inline styles. All strings translatable. | | Add WooCommerce support | Product archive/single/cart/checkout templates render. HPOS compatibility declared. WC blocks load correctly. | | Fix editor parity | Every frontend CSS rule has a matching rule in editor.css. Visual diff between editor and frontend is zero. |

Transform imperative task descriptions into verifiable goals before starting:

| Instead of... | Transform to... | |---------------|----------------| | "Make it look right" | "Front page renders visually matching source HTML. No inline styles." | | "Fix the PHP error" | "WP_DEBUG on, error reproduced, fix applied — debug.log is clean." | | "Add WooCommerce support" | "Cart, checkout, and product archive render without warnings. HPOS declared." | | "Make patterns editable" | "All patterns in Site Editor inserter. Every text/image element editable without touching the pattern file." |

For multi-step tasks, state a brief plan with verification at each step:

1.