Markup Decompose

markup-decompose

A whole screen is not one problem, it is N component problems plus a composition problem. This skill decides that split and routes each piece; it does not contain a build loop of its own.

The split is worth doing before writing markup for a measured reason, not an aesthetic one: once a component is a story with its own baseline, checking it costs a component-sized image instead of a page-sized one, and editing it stops reporting its neighbours as changed. See the measurement for the figures and their limits.

Route first

Phase 0 — Outline the reference

Get measured facts before deciding anything. Skip whatever the task did not supply.

vlmkit contract introspect <html-or-url> --out ui.contract.json   # landmarks, composition, viewports
vlmkit scan component target.png                                  # component bboxes + crops
vlmkit check palette target.png                                   # dominant colours
vlmkit scan breakpoints <html-or-url>                             # declared media queries

contract introspect gives the landmark/composition tree and viewports, so media queries are covered by the outline.

Two things the outline will not give you, so plan for them explicitly:

• Keyframes. The UI Contract IR has no field for animation. Motion has to come from the task's own brief, or from your reading of the reference — it cannot be extracted. dynamic-markup assumes a written brief for this reason. If the reference is a live URL you can at least read the declared animations out of its CSS by hand; if it is a screenshot, motion is unknowable from it and you should say so rather than invent easing.
• Component identity. scan component finds visual blocks, not the component boundaries a codebase would want. A card and its neighbour may be one bbox; a toolbar's three children may be three. Treat its output as a proposal.

Phase 1 — Decide the split

This is the phase with no tool, and the one that determines everything downstream. Write the list of components explicitly before touching markup.

A good boundary:

• Renders standalone. If it needs three ancestors to look right, it is not a component yet — either widen it or make the wrapper the component.
• Has states worth naming (default / disabled / loading / empty). Those become separate stories, and a state you cannot name is a state you will not test.
• Appears more than once, or is something you expect to edit repeatedly. A once-used block you will never touch again does not earn a story.

Size matters, and it is measured (65 trials, three page shapes, three regression classes — the report):

• Small components get the full benefit: 267x fewer image tokens than a page diff, 6/79 expected changes missed against the page diff's 15/79, and no false positives.
• Large components get much less, and lose on precision. 40x on cost — still large — but the story arm missed 6 of 12 changes on a 1258x203 hero where the page diff missed 0. Splitting a large block into parts that render standalone is therefore a detection decision, not a tidiness one.
• Half of those misses are the threshold unit: a corner-radius change moves ~60 pixels, which is over 1.6% of a button and 0.02% of that hero, so the 0.5% default catches one and not the other. build gallery derives a per-story threshold from a pixel budget for exactly this; if you write thresholds by hand, do the same arithmetic instead of reusing one number.
• The other half no threshold can fix: a pale-palette shift moved 96% of the hero's pixels by ≤8/255 per channel, which the pixel comparator scores as 0% changed. diff html catches it through its computed-style diff; check story is a pixel instrument and has no equivalent.

So do not retire the page diff. Per-component stories are the cheap, precise instrument for small components; a page-level diff html still covers large blocks and sub-perceptual style drift. Keep both in the done conditions.

So prefer splitting a large block into its parts over keeping it whole, when the parts render standalone. Not for tidiness — for detection.

Phase 2 — Build each component

Route to auto-markup per component, smallest first. Its build component loop is construction: converge markup toward a target you do not yet match.

Composition is its own problem and comes after the parts exist — build page handles missing/extra/ordering/stacking. Do not converge composition against a page whose components are still wrong; you will fix the same pixels twice.

For behaviour, hand the component to dynamic-markup once its static form is converged.

Phase 3 — Freeze (the handoff)

This is the phase people skip, and it is what makes the rest durable. A component that converged once has no protection against the next edit unless its correct state is recorded.

build component and check story are different tools for different phases — construction versus maintenance. build gallery is the conversion between them: point it at the page that just converged and it derives the gallery, the story list, and a per-story threshold.

vlmkit build gallery dist/index.html --out .vlmkit/gallery

It captures each component's rendered markup plus the page's CSS, writes gallery.html (implementing window.mount / window.unmount) and stories.json, and prints the vlmkit.gates.json fragment and the check story commands to run. Then:

1. Read the candidate list before trusting it. Discovery groups by class, so it proposes; you decide. Each candidate carries its evidence (instance count, size, what it contains) and rejected ones say why. --selector .c-card (repeatable) overrides discovery entirely, --include-all keeps the rejects.
2. Open the gallery and check it renders what you expect. If it warns that a stylesheet could not be read, stop — a baseline that looks fine and is wrong is worse than no baseline.
3. Write baselines once each component is converged, not before, using the printed commands (they carry the derived --threshold).
4. Record the set in vlmkit.gates.json so CI runs it and the story ids stop drifting (baselines are keyed on the id as written).
5. Commit the baselines.

A converged component with no baseline is an undone task, not a finished one.

What the generated gallery is not

It captures markup, so the stories are frozen: props are accepted and ignored, and behaviour is not exercised. It answers "did my CSS or token edit change how this looks", which is the maintenance question. A component whose stories need to vary by prop, or whose states only exist at runtime, wants a hand-written gallery — component-vrt's assets/ has React / Vue / vanilla templates.

Phase 4 — Maintain

From here on every edit goes through component-vrt, not through a page diff. That is the payoff: the diff is component-sized, and changing one component does not make its neighbours report.

Done conditions

• The component list from Phase 1 is written down, with states named.
• Every component converged (auto-markup's goal status pass, or a stated plateau).
• Composition converged: no missing/extra, no ordering violations.
• Every component has a committed story baseline, and vlmkit check story <all> --gallery <url> exits 0.
• Behaviour verified where the task specified it (dynamic-markup's gates).
• Large components carry a derived --threshold, not the gate default (build gallery prints one per story).
• A page-level vlmkit diff html still runs. Measured: story baselines miss half the changes on a large component, and miss sub-perceptual style drift entirely. Story VRT narrows what the page diff has to catch; it does not replace it.

What this skill does not solve

Stated so you do not go looking:

• No keyframe extraction. Motion cannot be read out of a reference by any tool here; it comes from a brief or from you.
• No story generation from a contract. build gallery works from a rendered page, so it needs markup that already exists. There is no path from a UI Contract IR (or a screenshot) straight to story definitions — during construction, before any markup, Phase 3 has nothing to read.
• No prop or behaviour coverage in a generated gallery. See above; a hand-written gallery is the answer, and templates for one are in component-vrt's assets/.