К основному содержанию
скилл CX Codex

visual-review — скилл для Claude Code: скриншоты и пиксельный диф

Скилл visual-review для Claude Code доказывает, что пересборка на Astro совпадает с живым сайтом: снимает полноэкранные скриншоты обеих сторон и считает пиксельный диф.

MIT ★ 137 обновлён 2026-10-31

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add ethanplusai/astro-conversion-kit
/plugin install astro-conversion@astro-conversion-kit
Открыть на GitHub

Что делает visual-review

Скилл снимает полноэкранные скриншоты каждого маршрута с живого сайта и с новой сборки на одной ширине. Анимации замораживаются, скрытое через scroll-reveal показывается принудительно, lazy-картинки подгружаются прокруткой до низа и обратно. Куки-баннер с кнопкой accept, agree, got it или ok закрывается, запросы к аналитике и чатам блокируются, поэтому просмотр не попадает в отчёты сайта; --allow-analytics их возвращает.

review:diff сравнивает пары через pixelmatch и пропускает пару при 0.5% различающихся пикселей или меньше. review:styles сверяет вычисленные стили h1–h4, p, a, button и полей формы: длины проходят с допуском 1 px, цвета и шрифты должны совпадать точно. review:sheet собирает контактный лист, review:check перечитывает diff.json и styles.json и печатает худшую пару.

В сайте от convert-site скрипты лежат в scripts/review/ и запускаются как npm run review:<name> -- <options>. Вне его нужен node <skill-dir>/scripts/<name>.mjs, запуск идёт из папки с capture/ и review/. Каждый шаг — отдельная команда: код 1 у диффа ожидаем, пока различия остаются, а код 3 у review:shoot значит, что сайт блокирует запросы; снимок повторяют с бо́льшим --delay. Порог в docs/visual-overrides.json не больше 2% на маршрут.

Какие задачи решает

  • сверить пересборку шаблона с живой страницей на одной ширине
  • поймать разъехавшуюся типографику и отступы до релиза
  • собрать контактный лист из пар живого, нового и дифа
  • записать послабление порога в docs/visual-overrides.json с причиной
  • отличить реальную разницу от сдвига в 1 px

Примеры запросов агенту

  • Сними скриншоты живого сайта и новой сборки для маршрута /about и покажи диф
  • Сравни стили h1 и кнопок на новой странице с живой
  • Собери контактный лист по всем шаблонам

Как установить visual-review

1Через маркетплейс плагинов

/plugin marketplace add ethanplusai/astro-conversion-kit
/plugin install astro-conversion@astro-conversion-kit

Команда ставит плагин astro-conversion целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add ethanplusai/astro-conversion-kit --skill visual-review -a claude-code

3Вручную: положить файлы

~/.claude/skills/visual-review/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/visual-review/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о visual-review

Как установить visual-review в Claude Code?

Через маркетплейс: /plugin marketplace add ethanplusai/astro-conversion-kit, затем /plugin install astro-conversion@astro-conversion-kit.

Что делает visual-review?

Снимает полноэкранные скриншоты живого сайта и пересборки, считает пиксельный диф, сверяет вычисленные стили и складывает пары в контактный лист.

Что нужно для работы visual-review?

В проекте от convert-site скрипты лежат в scripts/review/ и идут через npm run review:<name> -- <options>. Вне такого сайта нужен node и запуск node <skill-dir>/scripts/<name>.mjs из папки с capture/ и review/.

Исходный текст

SKILL.md · MIT
---
name: visual-review
description: Prove an Astro rebuild looks like the live site it replaces — full-page screenshots of both sides with motion frozen, a pixel diff with a 0.5 % pass line, a computed-style comparison of typography, colour and spacing, and one contact sheet to look at every pair. Use after a template is built, before calling a conversion page done, when someone asks whether the new site matches the old one, or when a diff or style row fails and needs fixing.
---

# visual-review

Screenshot the live site and the new build at the same widths, measure every difference, look at
every pair yourself, fix, and repeat until every template passes. Then do it again for every page.

## The golden rule

**The diff decides, your eyes explain.** A pair passes only when `review:diff` says it passes and
`review:styles` has no failing row for it. Looking at a screenshot and finding it "close enough" is
never a pass. Four more that follow from it:

