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/coverblock (parallax-capable) or acore/groupwith 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
ThemeHelperclass for one function. Don't create aconfig.phpthat'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-textblock 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_casefor function names, follow suit. - If you notice unrelated issues, mention them — don't fix them. "I noticed your header pattern has an inline
styleattribute. 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. Audit source HTML → verify: component map produced, no ambiguity remaining
2. Generate theme.json → verify: JSON validates, all design tokens mapped
3. Create templates → verify: all pages have corresponding FSE templates
4. Register patterns → verify: patterns appear in inserter, content is editable
5. Enqueue assets → verify: no console errors, styles load correctly
6. Accessibility pass → verify: skip-link works, contrast ratios pass, ARIA attributes present
Strong success criteria let you work independently. Weak criteria ("make it look good") require constant clarification.
When to Use This Skill
Trigger this skill when the user wants to:
- Convert static HTML/CSS/JS into a WordPress theme
- Build a Full Site Editing (FSE) theme from scratch
- Scaffold theme.json, block patterns, or block templates
- Port an existing landing page, portfolio, or eCommerce site to WordPress
- Create a WooCommerce-compatible block theme
- Generate individual block patterns or templates from HTML snippets
Custom Slash Commands
| Command | Purpose | Reference File |
|---|---|---|
/convert-to-wp-theme | Full conversion of HTML/CSS/JS project to complete block theme | commands/convert-to-wp-theme.md |
/scaffold-wp-theme | Create empty block theme scaffold (no source conversion) | commands/scaffold-wp-theme.md |
/wp-pattern | Convert single HTML section into a registered block pattern | commands/wp-pattern.md |
/wp-theme-json | Generate theme.json from a design system / CSS custom properties | commands/wp-theme-json.md |
/wp-template | Convert single HTML page into FSE template | commands/wp-template.md |
/wp-block | Scaffold a custom block (block.json, edit.js, save.js/render.php, CSS) | commands/wp-block.md |
/wp-migrate | Migrate existing WP content (Classic Editor, ACF, widgets, CPTs, shortcodes) to block theme | commands/wp-migrate.md |
/wp-plugin-theme | Declare plugin dependencies and generate plugin-specific CSS / compatibility code | commands/wp-plugin-theme.md |
/wp-variation | Generate a style variation (styles/*.json) — dark mode, color palette swap, font swap | commands/wp-variation.md |
/wp-classic-to-fse | Convert an existing WordPress classic theme (PHP templates) to FSE block theme | commands/wp-classic-to-fse.md |
/wp-debug | Systematically debug WordPress block theme issues (white screen, editor errors, style regressions) | commands/wp-debug.md |
When the user types one of these commands, read the corresponding command file in commands/ and execute the workflow defined there.
Core Workflow
For ANY conversion request (whether triggered by slash command or natural la