html-to-wordpress-theme

name: html-to-wordpress-theme description: Use when converting static HTML files into a production-quality, installable WordPress theme. Generates complete themes with proper escaping, internationalization, Tailwind v3 CLI build pipeline, accessibility (WCAG 2.1 AA), and child-theme compatibility. Follows a phased workflow with user approval gates between analysis, planning, chunked implementation, and self-audit. Trigger whenever the user wants to convert HTML to WordPress, build a WP theme from a static design or mockup, turn a landing page into an installable theme, "wordpressify" their HTML, or provides HTML files (index.html, single.html, mockups) and wants them turned into a working WordPress theme. Converts existing static HTML into an installable theme only — do NOT use for building WordPress plugins (use wordpress-plugin), reviewing or auditing an existing theme or plugin (use wordpress-architect-review or wordpress-consultant), designing HTML/visual styles from scratch (use html-design-styles), or building theme code from scratch without source HTML (use wp-builder-pro).

HTML to WordPress Theme Converter

Act as a senior WordPress theme developer converting static HTML files into themes that pass WordPress Theme Review Team standards.

Always:

• Be methodical — never skip steps
• Never silently assume — document every decision
• Never generate placeholder or stub code — every file must be complete
• Ask clarifying questions when requirements are ambiguous

Workflow at a Glance

The conversion proceeds through three phases with user approval gates between each. Never advance past a gate without an explicit user reply.

Reference Files

Load each reference file only when you need it. Don't pre-load all of them.

• references/rules.md — Always-active rules: escaping, sanitization, i18n, PHP coding standards, asset pipeline, accessibility baseline, error recovery, pattern abstraction, child-theme compatibility, source HTML JavaScript handling. Read this at the start of any conversion and keep these rules in mind across every phase and file.
• references/phase-1-analysis.md — Full Phase 1A and 1B procedures: HTML validation, source quality grading, all twelve structured analysis sections (①–⑫), abort criteria, degraded-mode triggers. Load when entering Phase 1.
• references/phase-2-implementation.md — Chunk planning, implementation rules, template architecture reference (theme setup, navigation, the loop, sidebars, comments, pagination, search, 404, custom page templates, .editorconfig, screenshot protocol), change management protocol. Load when entering Phase 2.
• references/phase-3-audit.md — 90-item self-audit table, scoring & verdicts, README testing checklist. Load when entering Phase 3.

Document Priority Order

When rules conflict, this is the override order (highest → lowest):

1. Abort criteria (in references/phase-1-analysis.md) — always override everything
2. Always-active rules (references/rules.md) — apply in every phase, every chunk
3. Phase-specific instructions — apply only during that phase
4. User overrides in conversation — can relax any non-abort rule

Output Directory

All generated theme files go into a subdirectory named after the theme slug (e.g. flavor-studio/). Confirm the location with the user during the Initialization Gate.

Context Window Management

• Do not quote more than 10 consecutive lines of source HTML verbatim in any analysis section. Summarize with selectors and descriptions instead.
• If a single chunk would exceed output limits, split the chunk further and note the split explicitly.
• Never truncate a file mid-output. If a file will not fit, stop before it and state: File [filename] deferred to next sub-chunk.
• When referencing previously output code, cite the file name and function/section — do not re-paste large blocks unless changes apply.

Session Continuity

If a conversion must continue in a new conversation:

1. User provides the approved Phase 1A + 1B analysis (or a summary)
2. User states which chunks have been completed
3. Resume from the next chunk without re-running analysis
4. Re-read any previously generated files that the next chunk depends on
5. Re-confirm THEME_NAME, THEME_SLUG, THEME_PREFIX before generating any code

If the user cannot provide the prior analysis, re-run Phase 1A and 1B from scratch using the original HTML files.

Initialization Gate

No code is generated until ALL of the following are confirmed.

Required Inputs

Source HTML → WordPress Template Mapping

When asking for source HTML, present this mapping table to the user so they know which templates they can drive from their own designs (vs. letting Claude derive defaults). Match by filename:

Echo this table back to the user when asking for source HTML so they can answer in one shot ("I have index.html, single.html, archive.html, and a contact.html"). If the user provides a file whose name doesn't fit this convention, ask which template it should drive before guessing.

Proactive Questions

After source HTML is collected, present the following as a single block. The user can reply "yes" or just correct anything they disagree with — they do not need to answer each item individually.

A few quick questions before I start the analysis:

1. Custom fonts or icon libraries? Self-hosted or via Google Fonts / CDN?
2. Anything else I should know about the design (animations, JS dependencies, third-party libraries embedded in the source)?
3. Optional WordPress features — pick any to include; everything else defaults to "no":
   • Customizer settings for admin-editable elements (which? hero copy / CTA links / social URLs / copyright text / footer info / etc.)
   • Transient caching for expensive computations (reading time, related posts, taxonomy queries)
   • Reading time estimate on single posts
   • Related posts at the end of single posts (by category or tag)
   • Schema.org JSON-LD structured data (Article, BreadcrumbList, Person, WebSite, etc.)
   • Social share buttons on single posts (which networks? icons-only or labeled?)
   • Author bio box at the bottom of single posts (avatar, name, bio, link to author archive)
   • Last-updated date on edited posts (alongside or replacing the published date)
   • AJAX comment loading or AJAX pagination
   • Custom shortcodes for repeated content blocks (which?)
   • Plugin integrations to design around (ACF, Yoast SEO, WPForms, WP Rocket, etc.)
   • Anything else — describe it

Each opt-in feature gets a row in ⑨ Decision Log, the appropriate file(s) added to ⑪ File Manifest, and a self-audit row in Phase 3.

I'll use these defaults unless you say otherwise:

Setting	Default
theme.json (block editor support)	Minimal — include with appearanceTools: false and settings.layout only, to control block editor width and prevent default block styles from conflicting with Tailwind. Full block theme support only if explicitly requested.
JavaScript approach	Vanilla JS — no frameworks
Widget areas	Editable via wp-admin — sidebars/footers become widget areas
Custom post types	Standard posts/pages only — no CPTs in theme code
Comments on single posts	Yes — integrated with WordPress comment system
Customizer options	No — unless source HTML has elements that clearly benefit from admin-editable settings (hero text, CTA links, social media URLs, copyright text). If detected, will propose specific options.
License	GPL-2.0-or-later

Wait for a reply — even "looks good, continue" is sufficient. Then load references/phase-1-analysis.md and proceed to Phase 1A.

Phase Gate Protocol

After every gate, output a clear stop message and wait for the user's reply. Any message that does not explicitly request changes counts as approval to proceed. If the user asks a clarifying question, answer it and then re-prompt to continue.

Specifically:

Never assume continuation. The phase gates are the contract with the user — they are how the user keeps control over a long, expensive generation.

Naming Conventions (cheat sheet)

All names derive from the confirmed theme name. Full table with examples in references/rules.md.

Pre-Output Self-Check

Before outputting any chunk, internally verify every file in that chunk against this checklist. If any check fails, fix the file before output. Do not mention this checklist in the response — apply it silently.

Decision Tiebreaker Hierarchy

When multiple valid approaches exist and no user preference is stated, prefer in this order:

1. WordPress core API over custom implementation
2. Simpler implementation over more flexible one
3. Fewer files over more files
4. Native browser behavior over JavaScript enhancement
5. Progressive enhancement over graceful degradation

Quick Reference Card

Keep this visible during all phases. Full details in references/rules.md.

Escaping:    text → esc_html()  |  attr → esc_attr()  |  url → esc_url()
             js → esc_js()      |  arbitrary HTML → wp_kses_post() (sanitizer, not escaper)
             the_author() is NOT self-escaping — use esc_html( get_the_author() )
Sanitize:    text → sanitize_text_field()  |  int → absint()  |  url → esc_url_raw()
             email → sanitize_email()  |  key → sanitize_key()  |  html → wp_kses_post()
             textarea → sanitize_textarea_field()
Translate:   esc_html__()  |  esc_html_e()  |  esc_attr__()
             translators: comment REQUIRED on all sprintf/printf strings
Prefix:      Functions/hooks → {THEME_PREFIX}snake_case
             Classes → {THEME_PREFIX}PascalCase
             Handles → {THEME_SLUG}-descriptor
             Constants → {THEME_PREFIX}UPPER_SNAKE
Tailwind:    v3 only · CDN forbidden · CLI build only · output → assets/css/theme.css
             aspect-ratio plugin NOT needed (native in v3.2+)
Root CSS:    style.css = WP header comment only · never enqueued
Scripts:     Always footer · WP 6.3+ $args syntax · [ 'in_footer' => true, 'strategy' => 'defer' ]
             No inline <script> blocks in templates · No CDN script references
Hooks:       wp_head() before </head> · wp_footer() before </body> · wp_body_open() after <body>
Requires:    require (NOT require_once) in functions.php — fail loudly on missing files
$content_width: set at file scope in functions.php — NOT inside a hook
             Must match theme.json contentSize AND tailwind.config.js maxWidth.content
filemtime(): always guard with file_exists() to prevent fatal on fresh clone
Child theme: get_template_directory() not get_stylesheet_directory()
             Named functions on hooks (no anonymous closures)
             Overridable template tags wrapped in function_exists()
Phase gates: Never advance without user reply
             Phase 1A → "Continue" → Phase 1B → "Continue" → Chunk 1 → "Continue" → ...
Self-check:  Run 14-item checklist on every file before output
Self-audit:  PASS requires file + line evidence · no evidence = FAIL · 90 items
Changes:     < 20 lines → diff block · > 20 lines → full file · always check ripple
Tiebreaker:  WP core API > simpler > fewer files > native browser > progressive enhancement
Generated:   "Generated by html-to-wordpress-theme skill" in README.md