1. **Write down every visible difference before you change code.** Per pair, in words, from the
   contact sheet. Fixing what you noticed first and skipping the rest is how a page ships wrong.
2. **Parity, not better.** A deliberate improvement (a fixed typo, a tidier spacing, a sharper
   image) never goes into the default build. It goes into `proposals.json`.
3. **A looser threshold needs a decision.** Per-route overrides live in the committed file
   `docs/visual-overrides.json`, each `{ "id": "<decision id>", "threshold": n, "reason": "..." }`
   with `n` at most 2 (%). The decision id, threshold and reason are recorded on the diff row.
4. **A failed or missing shot is a fail, not a skip.** A route that did not load, a screenshot
   present on one side only, or an unreadable PNG fails its row.

## What the scripts do

A site made by `convert-site` carries copies of the scripts in `scripts/review/`. Every command
below runs from the site root as `npm run review:<name> -- <options>`. Outside a converted site,
run `node <skill-dir>/scripts/<name>.mjs <options>` from the folder that holds `capture/` and
`review/`. Every script prints `--help`; run it rather than reading the source.

| Script | Does | Exit |
|---|---|---|
| `review:shoot` | Full-page Chromium screenshots per route and width, plus `manifest.json` | 0 all shot, 1 a route failed, 2 usage, 3 stopped on blocks |
| `review:diff` | Pixel diff of two screenshot folders, diff images plus `diff.json` | 0 all pass, 1 any fail, 2 usage |
| `review:styles` | Computed styles of sampled selectors on both origins, `styles.json` | 0 all match, 1 a row fails, 2 usage or environment |
| `review:sheet` | The contact sheet: an index of every route plus one HTML page per route with live, new and diff side by side | 0 written, 2 usage or environment |
| `review:check` | Re-reads `review/diff/diff.json`, `review/diff-all/diff.json` (when present) and `review/styles.json`; prints the worst failing pair | 0 every row passes, 1 a row fails or a result is missing, 2 usage |

Exit 1 from diff or styles is expected while differences remain: carry on to the sheet, and run
each step as its own command rather than chaining them with `&&`. Exit 3 from shoot means the
site is blocking requests: wait, then rerun with a longer `--delay`; never retry in a tight loop.

