html-ingest
Use when an HTML file, a URL or a published page has to become kivo-creator section specs - rendering it at 390 and 1440 px with the project's own Playwright, splitting it into sections, recording tex
SKILL.mdplugins/kivo-creator/skills/html-ingest/SKILL.md
GitHubHTML ingest
Turn a page into neutral section specs. The script does the rendering and the measuring; you review the split and fix it before anything is matched.
When to use
- "Convert this page / this HTML / this URL into our blocks", "migrate this landing page".
- A
/creatorrun whose source is a.htmlfile or anhttp(s)URL. - Not for Figma links (
figma-ingest), not for choosing blocks (section-matching).
Inputs required
- The source: a local
.htmlfile or anhttp(s)URL that the machine can reach. - The target project root, with
.roots-stack.json(kivo-wise/roots-detect --write) or the kivo-wise detector JSON. - Playwright in the project:
node_modules/playwrightor@playwright/test, with Chromium installed (npx playwright install chromium). Run the script where the project's own end-to-end tests run Playwright (usually the host); it is a read-only browser run, not a WordPress, Composer or PHP command. - The kivo-creator plugin root: the folder that holds
skills/,scripts/andschemas/(two levels above this skill's folder).
Procedure
From the project root run:
node <kivo-creator>/scripts/ingest-html.mjs --source=<file.html | https://...> --project=.Exit 3 means Playwright is missing in the project: show the printed install hint and stop. Never install it without asking. When the page already marks its sections (for example
main > sectionor[data-section]), add--selector=<css>: each matching element becomes one section and the heuristic below is skipped.Read the printed list of sections (
id,kind,chrome). The split follows these rules (seescripts/lib/segment.mjs):- content root is
<main>, else the body after unwrapping single wrappers; header,footerandnavoutside<main>arechrome(kept, never matched);- sections are the visible children of the root; pieces shorter than 80 px are merged into the previous section;
kindandlayoutare inferred; slot values and computed styles are exact.
- content root is
Open every spec in
.creator/<run>/specs/and compare it with the reference images inrefs/. Fix by editing the JSON, never by guessing:- two designs merged into one section: split the slots into two specs (new
id,order, samesource.refplus a note); - a wrapper picked as one section: move its children into separate specs;
- a wrong
kind: change it and add a note saying why; - a value you cannot see in the source: delete the slot. Never invent copy, colours or sizes.
- two designs merged into one section: split the slots into two specs (new
Validate:
node <kivo-creator>/scripts/validate-spec.mjs .creator/<run>/specs.Hand over to
section-matchingwith the run folder.
Verification
validate-spec.mjsprintsokfor every spec.- Every non-chrome spec has
refsfor 390 and 1440 (unless the element is hidden at one width; note it). - The number of non-chrome specs equals the number of sections a person sees on the page.
Failure modes
| Symptom | Cause | Fix |
|---|---|---|
| Exit 3 and an install hint | Playwright not installed in the project | Ask the person; install it as a dev dependency with their package manager and npx playwright install chromium |
| Whole page is one section | No <main> and several wrappers with more than one child |
Run again with --selector=<css> for the section container, or split the spec by hand (Procedure step 3) |
| Missing section that appears after scrolling | Lazy content not rendered at networkidle |
Ask for a static export of the page, or remove the lazy loading in a local copy before ingesting |
refs missing for 390 |
The section is hidden on mobile | Keep the spec; note it; verify only checks widths that have references |
| Wrong text in a slot (cookie banner, overlay) | The overlay is part of <body> |
Delete the overlay's spec or slots; note the decision |
Escalation
Stop and ask when the page needs a login, when the source is not reachable, or when the person disagrees with the section split and the right split is not visible in the references.