dsh-desktop-kit 0.0.0-stage → 1.0.0

package/skills/wow-design/references/visual-qa.md

@@ -0,0 +1,79 @@
+# Visual QA — петля «собрал → снял → раскритиковал → исправил»
+
+> Без скриншотов дизайн не считается проверенным. Глазами по PNG видно то, чего не видно в коде:
+> иерархию, воздух, ритм, «дёшево/дорого», поломки адаптива.
+
+## 1. Что нужно один раз
+- Node.js 18+ (на этой машине Node 24).
+- Chrome или Edge (Windows 11 — Edge есть всегда).
+- `playwright-core` + `axe-core` в `~/.dsh/skills/wow-design/assets/scripts/`:
+  ```
+  cd ~/.dsh/skills/wow-design/assets/scripts
+  npm install --no-audit --no-fund
+  ```
+  Если пакеты уже стоят в другом месте — можно указать `NODE_PATH` или запускать из той папки.
+- Скрипты ищут браузер так: `CDP_URL` → запущенный Chrome по CDP → установленный Playwright Chromium →
+  системный Edge/Chrome (`channel: msedge`/`chrome`). Обычно ничего настраивать не нужно.
+
+## 2. Скриншоты
+```bash
+# одна страница, все вьюпорты и темы
+node ~/.dsh/skills/wow-design/assets/scripts/capture.mjs path/to/page.html --name page --out screenshots
+
+# только desktop+mobile, светлая тема, full page
+node .../capture.mjs http://localhost:5173 --name app --viewports desktop,mobile --themes light
+
+# отдельный элемент (например, карточка)
+node .../capture.mjs page.html --name card --selector ".ticket-card" --themes light
+```
+Результат: `screenshots/page-desktop-light.png`, `page-mobile-light.png`, `page-desktop-dark.png`, … +
+`shots.json` (манифест: пути, размеры, ошибки консоли).
+
+## 3. Аудит
+```bash
+node ~/.dsh/skills/wow-design/assets/scripts/audit.mjs path/to/page.html --out screenshots
+```
+Проверяет: axe-core (критичные/serious нарушения), горизонтальный overflow на 390px, тач-цели < 40px,
+порядок заголовков, alt у картинок, битые изображения, загрузку шрифтов, ошибки консоли.
+Выход: `audit.json` + `audit.md`. Код выхода 2 — есть блокеры.
+
+## 4. Как смотреть скриншоты (обязательно!)
+1. `read_image` каждого PNG — не «на глаз по памяти», а реально открыть.
+2. Первый взгляд 5 секунд: понятно ли, что это, для кого, куда нажать? Что первое цепляет?
+3. Squint test: прищуриться — видна ли иерархия, или всё слилось в серое пятно?
+4. Grayscale: если убрать цвет, структура остаётся? Если нет — цвета не работают.
+5. Мобильный 390: нет ли обрезаний, скролла вбок, мелких тапов, «сжатого десктопа».
+6. Тёмная тема: фон/поверхности/контраст/акцент — отдельная палитра, а не инверсия.
+7. Сравни с референсом из брифа: тот же уровень «дорого»?
+8. Выпиши 5–10 конкретных правок с числами (px/rem/значения токенов), а не «сделать красивее».
+
+## 5. Итерации
+```
+v1: собрал → capture → read_image → 8 правок
+v2: правки → capture → read_image → 4 правки → rubric
+v3: финальные скриншоты → отчёт
+```
+Минимум 2 итерации. Первый вариант почти всегда «нормальный, но не WOW» — это ожидаемо.
+
+## 6. Гейт перед сдачей
+- Рубрика (`references/critique-rubric.md`): средний ≥ 4.4/5, ни один критерий < 4.
+- axe: critical/serious = 0.
+- 390px: overflow = 0, тапы ≥ 40px, читаемо.
+- Шрифты загружены (`document.fonts.status === "loaded"`), нет FOUT-скачков на скриншоте.
+- Тёмная и светлая темы сняты и просмотрены.
+- Нет ни одного антипаттерна из `references/anti-patterns.md`.
+- Скриншоты приложены к отчёту с путями.
+
+## 7. Если скриншоты не запускаются
+1. Проверь Node: `node -v`.
+2. Проверь пакеты: `ls assets/scripts/node_modules/playwright-core`; при отсутствии — `npm install` в папке скриптов.
+3. Проверь браузер: `msedge --version` или путь к Chrome. Скрипт подскажет, что не найдено.
+4. Если Chrome уже запущен с CDP — укажи `CDP_URL=http://127.0.0.1:9333` и не поднимай второй.
+5. В крайнем случае — сделай скриншоты вручную (Win+Shift+S) и всё равно оцени по рубрике: визуальная
+   проверка важнее автоматизации.
+
+## 8. CI (если проект уже на Playwright)
+- Визуальные снапшоты: `await expect(page).toHaveScreenshot('home.png', { fullPage: true })`.
+- Доступность: `@axe-core/playwright` — `expect(violations.filter(...)).toEqual([])`.
+- Матрица: 1440×900 и 390×844, light/dark (эмуляция `colorScheme`).
+- Обновляй снапшоты осознанно (`--update-snapshots`), в ревью смотри диффы.