markup-assist

Validates HTML and CSS work with deterministic headless-Chromium gates that report selector-attributed defects.

22|1|Updated Mar 30, 2026
One-click install
npx skills add https://github.com/mizchi/vlmkit --skill markup-assist-mizchi
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: markup-assist
Source: https://github.com/mizchi/vlmkit/tree/main/.apm/skills/vlmkit/workflows/markup-assist
Command: npx skills add https://github.com/mizchi/vlmkit --skill markup-assist-mizchi

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @mizchi/vlmkit, playwright.

What problem does it solve? After writing or editing markup, it is hard to know whether the page is actually correct without manually eyeballing screenshots. This Skill runs deterministic verification gates in headless Chromium that measure the DOM and pixels directly, then print a machine-parsable kickback listing each defect with its selector and measured value, so you fix exactly what is named and re-run until clean. ## Core Features & Use Cases - Broken-page detection: vlmkit check integrity scans three viewports for JS errors, empty renders, failed resources, text collision/clipping, overflow, occlusion, and unstyled pages — no API key or reference design required. - Copy, layout, and behavior gates: verify exact copy against a manifest, structural contracts, responsive breakpoint sweeps, scroll behavior, keyboard operability, ARIA state transitions, and drag-and-drop wiring. - Design-target verification: compare an implementation against a target screenshot with verify markup, list missing or misordered components with build page, and converge single component crops. - Use Case: You just built a landing page from a brief. Run npx vlmkit check integrity page.html, fix the reported [page-overflow-x] and [text-collision] findings, then run the copy, scroll, handlers, and interactions gates until every one reports clean. ## Quick Start Ask the agent to verify the HTML page you just edited by running the vlmkit integrity, copy, scroll, handlers, and interactions gates and fixing every reported defect until all gates pass.

Frequently Asked Questions about markup-assist

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check an HTML page for visual defects without a design reference?

Run `npx vlmkit check integrity page.html` to scan three viewports for JS errors, empty renders, failed resources, text collision or clipping, overflow, occlusion, and unstyled pages. It prints a kickback listing each defect with its selector and measured value, and exits 1 on any suspect.

How to verify a webpage matches a target design screenshot?

Use `vlmkit verify markup attempt.html --target target.png` for a single verdict with a full kickback, or `vlmkit build page target.png attempt.html` to list missing, extra, or misordered components. For high-density exports, normalize the mock first with `vlmkit scan mock [email protected]`.

Does vlmkit require an API key for visual checks?

No. The core gates — integrity, copy, layout, breakpoints, scroll, handlers, interactions, and verify markup — are fully deterministic and key-free. API keys (OpenRouter, Gemini, or Anthropic) are only needed for features marked [key], such as `heal markup` and `check copy --vlm`.

Can I test keyboard accessibility and drag-and-drop behavior automatically?

Yes. `vlmkit check interactions page.html` verifies everything is keyboard-operable and that ARIA states transition, while `vlmkit scan handlers page.html --probe-drag` detects drag-and-drop that looks wired but is not, such as dragover without preventDefault.

Why does the copy gate fail when text is present in the HTML?

The copy gate matches only visibly rendered text. Copy hidden via font-size:0, opacity:0, off-screen positioning, clipping, or sr-only classes is reported as `copy-invisible` with a reason class. The requester must explicitly pass `--allow-invisible <class>` to accept hidden copy.

What should I do when a vlmkit gate keeps failing after fixes?

After three honest fix attempts on the same finding, stop and report the finding, your attempts, and your best hypothesis rather than applying a workaround. If the tool itself fails to run, report the error verbatim instead of substituting hand-rolled screenshot scripts.