What makes the screenshots comparable, on both sides alike: animations and transitions are
frozen and scroll-reveal content is forced visible; endless GSAP loops (`repeat: -1`, JavaScript
motion the freeze cannot stop) are put back to their start and paused; lazy images are made
eager and loaded by scrolling to the bottom and back (capped at 60 viewports or 30 s), except
`sizes="auto"` ones, which stay lazy so they pick the same `srcset` file every time; the shot
waits only for images the page requested (a hidden slide's lazy image does not hold it) and
for each of them to be decoded, so none paints blank; web fonts are awaited; a cookie banner whose
button says accept, agree, got it or ok is closed and reported as `bannerClosed`. Requests to
analytics, tag, pixel and chat hosts (Google Analytics and Tag Manager, Meta pixel, Hotjar,
Clarity, HubSpot tracking, Intercom, Drift, LinkedIn, TikTok, Pinterest, Segment, Mixpanel,
Plausible, Fathom, Matomo cloud, Crisp, Tawk, Zendesk) are blocked in `review:shoot` and
`review:styles`, so a review run never counts as a visit in the site's reports and a late chat
bubble never lands in a shot; `--allow-analytics` lets them load. `--block-hosts <host,...>`
(a comma list; each host's subdomains included) blocks more hosts for that run, with or without
`--allow-analytics`, in `review:shoot`, `review:styles` and `css-coverage.mjs`. Use it for a
consent manager that behaves differently off the live host: Osano (`cmp.osano.com`), loaded on
`localhost` or a preview host, turned the theme's scripts off, so the build did not draw as
live did. `--block-hosts cmp.osano.com` on every run lets the
scripts run as on live; record it as a decision row, and pass the same list when the live
shots are taken. A screenshot
more than 2 px off the page's `scrollHeight` is flagged `heightMismatch`.

What the diff measures: pixelmatch at threshold 0.1 with anti-aliasing ignored. A pair passes at
**0.5 % differing pixels or fewer** and equal widths. When the heights differ, every row the
taller image has and the shorter one lacks counts as differing, so a missing footer fails; the
row says `heightMismatch` and the difference is counted, never ignored. When the aligned
comparison fails, the new image is also tried shifted by up to **1 px** in each direction, so a
sub-pixel rounding shift is not reported; the row records the `offset` used and the aligned
`percentUnaligned`. Wider shifts are never searched: 2 px off is a real difference.

What the styles comparison measures: on the first match of `h1`–`h4`, `p`, `a`, `button`,
`.btn`, `[class*=button]`, `nav a`, form fields, `blockquote`, `li`, `header` and `footer`, it
compares first font family, size, weight, line height, letter spacing, colour, background,
text transform, vertical margins and all four paddings. Lengths pass within 1 px; colours and
families must match exactly. A selector present on one side only fails with a `present` row. A
route that is not 2xx on either side fails with one `status` row.

## Where things live

    capture/screens/live/     live screenshots, taken once at capture time (the capture step
                              runs shoot.mjs against the live site); never re-shot to
                              get a match (rollout adds capture/screens/live-all/ once)
    review/new/               new screenshots, from the dev or preview server
    review/diff/              diff images and diff.json
    review/styles.json        style rows
    review/index.html         the contact sheet's index; review/index-pages/ holds a page per route
    docs/visual-overrides.json
                              per-route thresholds, each with its decision id and reason
                              (optional; committed, so every looser threshold is reviewed)

`capture/` holds the live evidence; `review/` is regenerable and not committed. The contact sheet
links each image by its relative path instead of embedding it, so a site with hundreds of pages
gives an index and many small pages rather than one file too large to write: open it where the
screenshot folders are, or copy them with it.

## The loop

Read `references/review-procedure.md` before the first run. In short:

1. **Serve the new site.** `npm run build`, then serve the build with `npm run review:serve`
   (it applies `vercel.json` like staging does, so media and scripts rewritten to another origin
   load) and use that origin, e.g. `http://localhost:4321`, for every `review:*` step.
   `npm run preview` is only for sites whose media is in the repo; `npm run dev` while iterating.
2. **Shoot new** with the same `--routes` and widths the live shots used, so folder names match:

       npm run review:shoot -- --base http://localhost:4321 --routes capture/templates.json --widths 390,768,1440 --out review/new --delay 0

3. **Diff** (it reads `docs/visual-overrides.json` when that file exists):

       npm run review:diff -- --a capture/screens/live --b review/new --out review/diff

4. **Styles.** It loads the live site one page at a time, 500 ms apart by default. It defaults to 390
   and 1440, so pass the widths to cover 768 too:

       npm run review:styles -- --live https://www.example.com --new http://localhost:4321 --routes capture/templates.json --widths 390,768,1440 --out review/styles.json

5. **Sheet:**

       npm run review:sheet -- --live capture/screens/live --new review/new --diff review/diff/diff.json --styles review/styles.json --out review/index.html

6. **Look.** Open `review/index.html` and each route page it links. For every pair, write down every visible difference you
   can see, failing or not, before you touch any code. Then read `diff.json` for `offset`,
   `percentUnaligned` and `reason`, and both `manifest.json` files for `bannerClosed`,
   `heightMismatch` and `error`: the sheet does not show those.
7. **Fix** from `capture/` (markup, CSS, media), one difference at a time. Then go back to 2.
8. **Roll out** only when every template pair passes at every width: shoot every page
   (`--full`) at 390 and 1440, diff, sheet, look, fix, repeat until every page passes. The
   exact commands are in the reference, step 7.
9. **Check** before the pull request: `npm run review:check` exits 0 only when every template
   pair, every page pair and every style row passes.

## If your agent has a browser of its own

Use it to open the contact sheet and to look at a live page and its new page side by side, at
the same width, when a diff image does not explain itself. Never use it instead of the diff: a
page you looked at and liked has not passed anything.

## Present the result

1. **Pass or fail, per template, then per page.** Lead with what still fails and why.
2. **Every override**, with its threshold and reason, read out. An override is a decision a
   person should see.
3. **Every banner closed and every `heightMismatch`**, with the route: each is a place the
   screenshot may not show what a visitor sees.
4. **Proposals**: what you saw that could be better and put in `proposals.json` instead (the
   site's `AGENTS.md`, "Exceptions and proposals", says what an entry holds and how it ships).
5. **Not covered, verbatim**: the list at the end of `references/review-procedure.md`, every
   line, unedited. None of it was compared, an open mobile menu included. Not covered is never
   a pass.

## References

| File | Covers |
|---|---|
| `references/review-procedure.md` | The full loop, writing down differences, fixing, overrides, rollout, proposals |

© ethanplusai · MIT · ethanplusai/astro-conversion-kit

Похожие скиллы

Все скиллы по теме «Тесты и QA» →
triaging-visual-review-runs PostHog Скилл triaging-visual-review-runs разбирает падения визуальных проверок PostHog Visual Review в PR и помогает отделить реальные регрессии скриншотов от флакующих тестов Storybook и Playwright. CX Codex +1 398установок visual-testing kindlmann Скилл visual-testing для визуального регрессионного тестирования: сравнивает скриншоты с эталонами и ловит различия на уровне пикселей, которые пропускают функциональные тесты. CX Codex +1 1 500установок visual-regression-testing aj-geddes Скилл visual-regression-testing ловит случайные визуальные изменения интерфейса: снимает скриншоты компонентов и страниц и сравнивает их между версиями. CX Codex +1 741установок visual-regression-tester patricio0312rev Скилл visual-regression-tester настраивает визуальное регрессионное тестирование: снимает скриншоты, сравнивает их с базовыми и ловит случайные изменения интерфейса. CX Codex +1 351установок visual-regression rohitg00 Плагин visual-regression проводит визуальное регрессионное тестирование интерфейса через сравнение скриншотов. Помогает отслеживать непреднамеренные сдвиги вёрстки при изменении кода. ★ 2 858звёзд репо visual-testing-advanced proffesor-for-testing Скилл visual-testing-advanced настраивает продвинутое визуальное регрессионное тестирование интерфейса, сравнение скриншотов по пикселям и адаптивную проверку верстки. CX Codex +1 163установок

Из того же набора9

astro-conversion Плагин astro-conversion для Claude Code переносит WordPress или другой сайт, доступный по HTTP, в статический Astro. Он собирает сайт и проверяет маршруты, SEO-данные и визуальное сходство. ★ 137звёзд репо suggest-improvements Скилл suggest-improvements для Claude Code формирует отчёт об ошибках и недочётах конвертированного сайта по восьми направлениям. Запускается перед открытием pull request и сам ничего не правит. CX Codex +1 ★ 137звёзд репо launch-audit Скилл launch-audit для Claude Code проверяет сайт перед запуском или после него. Он также включается при переезде на новый домен и запросе на QA сайта. CX Codex +1 ★ 137звёзд репо post-launch Скилл post-launch для Claude Code проверяет сайт сразу после переезда DNS и потом тридцать дней подряд. Включается на вопрос, живой ли сайт после смены домена. CX Codex +1 ★ 137звёзд репо pre-launch Скилл pre-launch для Claude Code проверяет сайт перед публикацией и блокирует запуск при проваленных проверках. Запускается перед релизом, переносом DNS или заменой существующего сайта. CX Codex +1 ★ 137звёзд репо convert-site Скилл convert-site для Claude Code переносит сайт в статический Astro, сохраняя его URL, контент и оформление. Запускается по просьбе перенести, пересобрать или клонировать сайт. CX Codex +1 ★ 137звёзд репо parity-gates Скилл parity-gates для Claude Code замораживает состояние сайта в baseline/ и проверяет, что новая Astro-сборка совпадает с ним. Запускается при сверке редиректов и тестировании деплоя. CX Codex +1 ★ 137звёзд репо capture-site Скилл capture-site для Claude Code сохраняет живой сайт в папку capture/ для последующей проверки пересборки. Запускается перед переносом сайта или по просьбе сделать его снимок, инвентаризацию либо повторить прерванный сбор. CX Codex +1 ★ 137звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой