html-componentize (Claude Code plugin)
Convert static HTML+CSS → React or Vue components deterministically, with
fidelity proven by render-and-pixel-diff.
The wedge no existing tool fills (see PLAN.md §8): HTML input · cascade-
preserving · reuses your existing components · verifies the result renders
identically. Builder.io/v0/Locofy are Figma-input, AI-probabilistic, unverified.
How it works
The model orchestrates; deterministic Node scripts do the heavy lifting.
One rule: restructure, never re-author (skills/html-componentize/references/principles.md).
Authored CSS, source text, and DOM are moved verbatim by scripts — computed
style is used only to verify, never to generate.
.claude-plugin/
plugin.json plugin manifest (current: v0.6.2)
marketplace.json so the repo is installable as a marketplace
commands/
componentize.md the /componentize slash command
skills/html-componentize/
SKILL.md orchestration playbook (the skill entrypoint)
scripts/ deterministic engine (Node, .mjs)
detect-project.mjs infer framework/lang/styling/routing+layout from the project → detected.json
parse-source.mjs HTML+CSS → source-map.json (incl. inline-SVG rawHTML + head font assets)
index-workspace.mjs existing+generated components (tag-sig + class vocab) → workspace-index.json
detect-boundaries.mjs classify layout|reuse|new-component|leaf; exact+fuzzy reuse match
extract-data.mjs instance tree-diff → props + verbatim data array
plan-files.mjs boundary tree → dir plan + layout/chrome + shared placement + write-mode + hoist plan
manifest.mjs record generated files (path+hash) so re-runs reconcile, not blind-overwrite
lint-deps.mjs flag page→page import coupling (a component that should be hoisted to common)
css-to-modules.mjs authored CSS → scoped *.module.css + classMap
verify-fidelity.mjs Playwright render (waits fonts, full page) + global/local/DOM diff gate + report.html
templates/{react,vue}/ canonical codegen idioms
references/ principles.md, interview.md
examples/ sample HTML + an existing-project for reuse demo
PLAN.md design, decisions, market research
Requirements
- Claude Code (the plugin runs inside it).
- Node.js ≥ 18 on PATH (the engine scripts are ESM
.mjs; developed on Node 24).
- git (for installing the plugin from GitHub).
- GitHub CLI
gh, authenticated — only because this repo is private.
Run gh auth status to confirm you're logged in to an account with access.
(If you later make the repo public, gh auth is no longer required to install.)
- ~150 MB disk for the one-time Playwright Chromium download (phase 5 only).
Skip it if you don't need fidelity verification.
Installation
There are two ways to use it: (A) install as a plugin (recommended — gives
you the /componentize command and auto-triggering), or (B) run from a local
clone (no install; you drive the scripts).
A. Install as a Claude Code plugin
-
Add this repo as a plugin marketplace (inside Claude Code):
/plugin marketplace add mzd-hseokkim/html-componentize
This reads .claude-plugin/marketplace.json from the repo. Because the repo
is private, Claude Code uses your gh credentials to clone it — make sure
gh auth status shows you're logged in first.
-
Install the plugin from that marketplace:
/plugin install html-componentize@html-componentize-marketplace
html-componentize = the plugin name (.claude-plugin/plugin.json → name)
html-componentize-marketplace = the marketplace name
(.claude-plugin/marketplace.json → name)
After this, /componentize appears in your command list and the skill can
auto-trigger from natural language. The plugin is cached under:
~/.claude/plugins/cache/html-componentize-marketplace/html-componentize/<version>/
-
Install the engine dependencies (one time per machine).
The deterministic engine needs npm packages (cheerio, postcss, playwright,
babel, …). On the first conversion, the skill runs this for you per
SKILL.md; you can also do it manually against the cached plugin:
cd ~/.claude/plugins/cache/html-componentize-marketplace/html-componentize/<version>/skills/html-componentize/scripts
npm install
npx playwright install chromium # only needed for phase-5 verification
npm install is per-plugin-version; the Chromium download is global, so it's
reused across projects and future plugin versions.
B. Run from a local clone (no plugin install)
git clone https://github.com/mzd-hseokkim/html-componentize
cd html-componentize/skills/html-componentize/scripts
npm install
npx playwright install chromium