html-to-block-theme

Build a WordPress block theme from a set of static HTML designs

End-to-end conversion of a directory of static Claude Design files (HTML + linked CSS + JS + assets) into a standards-driven WordPress block theme on a local Studio site. The output reproduces the designs as closely as possible using WordPress primitives — theme.json, templates, template parts, block styles, and page content an editor can change — not hand-written CSS. Custom behaviour comes from core features first, then from the A8C Special Projects blocks monorepo; the skill never creates a block inside a theme.

Work in phases and do not skip the blueprint. Plan the whole mapping first, get it on disk, then build view by view and refine each against the original in a real browser. The reference guides under ${CLAUDE_PLUGIN_ROOT}/skills/html-to-block-theme/references/ are the source of truth for every mapping, standards, and tooling decision — load the relevant one before acting in each phase.

The plugin's own directory is ${CLAUDE_PLUGIN_ROOT}. The reference guides are files you read, so nothing fills that path in for them: where one writes <plugin-root>, it means this directory. The shell does not have it as a variable.

Inputs

• Design directory (required) — absolute path to a folder of static .html files plus their linked .css, .js, image, and font assets. The user provides this.
• Or a live site to rebuild. When the source is a running site, load references/live-site-guide.md first: it says what to ask, how to mirror the pages into a design directory, and how to treat the original's defects. The mirror is then the design directory for the rest of the run.
• Design documents (optional) — DESIGN.md, decisions.md and views.md, as a design handoff leaves them, in the design directory or its parent. Phase 1, step 5 reads them.
• Project repository (optional) — a repository generated from a8cteam51/a8csp-project-template. When the Studio site's wp-content is a clone of one, the run is in template mode (detected in Preconditions): it builds into that repository's theme and features mu-plugin under the template's conventions, per references/project-template-guide.md.
• Studio site — path or registered name of the target Studio site. If the user named neither, list the sites (studio site list --format=json) and ask which one, unless there is exactly one. Never pick a site by the look of its name: the run changes the site it is given.
• Theme (optional) — the theme to build into, when the user names one. Otherwise the run makes a new theme, or in template mode uses the repository's (Preconditions step 10).