html-componentize

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

1. 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.

2. 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>/
   

3. 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