jackson2w/claude-code-skills / cdp-layout-verification
cdp-layout-verification
FlaggedThis skill should be used when the user asks to "verify this looks right", "check the spacing/alignment/margin", "is this centered", "double check the CSS", "confirm the layout matches", or after any CSS/layout change on a web project where a screenshot alone would only be an eyeball check. It should also be used proactively whenever reporting a CSS fix as "verified" or "confirmed" — a headless screenshot is not sufficient verification for precise spacing, alignment, or color claims; only direct DOM measurement is.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.9 KB |
| scripts/cdp-eval.mjs | script | 1.4 KB |
| scripts/cdp-screenshot.mjs | script | 1.4 KB |
SKILL.md
View on GitHub---
name: cdp-layout-verification
description: This skill should be used when the user asks to "verify this looks right", "check the spacing/alignment/margin", "is this centered", "double check the CSS", "confirm the layout matches", or after any CSS/layout change on a web project where a screenshot alone would only be an eyeball check. It should also be used proactively whenever reporting a CSS fix as "verified" or "confirmed" — a headless screenshot is not sufficient verification for precise spacing, alignment, or color claims; only direct DOM measurement is.
version: 0.1.0
---
# CDP Layout Verification
Verify CSS layout claims (spacing, alignment, color, margins) against the
real, live DOM of a running page, using the Chrome DevTools Protocol (CDP)
directly over a WebSocket — rather than eyeballing a screenshot.
## Why this exists
A headless screenshot can look "close enough" at a glance and lead to a
false "looks good" conclusion, even when the actual computed margin,
alignment, or color is wrong. Two concrete failures this skill prevents:
- A homepage line appeared centered in a screenshot at several widths, but
was actually offset ~111px left in the real DOM — only caught by measuring
`getBoundingClientRect()` against the live page, after two rounds of
screenshot-based "looks fine" were both wrong.
- Three summary lines were meant to have an identical 11px gap between each,
but a global `p + p { margin-top: ... }` rule silently added 30px to two
of the three transitions. The screenshot looked plausible; only measuring
each element's `top`/`bottom` in pixels revealed the inconsistency.
Screenshots are still useful for a final human-readable check, but treat
them as a supplement to measurement, never a replacement for it. When
reporting any layout fix as verified, prefer citing actual measured numbers
over "looks correct in the screenshot."
## Workflow
1. **Serve the built site.** Start (or reuse) a local server for the built
output — e.g. `npx wrangler pages dev _site --port <port>` for an
Eleventy/Pages project, or any static server for another stack.
2. **Launch headless Chrome with remote debugging**, sized to the
breakpoint being verified (mobile vs. desktop matters — a bug can be
present at one width and absent at another):
```bash
pkill -f "remote-debugging-port=<port>" 2>/dev/null
("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--headless=new --disable-gpu --remote-debugging-port=<port> \
--window-size=<W>,<H> "<url>" > /tmp/chrome-debug.log 2>&1 &)
sleep 3
```
Use a fresh, unused debugging port each time — do not reuse a port from
an earlier run in the same session without killing the prior process
first.
3. **Get the page's WebSocket URL:**
```bash
WS=$(curl -s http://localhost:<port>/json | python3 -c "
import json,sys
tabs = json.load(sys.stdin)
for t in tabs:
if t.get('type') == 'page':
print(t['webSocketDebuggerUrl'])
break
")
```
4. **Measure with `scripts/cdp-eval.mjs`.** Pass a JS expression that
queries the DOM and returns a plain value (string/number/object — must be
JSON-serializable, since it goes through `returnByValue`). Prefer
returning a single formatted string for multiple elements in one call
over separate calls per element, to keep round-trips low:
```bash
node scripts/cdp-eval.mjs "$WS" "
(function() {
function info(sel) {
var el = document.querySelector(sel);
if (!el) return sel + ': NOT FOUND';
var r = el.getBoundingClientRect();
var cs = getComputedStyle(el);
return sel + ': left=' + r.left.toFixed(1) + ' top=' + r.top.toFixed(1) +
' bottom=' + r.bottom.toFixed(1) + ' color=' + cs.color;
}
return [info('.thing-one'), info('.thing-two')].join('\\n');
})()
"
```
Compute gaps between elements as `nextEl.top - prevEl.bottom`, not by
reading a single margin value — margin collapsing between adjacent block
siblings means the visible gap is not always the sum of both elements'
declared margins (it is the *max* of the two, unless a rule prevents
collapsing). If a measured gap doesn't match the sum/expected value of
the CSS just written, look for another rule contributing to one side
(see Common Pitfalls below) before assuming the edit didn't apply.
5. **Screenshot the exact current state with `scripts/cdp-screenshot.mjs`**
when a visual (not just numeric) check is useful — e.g. after confirming
numbers are right, to also eyeball it, or after mutating the DOM live
(see below):
```bash
node scripts/cdp-screenshot.mjs "$WS" /path/to/output.png
```
6. **Mutate the DOM live to preview a change before committing to it.**
Because `cdp-eval.mjs` can run arbitrary JS, use it to toggle a class or
inline style, then screenshot the result — useful for showing a user
"before vs. after" of a CSS variant without touching the checked-in
template, or without a full rebuild/reload cycle:
```bash
node scripts/cdp-eval.mjs "$WS" "document.querySelector('.thing').classList.add('is-preview')"
node scripts/cdp-screenshot.mjs "$WS" /path/to/preview.png
```
7. **Clean up.** Always kill the headless Chrome process (and any local dev
server started just for this) when done:
```bash
pkill -f "remote-debugging-port=<port>" 2>/dev/null
```
## Common pitfalls this catches
- **A global sibling-combinator rule** (e.g. `p + p { margin-top: 30px }`)
silently applies to any two adjacent elements of that tag, including ones
added inside an unrelated component — the fix is an explicit
`margin-top: 0` override on the more specific selector, not just adding
the "correct" margin and assuming it wins.
- **Missing `margin-inline: auto` (or similar) on a new element** inside a
wider container that relies on a global `max-width` rule for its own
width — the element gets the width but not the centering, and sits
flush against one edge instead.
- **A gap that's larger or smaller than expected** almost always means
another CSS rule is also contributing — check `getComputedStyle` for
every margin/padding on both elements bordering the gap, not just the one
just edited.
- **Serving stale CSS.** If measurements don't match what the source CSS
says they should, diff the actual served/built file (e.g. `_site/**` or
`dist/**`) against source — a stale build or cached asset can look like a
CSS bug that isn't one.
- **A tap right after a synthetic swipe is ignored (2026-11-06, Abernathy gallery).** Headless
swipe tests need the CDP touch API (`Input.dispatchTouchEvent`), and Chromium's touch emulator
then ignores a tap landing within about 1 s of a swipe on the same element. That looks exactly
like a broken tap-to-advance handler but is a harness artifact. Space synthetic taps more than
1 s after any swipe, or confirm in a real browser, before calling the interaction broken.
## Requirements
- Node 22+ (for the built-in global `WebSocket` used by both scripts —
earlier versions need a `ws` package polyfill instead).
- A local Chrome/Chromium binary that supports `--headless=new`.
- `curl` and `python3` (or equivalent) for parsing the `/json` debugging
endpoint response.
## Hit-test links, not just measure them (2026-11-05, Abernathy)
A decorative element drawn over real links swallows their clicks. Screenshots look right, Lighthouse scores 100, and box measurements are all fine. On Abernathy, a giant outline footer wordmark sat over the footer's link row at ≥1024px, so every footer link was dead on desktop. Only a real click test revealed it. For every visible `a`, check that `document.elementFromPoint(centre)` is the link or inside it. Scroll each page to the bottom too, because footers are where big decorative type tends to overlap. Fix decorative layers with `pointer-events: none`. Reference script: `~/projects/sites/mockups/scripts/dev/hit-test.mjs`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |