pixel-gate

Указал макет, указал сайт — получил отчёт. Автоматическая сверка «макет Figma ↔ живой сайт», пиксель в пиксель.

Дизайнер отдал макет, разработчики «сделали как в макете» — а глазами всё проверять долго и ненадёжно. pixel-gate сам сопоставляет блоки макета с секциями сайта, сравнивает их попиксельно и выдаёт наглядный отчёт: какой блок совпадает, какой разъехался и где именно (подсветка красным).

Automated Figma-vs-live-site comparison for designers. English docs: README.en.md.

Быстрый старт

Нужен только Node.js (LTS, кнопка «скачать» на сайте).

1. В Figma выделите фрейм страницы → правый клик → Copy link to selection.
2. В терминале:

npx pixel-gate "<ссылка-на-фрейм>" "https://адрес-сайта/"

3. Отчёт откроется в браузере сам.

При первом запуске pixel-gate спросит токен Figma (подскажет, где взять — один раз, дальше запомнит) и при необходимости скачает браузер для снимков. Можно запустить и просто npx pixel-gate — мастер спросит всё сам.

Что делает

1. Читает макет — блоки фрейма, их рендеры, шрифты/размеры/цвета и все комментарии дизайнера, автоматически привязанные к блокам (комментарии — половина спеки: поведение шторок, ховеры, уточнения).
2. Фотографирует сайт — сам находит секции страницы и сопоставляет их с блоками макета (по текстам и порядку следования), 1:1 по масштабу.
3. Сравнивает попиксельно — и собирает один HTML-файл отчёта: карточки блоков, худшие сверху, тройки «макет | сайт | расхождения красным», комментарии дизайнера в карточке. Картинки встроены — отчёт можно переслать разработчику одним файлом.

Как читать отчёт

• совпадает (<10%) — остаток на сглаживании шрифтов, всё хорошо;
• проверить (10–25%) — открыть картинку «Расхождения», возможны точечные проблемы;
• разъехался (>25%) — почти наверняка структурная проблема;
• медиа — глазами — внутри карта/видео/фото, дифф всегда высокий, сравнивать по картинке;
• нет пары — блок из макета не нашёлся на сайте (или наоборот — секции сайта без пары перечислены в конце отчёта);
• «блок отличается по высоте на N px» — на сайте лишний или недостающий контент.

Рабочий цикл

1. npx pixel-gate "<ссылка>" "<сайт>" — свежий отчёт.
2. Худший блок → правка вёрстки (точные значения — в «паспорте блока» внутри карточки, указания дизайнера — в комментариях там же).
3. Перепрогон той же командой: макет не менялся — возьмётся из кеша, дифф упал — следующий блок.

Флаги и тонкая настройка

npx pixel-gate                                  мастер (спросит всё сам)
npx pixel-gate <ссылка-на-фрейм> <адрес-сайта>  без вопросов
  --fresh         заново скачать макет из Figma (игнорировать кеш)
  --out <файл>    куда сохранить отчёт (по умолчанию pixel-gate-report.html)
  --no-open       не открывать отчёт автоматически
  --viewport <px> ширина сравнения (по умолчанию — ширина фрейма)

• Сайт за HTTP Basic: SITE_HTTP_USER=… SITE_HTTP_PASSWORD=… npx pixel-gate …
• Токен можно передать через env FIGMA_API_TOKEN (для CI).
• Продвинутое (обычно не нужно): положите pixelgate.config.json рядом с местом запуска — см. pixelgate.config.example.json: скрытие своих виджетов (hideSelectors), пауза загрузки (settleMs), допуск диффа (tolerance) и ручные пары «блок → селектор» (pins), если авто-сопоставление ошиблось на конкретном блоке.

Служебные файлы (кеш макета, рендеры) живут в ~/.pixel-gate/ — в папке проекта остаётся только отчёт.

Как это работает внутри

bin/pixel-gate.js — CLI и мастер; src/figma.js — Figma API (фрейм, рендеры, комментарии, кеш по версии файла); src/site.js — Playwright: секции страницы, скриншоты, пиксель-дифф на canvas (без нативных зависимостей); src/match.js — авто-сопоставление блоков и секций (текст-якоря + порядок следования, каждой паре — уверенность); src/report.js — HTML-отчёт. Куда движемся: docs/product-vision.md.

Лицензия

MIT