simplycms 0.4.0

package/skills/redesign-from-reference/SKILL.md

@@ -0,0 +1,648 @@
+---
+name: redesign-from-reference
+description: Use when the user wants a SimplyCMS store redesigned to look like an existing website — "redesign my store like <url>", "make it look like this site", "build a theme from this reference", "clone the style of", "apply this site's colors and fonts" — or the same in Ukrainian ("редизайн за референсом", "зроби як у сайту", "тема за референсом", "перефарбуй магазин під"). Covers the full pipeline: clarify with legal limits, deterministic inspection (colors, type, motion), token mapping, theme scaffold, components from spec files, mandatory side-by-side verification, optional polishing pass.
+---
+
+# Редизайн за референсом — SimplyCMS
+
+Це **design transfer**, а не піксельний клон. Канонічні сторінки (каталог,
+товар, кошик, чекаут, профіль) лишаються в ядрі — тема постачає **оформлення**:
+токени, шрифти, Header/Footer, опційні Hero/HomeSections. Воронка покупки буде
+схожа «в кольорах і шрифтах», а не структурно — скажи це користувачу вголос на
+фазі 0, інакше на фазі 5 отримаєш розчарування замість приймання.
+
+Канон теми не переказуємо — читай його в доках SimplyCMS:
+`docs/architecture/themes.md` (механізм, контракт `ThemeModule`) і
+`docs/guides/themes.md` (практика автора теми). У магазині-скаффолді цих файлів
+немає — вони в репозиторії ядра.
+
+Інструменти скіла — три детерміністичні скрипти магазину:
+`.claude/skills/redesign-from-reference/scripts/discover.mjs`,
+`.claude/skills/redesign-from-reference/scripts/inspect.mjs` і
+`.claude/skills/redesign-from-reference/scripts/map-tokens.mjs`.
+Вони не «вгадують» — вони міряють; судження лишається за тобою й користувачем.
+
+---
+
+## Фаза 0 — Кларіфай (обовʼязкова, без неї не починай)
+
+Питання, на які потрібні відповіді ПЕРЕД першим запуском:
+
+1. **URL референсу** і які саме сторінки (головна — мінімум; окремо лендінг,
+   картка товару, футер-важка сторінка).
+2. **Глибина**: (а) лише токени — «перефарбувати»; (б) повна тема — токени +
+   Header/Footer/Hero/HomeSections; (в) + кастомні сторінки в `src/routes/my/`.
+3. **Мапінг блоків** референсу на слоти: що стає `HeroBanner`, що —
+   `HomeSections`, що взагалі не переноситься.
+4. **Ключ теми** (`<slug>`, латиниця, kebab-case) і людська назва.
+5. **Темна тема** потрібна? (визначає прапорець `--dark` на фазі 1).
+
+### Правові межі — проговори їх, це не формальність
+
+- **Переносимо:** палітру, типографічні пропорції, радіуси/тіні/ритм відступів,
+  ідеї лейауту, загальний настрій.
+- **НЕ переносимо:** логотипи, іконки бренду, фотографії, ілюстрації, тексти,
+  шрифти під платною ліцензією, будь-які ассети з референсу.
+- **Заборонено:** робити магазин схожим на чужий бренд так, щоб покупець
+  переплутав (імперсонація, фішинг). Якщо запит звучить саме так — зупинись і
+  скажи про це прямо; це не «жорсткіші налаштування», це відмова.
+- Якщо користувач має права на референс (це його ж сайт) — межа з ассетами
+  знімається його рішенням, і він каже це явно.
+
+---
+
+## Фаза 1 — Дискавері сторінок, діалог, інспекція
+
+Одна сторінка — це не магазин: палітра й шрифти з самого герою
+нерепрезентативні, а спеки компонентів і side-by-side QA на фазах 4-5
+лишаються без пар «наш канонічний тип ↔ їхня сторінка». Тому фаза йде трьома
+кроками, і середній з них — розмова.
+
+### 1.1 Дискавері
+
+```bash
+node .claude/skills/redesign-from-reference/scripts/discover.mjs <startUrl> \
+  --out docs/design-references/<slug>/sitemap-proposal.json [--max-visits 8]
+```
+
+Скрипт відкриває стартову сторінку, прокручує її до низу (ліниві секції й
+футер теж дають лінки), збирає `a[href]` з DOM, класифікує їх на канонічні
+типи `home | listing | product | cart | checkout | contact | about` і
+відвідує топ-кандидатів. Вивід `sitemap-proposal.json` (`schemaVersion: 2`):
+
+- `pageTypes: { <type>: { url, score, evidence, visited, title? } }` — `score`
+  тут **ціле число балів** (сума сигналів), а не частка 0..1, як `confidence`
+  у `tokens-proposal.json`; не плутай їх;
+- `evidence` — чим саме доведено тип. Джерел три:
+  `source: 'url' | 'anchor'` (словникові збіги — `urlPattern` /
+  `anchorMatch`) і `source: 'structure'` — **структурний fan-out**: запис
+  `{ structural: 'prefix-fanout', count }` означає «під цим префіксом лежить
+  `count` інших кандидатів, тобто він поводиться як індекс колекції», а
+  `{ structural: 'fanout-leaf' }` — «це бездітний лист під таким префіксом,
+  тобто поводиться як картка». Структура рятує сайти з нейтральними
+  сегментами, де словник мовчить, але вона ж не відрізняє каталог від
+  будь-якого іншого великого індексу: `/blog` із 12 постами виглядає точно
+  як `/shop` із 12 товарами. Тому сигнал дає гіпотезу, а вирок — діалог 1.2.
+  🔴 Окремого `source: 'aria'` НЕ буває: `aria-label` (як і `title` та
+  `img[alt]`) агрегується в `anchors` ще на зборі лінків, тож іконковий
+  кошик без видимого тексту доводиться звичайним `source: 'anchor'`;
+- `links: [{ pathname, anchors }]` — **увесь вхід класифікатора**
+  (дедуплікований за pathname, з агрегованими якорями, до будь-яких
+  виключень перепідбору). Саме те, що інструмент побачив: коли класифікація
+  здається дивною, відповідь шукається тут, а не власним зондом;
+- `unresolved: [{ type, reason }]` — причин три: `no-candidate` (кандидата не
+  знайшлось), `visit-failed` (кандидат був, але сторінка не віддала 2xx) і
+  `visit-mismatch`;
+- `visited: false` означає «кандидата знайдено, але бюджет `--max-visits`
+  вичерпано» — статус не підтверджений.
+
+🔴 **`visit-mismatch` — це «сторінка відкрилась, але її зміст суперечить
+типу»**, і саме так це треба пояснити користувачу в діалозі 1.2. Після 2xx
+кандидати `listing`/`product` **прокручуються до низу і лише потім** віддають
+легкий контент-проб (сітку карток масово дорендеровують на скролі — знятий
+одразу після переходу проб побачив би нуль карток на нормальному каталозі).
+Проб — два сирі виміри: JSON-LD `@type` плюс лічильник карток, де картка це
+лінк із зображенням, а рахується розмір НАЙБІЛЬШОЇ сімʼї однопрефіксних таких
+лінків (спільний батьківський префікс, pathname-и всередині сімʼї дедупляться).
+🔴 Саме сімʼя, а не «глибші за поточну сторінку»: на Shopify
+(`/collections/all` → `/products/<slug>`) і WooCommerce індекс і картки лежать
+на ОДНАКОВІЙ глибині, тож умова глибини обнуляла лічильник рівно там, де він
+потрібен. 🔴 Дві сімʼї не рахуються ніколи, бо це не чужий кущ карток, а
+оточення самої сторінки: топ-рівнева (префікс `/` — іконкове меню `/cart`,
+`/blog`, прапорці мов) і та, що ділить батьківський префікс із поточним
+pathname (блок «схожі товари» на картці `/products/<slug>`). Без цих двох
+відсікань звичайна картка товару без розмітки читалась би як сітка. Груба невідповідність — тип `product` на сторінці з ≥6 картками й без
+жодної `Product`-розмітки, або тип `listing` на сторінці, що Є ВИКЛЮЧНО товаром
+(схема `Product`, майже нуль карток і **жодної** `CollectionPage`/`ItemList`).
+🔴 Колекційна розмітка знімає правило `listing` сама по собі: вітрини штатно
+вкладають `Product` в `ItemList`, тож на коректному індексі каталогу `Product`
+у розмітці є за проєктом. Правила навмисно консервативні (ловлять лише грубу
+помилку) і JSON-LD у них — додатковий сигнал, а не вимога: сторінки без
+розмітки просто судяться за картками. 🔴 Помилка САМОГО проба (CSP, таймаут
+`evaluate`) не робить сторінку `visit-failed` і не є доказом невідповідності:
+візит, що віддав 2xx, лишається успішним, просто без проба. Практичний сенс —
+індекс колекції з ім'ям `/product` більше не забирає тип `product` у справжньої
+картки, а сама сторінка при цьому лишається доступною типу `listing`:
+`visit-mismatch` спростовує ПАРУ (тип, сторінка), а не сторінку — блокується
+рівно ця пара, інший тип той самий URL узяти ще може. На відміну від
+`visit-failed`, який вибиває pathname з набору для ВСІХ типів.
+
+### 1.2 Обовʼязковий діалог (чекпойнт)
+
+Покажи користувачу таблицю «знайшов ↔ unresolved» — саме таблицею, не прозою:
+
+| Тип | URL | score | visited | Питання |
+|-----|-----|-------|---------|---------|
+| `home` | `https://…/` | 4 | так | підтверджуєш? |
+| `product` | `https://…/products/x` | 2 | так | це репрезентативна картка? |
+| `checkout` | — | — | — | `unresolved: no-candidate` — дай URL або пропускаємо? |
+
+Далі — рівно два запитання, і на обидва потрібна відповідь користувача:
+
+1. **Підтверди або виправ** кожен знайдений рядок (частий випадок — дискаверер
+   вибрав службову сторінку замість репрезентативної).
+2. **На кожен `unresolved`** — «дай URL або пропускаємо?». Причину переказуй
+   людськими словами, не кодом: `no-candidate` — «лінка на таку сторінку в
+   DOM не було»; `visit-failed` — «сторінка не відкрилась»;
+   `visit-mismatch` — «сторінка відкрилась, але її зміст суперечить типу
+   (наприклад, під кандидатом на картку товару виявилась сітка з десятка
+   товарів), тож кандидата відхилено, а заміни не знайшлось».
+
+🔴 **Продовжувати з непорожнім `unresolved` без відповіді користувача
+заборонено.** Мовчазне «ну, checkout ми не знайшли, поїхали далі» — це рівно
+та помилка, заради якої дискаверер і зʼявився: користувач дізнається про
+пропущену сторінку аж на фазі 5. Те саме стосується рядків з `visited: false`
+— спитай, чи піднімати `--max-visits`.
+
+### 1.3 Інспекція підтверджених сторінок
+
+На кожну підтверджену сторінку — окремий запуск, артефакти в теку **свого
+типу** (розкладку задає скіл через `--out`, дефолти CLI її не знають):
+
+```bash
+node .claude/skills/redesign-from-reference/scripts/inspect.mjs <url> \
+  --out docs/design-references/<slug>/<pageType> [--dark]
+```
+
+Дає скріншоти `desktop.png`/`tablet.png`/`mobile.png` (1440/768/390) та
+`inspection.json` (`schemaVersion: 3`): кольори з частотами й площею, шрифти
+(h1-h3 vs body), кластери `border-radius`, тіні, шкала відступів,
+`fontStylesheets`, `darkDetected`, `sampleViewport`, `radiusDropped` — і
+секцію **`motion`** (нижче).
+
+🔴 **Політика артефактів залежить від репозиторію, і перевіряється вона
+`.gitignore`, а не памʼяттю.** У **магазині** артефакти інспекцій
+**комітяться** — це аудитований слід рішень: за півроку видно, звідки взявся
+кожен колір теми. У **монорепо ядра** (де скіл прогонять на живому референсі,
+щоб перевірити сам механізм) тека `docs/design-references/` цілком у
+`.gitignore` — рішення власника: це робочий процес, не код. Тобто там
+артефакти лишаються локальними, і «нічого не закомітилось» — норма, а не
+збій. Перед першим `git add` подивись `.gitignore` і скажи користувачу, який
+із двох випадків маєш.
+
+- Кожен запуск **прокручує сторінку до низу на кожному з трьох viewport-ів**
+  перед знімком — інакше scroll-animated секції потрапляють у скріншот
+  порожніми. Ціна — час: на довгій сторінці інспекція йде в кілька разів
+  довше за наївний знімок. Це очікувано, не вішай процес.
+- **Палітра семплиться з десктопу** (`sampleViewport` у JSON — чесне поле):
+  секції, приховані на вузькому лейауті, інакше випадали б із семплу.
+- **Playwright не встановлено** (у шаблоні магазину його свідомо немає) —
+  скрипт друкує точну команду й виходить з кодом 1:
+  `pnpm add -D playwright && pnpm exec playwright install chromium`.
+  Не обходь це вручну і не «здогадуйся» про кольори — попроси встановити.
+- **Мережеві збої гучні.** Порожній чи частковий `inspection.json` — привід
+  перезапустити, а не мапити далі.
+
+**Секція `motion` — рух, знятий детерміністично.** Пʼять каналів плюс похідний
+прапорець, усі з того самого запуску — окремої команди для руху немає:
+
+| Поле | Що всередині |
+|------|--------------|
+| `motion.transitions` | кластери `{ property, durationMs, easing, count }`, сортування за `count` спадно — перші 3-5 рядків і є «мова руху» сайту |
+| `motion.keyframes` | `{ names, inaccessibleSheets }` — імена `@keyframes` same-origin; `inaccessibleSheets > 0` означає cross-origin аркуші, тобто чесну дірку, а не «анімацій немає» |
+| `motion.reveal` | по секції: `{ index, tag, selector, opacityBefore, opacityAfter, transformChanged, animated }`; `animated: true` — секція проявляється при скролі. `index` — позиція у ВИБІРЦІ, не в DOM |
+| `motion.revealSampled` | скільки вузлів реально семпльовано (обсяг вибірки). `0` означає «міряти не було на чому» — не «сторінка не рухається» |
+| `motion.revealRoot` | `'main'` або `'body-fallback'` — звідки бралися кандидати: діти `<main>`, а без нього `body > section` плюс діти обгорток верхнього рівня |
+| `motion.hover` | `{ entries: [{ index, selector, changes: [{ property, from, to }] }], skipped }` — дельти `background-color`/`border-color`/`box-shadow`/`color`/`transform` під курсором; `skipped` — вузли, до яких ховер не дійшов |
+| `motion.jsLibraries` | `{ detected, markers }` — GSAP / Framer Motion / Lottie / anime.js за `script src`, window-глобалами і `data-*` |
+| `motion.jsDrivenSuspected` | **три стани**: `true` — reveal є, а ні transitions по opacity/transform, ні `@keyframes` його не пояснюють (рух крутить JS); `false` — reveal виміряно й механізм видно; `'unknown'` — вибірки не було взагалі |
+
+🔴 **`schemaVersion: 3` — саме через ці три поля.** Інспекція, знята до
+інкремента Б.3, має версію `2`, у ній `jsDrivenSuspected` завжди `boolean` і
+немає ні `revealSampled`, ні `revealRoot` — тобто «нема на чому міряти» там
+нерозрізненне з «перевірено, підозри немає». `map-tokens.mjs` такі файли
+читає (motion у токени не йде), але **motion зі старої інспекції не читай**:
+перезніми сторінку актуальним `inspect.mjs`.
+
+🔴 **Нуль вибірки — це НЕ «не підозрюється».** `revealSampled: 0` разом із
+`jsDrivenSuspected: 'unknown'` означає, що reveal-канал на цій сторінці не
+виміряв нічого: розмітка не дала кандидатів-секцій ні під `<main>`, ні під
+fallback-коренем. Читати це як «перевірено, підозри немає» — рівно та помилка,
+через яку прапорець і став триставним. Побачив `'unknown'` — скажи це вголос
+і став рух цієї сторінки під очі (свої скріншоти або скріншоти користувача).
+
+- `motion` — **пер-сторінкова** секція: `map-tokens.mjs` її не споживає, у
+  зведений `tokens-proposal.json` вона не потрапляє (контракт токенів теми
+  руху не містить — свідома межа). Спеки компонентів на фазі 4 читають
+  `motion` з `inspection.json` **своєї** сторінки.
+- Ховер знімається по `header a, nav a, button, [role="button"]` — видимі, у
+  DOM-порядку, стеля 20 вузлів. Це стилістичний ЗРАЗОК ховер-палітри, а не
+  інвентаризація всіх інтерактивних елементів сайту.
+
+**Interaction sweep (залишок — опційно, потрібен браузерний MCP).** Ховер і
+scroll-reveal тепер знімаються детерміністично (вище) — MCP для них не
+потрібен. За MCP лишається те, чого скрипт не робить: **клік** по меню, табах
+і аккордеонах, **фокус-стилі** (`:focus-visible` по Tab), поведінка **в русі**
+(sticky-шапка, паралакс, автоплей-каруселі, reverse-анімації) і живий огляд на
+390px. Записуй спостереження в `docs/design-references/<slug>/notes.md`.
+**Без MCP** фаза деградує чесно — але вже не до нуля: тривалості, easing-и,
+reveal-прапорці й ховер-дельти в артефактах Є; без сліду лишаються клікова
+модель і фокус. Скажи користувачу саме це, не ширше.
+
+---
+
+## Фаза 2 — Мапінг токенів
+
+Мапиться **весь набір інспекцій разом**, а не кожна сторінка окремо: тема в
+магазині одна, і токени в ній теж одні.
+
+```bash
+node .claude/skills/redesign-from-reference/scripts/map-tokens.mjs \
+  docs/design-references/<slug>/home/inspection.json \
+  docs/design-references/<slug>/listing/inspection.json \
+  docs/design-references/<slug>/product/inspection.json \
+  --out docs/design-references/<slug>/tokens-proposal.json
+```
+
+- **`--out` при кількох входах обовʼязковий** — інакше зведення лягло б у теку
+  однієї зі сторінок; скрипт падає з підказкою, а не вгадує.
+- Що зливається: колірні частоти сумуються по парі (роль, значення),
+  «інтерактивність» — за принципом «будь-де інтерактивний → інтерактивний»,
+  `fontStylesheets` — обʼєднання, радіуси — конкатенація, `darkDetected` —
+  «хоч десь». `motion` не зливається взагалі — вона пер-сторінкова.
+  Шрифти — **голосуванням по сторінках** (кожна сторінка дає один голос за
+  heading-сімʼю і один за body); усередині сторінки сімʼя перемагає за
+  СУМОЮ довжин тексту (ліміт 400 символів на вузол), частота — лише
+  tie-break. Саме тому дрібні `<span>`-мітки в моно-гарнітурі більше не
+  перебивають body-абзаци.
+- Порядок файлів на результат не впливає — сортування стабільні.
+- Один вхід (`map-tokens.mjs <один inspection.json>`) працює як і раніше,
+  дефолтний вивід — поруч із входом.
+
+Дає `tokens-proposal.json` (`schemaVersion: 2`): `{ schemaVersion, tokens,
+fonts?, confidence, contrastWarnings, unmapped }` плюс `sources: [{ file, url }]`
+при кількох входах — за пропозицією видно, з яких саме сторінок вона зібрана.
+`dark` — усередині `tokens` (форма `DesignTokens` 1:1). 🔴 Цей лічильник
+версії — **не** той, що в `inspection.json`: там версіонується вхід, тут
+вихід, і рухаються вони незалежно.
+
+**Пропозицію обовʼязково обговорюємо з користувачем.** Мінімум три речі:
+
+- `contrastWarnings` — пари `*`/`*-foreground`, що не тягнуть WCAG AA 4.5:1.
+  Скрипт нічого не «виправляє» сам: рішення — освітлити фон, затемнити текст чи
+  свідомо прийняти ризик — за людиною. Мовчки залишити провал не можна.
+- `unmapped` — кольори референсу, що нікуди не лягли. Це **структуровані
+  записи**, а не голий список hex:
+  `{ hex, role, count, area, contrastOnBackground, contrastOnCard, belowAA }`
+  — дедупліковані за парою (hex, роль), відсортовані за `count` спадно.
+  Тобто вимога «обговори `unmapped`» тепер **виконувана з файлу**, без
+  власного дослідження: видно і як часто колір трапляється, і скільки він
+  займає площі, і в якій ролі (`background`/`text`/`border`). Спитай по
+  верхніх записах, чи не має колір стати `accent`/`secondary`.
+  🔴 `belowAA: true` — це **провал контрасту, який `contrastWarnings` не
+  ловить**: ті дивляться лише на змаповані пари `*`/`*-foreground`, а тут
+  текстовий колір референсу міряється проти запропонованих `background` і
+  `card`, за найгіршою з двох поверхонь. Такий рядок мовчки лишити не можна —
+  або колір стає токеном і виправляється, або користувач приймає ризик явно.
+  `contrastOnBackground`/`contrastOnCard` можуть бути `null` — це «токена в
+  пропозиції немає», а не нульовий контраст.
+- `confidence` — де евристика вгадувала. Низька впевненість на `primary` майже
+  завжди означає, що акцент треба вибрати очима зі скріншота.
+
+Затверджений набір — це домовленість, зафіксована в
+`docs/design-references/<slug>/tokens-proposal.json`. Далі керуємось ним, а не
+памʼяттю про розмову.
+
+---
+
+## Фаза 3 — Тема (checkpoint робочого магазину)
+
+```bash
+pnpm simplycms create theme <slug>
+```
+
+Штатний лайфсайкл, свого скаффолда не вигадуємо. Далі:
+
+1. Перенеси затверджені `tokens` у `themes/<slug>/tokens.ts` (значення — HSL
+   -трійки без `hsl()`, `radius` — у `rem`, `font-sans`/`font-heading` — повний
+   CSS-стек).
+2. Якщо в пропозиції є `fonts` — додай їх у `ThemeModule.fonts` (лише
+   `https:`-stylesheet; фільтр — `safeFontStylesheets`).
+3. `pnpm build` → активуй тему в адмінці (реєстрація йде через
+   `simplycms.config.ts`, рядок у БД дописує `bootstrapThemes`).
+
+**Це контрольна точка.** Магазин має бути робочим і «перефарбованим» ще до
+будь-яких компонентів. Якщо браузерного MCP немає — компоненти фази 4 без
+скріншотів користувача не робимо, але **фаза 5 виконується й тут**: пари
+інспекцій знімає той самий `inspect.mjs`, MCP їй не потрібен. Тобто віддаєш
+не «робочу тему й перелік того, що лишилось», а робочу тему **плюс** таблицю
+розбіжностей із класами.
+
+---
+
+## Фаза 4 — Компоненти за спека-файлами
+
+Потрібен браузерний MCP або скріншоти від користувача. Дисципліни — з
+методології клонера, і вони не опційні:
+
+1. **Спека ПЕРЕД кодом.** На кожен компонент —
+   `docs/design-references/<slug>/components/<Name>.spec.md`. Немає спеки —
+   немає коду.
+2. **Interaction model first.** Спека починається з відповіді, чим керується
+   компонент: static / click / scroll / time. Побудувати click-меню там, де
+   референс scroll-driven, — найдорожча помилка цієї фази.
+3. **Усі стани**, а не «основний»: default, hover, focus-visible, active,
+   disabled, loading, empty, error.
+4. **Точні значення** зі спеки — кольори токенами теми, розміри, ваги, відступи.
+   Ніяких «приблизно як там».
+5. **Responsive** на всі три ширини: 1440 / 768 / 390.
+6. **Секція `## Motion`** у спеці — обовʼязкова (нижче), навіть коли відповідь
+   у ній «рух відсутній».
+7. **Бюджет складності ~150 рядків** на компонент (він же ліміт файлу в
+   каноні репо). Не влазить — це два компоненти.
+
+### Секція `## Motion` у `<Name>.spec.md`
+
+Пишеться з **виміряних** даних — секції `motion` того `inspection.json`, чия
+сторінка містить цей компонент. Формулювання «плавно зʼявляється» без числа —
+це не спека. Чотири підпункти, кожен із джерелом:
+
+1. **Тривалості й easing-и** — з `motion.transitions`: бери 1-2 верхні
+   кластери (вони відсортовані за `count`) і пиши як
+   `transition: <property> <durationMs>ms <easing>`. Якщо кластера під
+   потрібну властивість немає — так і пиши: «у референсі не виміряно, беремо
+   типову 200ms ease-out», щоб наступна ітерація бачила, що це наше рішення,
+   а не факт із сайту.
+2. **Reveal** — з `motion.reveal`: чи секція, у якій живе компонент, має
+   `animated: true`, і яка саме дельта (`opacityBefore` → `opacityAfter`,
+   `transformChanged`). Це прямо задає, чи потрібен компоненту
+   `IntersectionObserver`-клас, чи він статичний.
+3. **Hover** — з `motion.hover.entries`: конкретні `changes`
+   (`property`, `from`, `to`) для селектора цього компонента. Кольори в спеці
+   перекладаються **в токени теми**, а не в сирі `rgb()` референсу.
+4. **Межа руху.** Якщо `motion.jsLibraries.detected` непорожній або
+   `motion.jsDrivenSuspected: true` — пиши це в спеку прямим текстом:
+   «motion керується JS (`<detected>`), статично незнімано → дивись очима /
+   скріншоти користувача». Вигадувати тривалості замість такого рядка
+   заборонено. Так само чесно фіксуй `motion.keyframes.inaccessibleSheets > 0`
+   — частину анімацій ми просто не бачили.
+   🔴 Стан `jsDrivenSuspected: 'unknown'` (при `revealSampled: 0`) — це
+   **третій**, окремий рядок, а не «руху немає»: «reveal не виміряно —
+   вибірка порожня (`revealRoot: <корінь>`); чи проявляється секція при
+   скролі, не встановлено». Записати його як `false` («перевірено, підозри
+   немає») — та сама вигадка, що й вигадана тривалість, тільки тихіша.
+
+Реалізація — CSS-transitions компонента; motion-токенів у контракті теми
+немає (свідома межа v1), тож значення живуть у самому компоненті.
+
+Технічні межі:
+
+- Обовʼязкові — `Header`/`Footer`; опційні — `HeroBanner` (отримує `banners`),
+  `HomeSections` (**без пропсів**, дані тягне сама).
+- **Усі рядки UI — через `useThemeT`** і власний каталог теми (uk/en). Кирилиця
+  в JSX валить лінт; неповний каталог валить парність-тест.
+- Дані — хуками ядра. Канонічні сторінки ядра **не редагуємо**; кастомні
+  сторінки магазину — тільки `src/routes/my/`.
+
+---
+
+## Фаза 5 — Side-by-side верифікація (по КОЖНОМУ підтвердженому типу)
+
+Ця фаза — не «глянь і скажи, схоже чи ні». Це дисципліна пар: на кожен
+підтверджений тип зі `sitemap-proposal.json` мають бути **дві інспекції тієї
+самої форми**, зняті **тим самим** `inspect.mjs`.
+
+### 5.1 Зняти наш бік
+
+Підніми магазин (`pnpm build && pnpm start`, або `pnpm dev`) і зніми кожен
+підтверджений тип окремим запуском у теку `_ours/<pageType>/`:
+
+```bash
+node .claude/skills/redesign-from-reference/scripts/inspect.mjs http://localhost:3000/catalog \
+  --out docs/design-references/<slug>/_ours/listing
+```
+
+Мапа «канонічний тип → URL нашого магазину»:
+
+| Тип | Наш URL | Передумова |
+|-----|---------|------------|
+| `home` | `/` | — |
+| `listing` | `/catalog` (або `/catalog/<sectionSlug>` — репрезентативніша) | — |
+| `product` | `/catalog/<sectionSlug>/<productSlug>` | — |
+| `cart` | `/cart` | 🔴 кошик має бути НЕПОРОЖНІМ |
+| `checkout` | `/checkout` | 🔴 кошик має бути НЕПОРОЖНІМ |
+| `about` / `contact` | канонічної сторінки в ядрі немає — або наша `src/routes/my/…`, або тип свідомо без пари (виняток №3 нижче) | — |
+
+🔴 **`cart`/`checkout` `inspect.mjs` сам зняти не може.** Кошик — клієнтський
+стан у `localStorage` (ключ `simplycms-cart`), а інспекція відкриває свіжий
+контекст браузера й робить рівно `page.goto` + семпл, тож кошик там завжди
+порожній. `/cart` віддасть порожню сторінку — порівнювати нема з чим;
+`/checkout` при порожньому кошику **редиректить на `/cart`**
+(`packages/simplycms/src/storefront-routes/pages/Checkout.tsx`, «Redirect if cart is
+empty»), а в `inspection.json` пишеться ЗАПИТАНИЙ URL, не кінцевий. Тобто
+наївний запуск кладе в `_ours/checkout/` скріншоти кошика з полем
+`url: …/checkout` — мислабельований артефакт, на якому потім будуються
+таблиця 5.3 і фаза 6.
+
+Виходів рівно два, і обидва явні:
+
+- **(а) наповнити кошик у тому самому контексті, у якому знімаєш.** Кошик,
+  покладений у власному браузері, інспекції не видно — контекст інший, — тож
+  потрібна одноразова обгортка: `page.goto` на корінь магазину →
+  `page.evaluate` записує `localStorage['simplycms-cart']` (масив позицій) або
+  клікає «додати в кошик» → `page.goto` на `/cart` чи `/checkout` →
+  `inspectPage` (реекспортований з `inspect.mjs` саме для таких обгорток).
+  Пара виходить повноцінна, знята тією ж інспекцією.
+- **(б) записати тип рядком** «пара неможлива автоматично: порожній кошик
+  редиректить — причина в таблиці» у таблицю 5.3. Це не мовчазний пропуск, а
+  зафіксоване рішення, видиме користувачу.
+
+🔴 **Третього виходу немає: класти скріншот кошика під іменем `checkout`
+ЗАБОРОНЕНО.** Пара з підміненим змістом гірша за відсутню — відсутню видно,
+підмінену вже нічим не спіймати.
+
+Виходить пара: `…/<slug>/<pageType>/` (референс) і
+`…/<slug>/_ours/<pageType>/` (наш) — однакові три скріншоти й два
+`inspection.json`, тобто порівняння йде **полями**, а не памʼяттю.
+
+🔴 **Продовжувати без пари по підтвердженому типу заборонено.** Це та сама
+модель, що обовʼязковий діалог фази 1.2: «зробили home, решта наче нормально»
+— рівно та помилка, через яку ця вимога зʼявилась. Винятків рівно три, і
+кожен іде в підсумкову таблицю окремим рядком:
+1. тип, свідомо пропущений користувачем на фазі 1.2 («пропущено на фазі 1.2,
+   пари немає за домовленістю»);
+2. `cart`/`checkout`, коли кошик наповнити нема чим (вихід «б» вище);
+3. тип, у якого сторінки в магазині немає взагалі — `about`/`contact` без
+   власної `src/routes/my/…` (рядок таблиці вище): знімати нема що, і це
+   записується рядком «сторінки в магазині немає — пари немає».
+
+Усі три — зафіксовані рішення, а не мовчазні пропуски.
+Стенд без даних теж не привід пропустити пару: порожня картка товару —
+це вже перша розбіжність класу **дані**, і фіксується вона саме тут.
+
+### 5.2 Класифікувати кожну розбіжність
+
+Перелічуй розбіжності по парі, і кожна отримує РІВНО один клас:
+
+| Клас | Що це | Ознака в парі | Куди веде |
+|------|-------|---------------|-----------|
+| **токен-фіксабельна** | колір / радіус / шрифт / відступ, який можна привести токеном або стилем теми | різні значення полів `colors`/`radius`/`fonts`/`spacing` при схожій структурі | фаза 6, щабель «токен» — або одразу правка `tokens.ts` |
+| **дані** | верстка правильна, наповнення стенда бідне (нема фото, опису, властивостей, кількох секцій) | наш блок порожній або в один рядок там, де в референсі контент | не фікситься дизайном — потрібен demo-датасет (`scripts/dev-stand/README.md`) або контент власника |
+| **структурна-за-дизайном** | воронка покупки має структуру ядра, і це рішення, а не дефект | інший порядок/склад блоків на `listing`/`product`/`cart`/`checkout` | назвати вголос: фаза 6, щабель «view теми» (для пʼятірки вітрини) або **прийняти**; правити канонічні сторінки ядра не можна ніколи |
+
+Правило спеки лишається: **винна спека** (описали не те, що бачимо) →
+ре-інспекція й правка спеки; **винен код** (спека каже інше) → фікс за
+спекою. Не «підганяй» код, не оновивши спеку — наступна ітерація втратить
+джерело правди.
+
+### 5.3 Підсумок — таблиця, яку ти ПОКАЗУЄШ користувачу
+
+```markdown
+| Тип | Розбіжність | Клас | Рішення |
+|-----|-------------|------|---------|
+| home | герой вужчий, фон світліший на 6% | токен-фіксабельна | правимо `background` у `tokens.ts` |
+| listing | картки без тіні | токен-фіксабельна | додаємо тінь у Header-незалежний стиль теми |
+| product | галерея порожня, немає властивостей | дані | demo-датасет стенда; дизайном не лікується |
+| checkout | інший порядок кроків | структурна-за-дизайном | приймаємо (структура ядра) |
+| about | — | — | пропущено на фазі 1.2 за рішенням користувача |
+```
+
+Таблиця живе у файлі —
+`docs/design-references/<slug>/side-by-side.md`, поруч із парами інспекцій
+(комітяться вони чи ні — за політикою репозиторію, фаза 1.3). Покажи її
+користувачу цілком, разом із парами скріншотів, і назви окремо те, що свідомо
+не переносили. Ця ж таблиця — вхід у фазу 6.
+
+### 5.4 Якщо перевіряєш фільтри каталогу в браузері — чек-лист
+
+Ця перевірка не обовʼязкова (вона не про оформлення), але коли до неї доходиш
+— роби її за чек-листом, бо в ній є пастка, яка вже коштувала сесії.
+
+🔴 **Пастка: перемикання фільтрів В ОДНІЙ сесії накопичує умови.** Клацнув
+бренд, потім ціну, потім наявність — і отримав «0 результатів на всіх»,
+що читається як зламаний фільтр. Насправді це артефакт тесту: умови
+поскладались у кон'юнкцію, під яку товару й справді немає. Висновок «фільтри
+зламані» тут неправдивий, а виправляти за ним нічого.
+
+Три вимоги, усі три обовʼязкові:
+
+1. **Чиста сторінка на кожен стан фільтра.** Новий перехід за URL (або
+   свіжа вкладка) під кожен окремий фільтр — не клацання поверх попереднього
+   стану. Перевіряєш комбінацію — перевіряй її свідомо, як окремий стан, а
+   не як залишок від попереднього кроку.
+2. **Очікування — з БД, а не з памʼяті.** Перед перевіркою дізнайся, скільки
+   позицій має віддати цей фільтр (запит до бази стенда), і порівнюй із цим
+   числом. «Здається, тут мало бути більше» — не результат перевірки.
+3. **Обовʼязковий контрольний випадок із НЕПОРОЖНІМ результатом.** Хоча б
+   один фільтр, який за даними стенда точно щось віддає. Без нього «усе по
+   нулях» неможливо відрізнити від зламаного фільтра — саме контрольний
+   випадок і відділяє «даних немає» від «код не працює».
+
+Порожній результат на реальних даних — це, до речі, теж знахідка, але класу
+**дані** (фаза 5.2), а не дефект оформлення.
+
+---
+
+## Фаза 6 — Шліфування (опційна, за рішенням користувача)
+
+Базовий клон готовий; фаза 6 — це посторінковий прохід по таблиці 5.3, щоб
+кожна розбіжність отримала **рішення**, а не залишилась рядком. Фаза опційна
+цілком: користувач може сказати «досить» — і це нормальна відповідь. Чого не
+можна — **мовчки лишити як є**.
+
+Драбина рішень, зверху вниз. Спускайся на щабель нижче лише тоді, коли
+верхній чесно не працює:
+
+1. **Токен теми.** Колір, радіус, шрифт-стек, ритм відступів — правиться в
+   `themes/<slug>/tokens.ts` і діє на весь магазин відразу. Найдешевший і
+   найбезпечніший щабель: він же зберігає узгодженість вітрини.
+2. **Setting теми** (`ThemeModule.settings`) — коли варіант потрібен
+   перемикачем, а не константою (щільність шапки, показувати чи ні секцію).
+   Ціна вища: це вже поверхня, яку тема мусить підтримувати далі.
+3. **View теми** (`ThemeModule.views`, контракт тем v3) — коли розбіжність
+   СТРУКТУРНА і сторінка з воронки: `Home`, `Catalog`, `CatalogSection`,
+   `ProductDetail`, `Cart`. Тема віддає власну розмітку сторінки, а дані, SEO
+   і комерційні реквізити лишаються ядром: кнопку купівлі, блок ціни, підсумок
+   кошика тема не пише — вона РОЗСТАВЛЯЄ готові `vm.slots`. Ціна щабля висока:
+   це найбільший обсяг коду й підтримки, і заявлений view мусить пройти гейт
+   (`pnpm simplycms theme:conformance <slug>`, потребує `jsdom`) — інакше
+   магазин лишиться без реквізиту, бо рантайм-fallback ядро НЕ робить.
+   Механізм — `docs/architecture/themes.md` §2.1, how-to —
+   `docs/guides/themes.md` §3.5. Сторінок поза пʼятіркою (checkout, auth,
+   профіль) це не стосується — там щабель 4 або 5.
+4. **Кастомна сторінка магазину** в `src/routes/my/` — коли розбіжність
+   структурна, а сторінка НЕ з воронки покупки (лендінг, «про нас»,
+   промо-сторінка). Своя сторінка, свої компоненти, дані — хуками ядра.
+5. **Свідомо прийняти канонічний вигляд.** Легітимне рішення, а не поразка:
+   структура воронки належить ядру. Записується в таблицю тим самим рядком —
+   «приймаємо, структура ядра».
+
+Кожне рішення дописується в ту саму таблицю 5.3 — колонка «Рішення» плюс,
+за потреби, «Щабель» (1-5). Після правок **перезніми пару** для зачепленого
+типу: без нової інспекції «стало краще» — це знову «на око», проти чого
+весь цей скіл і побудований.
+
+---
+
+## Межі v1 — назви їх уголос, а не замовчуй
+
+- **Reverse-анімації.** Прокрутка розкриває reveal-once секції — саме на це
+  розрахований скрол інспекції. Сайт, який ховає секцію назад при зворотному
+  скролі, ми знімаємо як «розкриту»; що саме він показує в русі — дивись очима.
+- **Сторінки за логіном** (кабінет, історія замовлень, приватний чекаут) —
+  поза інспекцією: авторизацію ми не проходимо й обходити захист не будемо.
+  Потрібні — попроси в користувача скріншоти.
+- **Палітра — з десктопного viewport.** Оформлення, що існує тільки на мобілці
+  (бургер-панель, mobile-only банер), у семпл кольорів не потрапляє. Побачив
+  таке на `mobile.png` — фіксуй очима й питай користувача.
+- **Шрифти через CSS `@import` і self-hosted `@font-face`** не ловляться:
+  `fontStylesheets` збирає лише `link[rel=stylesheet]`. Сімʼю визначай зі
+  скріншотів і підтверджуй у користувача.
+- **Структура сторінок не копіюється автоматично.** Дискаверер дає пари «наш
+  канонічний тип ↔ їхня сторінка» для токенів, спек компонентів і QA — не для
+  переносу верстки воронки. Перемалювати структуру можна лише свідомо й лише
+  темою: щабель «view теми» фази 6 (контракт тем v3 — пʼять сторінок вітрини,
+  дані й реквізити лишаються ядром). Правити канонічні сторінки ядра —
+  заборонено завжди.
+- **Рух не стає токеном.** `motion` знімається й іде у спеки компонентів, але
+  контракт `ThemeTokenValues` motion-токенів не має: тривалості й easing-и
+  живуть у CSS самих компонентів теми, а не в `tokens.ts`.
+- **Клік і фокус лишаються за очима.** Детерміністично знято ховер і
+  scroll-reveal; меню/таби/аккордеони, `:focus-visible` і поведінка в русі —
+  браузерний MCP або скріншоти користувача.
+- **Ховер знято зразком, не суцільно.** Стеля 20 видимих вузлів по
+  `header a, nav a, button, [role="button"]`; `motion.hover.skipped` чесно
+  показує, скількох не дістали (оверлей, вузол відʼєднався).
+
+---
+
+## Анти-патерни
+
+- **Вгадувати значення «на око»** замість `inspection.json` — головна причина
+  теми, яка «майже схожа» і нікому не подобається.
+- **Клікабельний UI замість scroll-driven** (і навпаки) — модель взаємодії
+  визначаємо ДО коду.
+- **Тягнути чужі ассети й тексти** — див. фазу 0; це не питання смаку.
+- **Рядки теми в core-каталозі i18n** — ламає типізацію ядра; тема має власний
+  `messages`.
+- **Правки канонічних сторінок ядра** — вони не належать темі; потрібна інша
+  сторінка — `src/routes/my/`.
+- **Ігнорувати `contrastWarnings`** — доступність не «деталь оформлення».
+- **Продовжувати після провалу інспекції** з порожнім чи частковим JSON.
+- **Side-by-side лише по `home`** — решта підтверджених типів без пар. Саме
+  через це фаза 5 і стала дисципліною, а не рядком.
+- **Розбіжність без класу й без рішення** — рядок «ну, трохи інакше» в
+  підсумку нічого не вирішує; клас і рішення обовʼязкові (фази 5-6).
+- **Вигадувати тривалості анімацій**, коли `motion.jsDrivenSuspected: true`
+  або `jsLibraries.detected` непорожній — там треба чесна межа, а не число.
+- **Читати `jsDrivenSuspected: 'unknown'` як «руху немає»** — це «не
+  виміряно» (`revealSampled: 0`), і в спеку йде саме таким рядком.
+- **Лишати `unmapped` із `belowAA: true` без рішення** — `contrastWarnings`
+  цей провал не бачить за визначенням, тож мовчання тут остаточне.
+- **Обіцяти піксельну відповідність** — скіл цього не робить і не має.
+
+---
+
+## Чесна деградація
+
+| Немає | Що робимо |
+|-------|-----------|
+| Playwright у магазині | Друкуємо команду установки, зупиняємось. Без інспекції фаз 2-6 немає. |
+| Браузерного MCP | Фази 0-3 повністю; фаза 5 — теж повністю (пари знімає той самий `inspect.mjs`, MCP їй не потрібен). Фаза 4 — лише якщо користувач дасть скріншоти клікових станів; інакше віддаємо робочу перефарбовану тему й називаємо борг. |
+| Доступу до референсу (401/403/бот-захист) | Просимо скріншоти або публічну сторінку; не обходимо захист. |
+| Сторінок під якийсь тип (`unresolved`) або відповіді користувача на «дай URL» | Питаємо явно (фаза 1.2) і чекаємо. Користувач відмовився давати URL — тип **пропускаємо свідомо** й пишемо це в підсумок фази 5: токени зібрані без нього, пар для side-by-side по ньому не буде. Мовчки добирати сторінку «на свій розсуд» чи вдавати, що тип знайдено, — не можна. |
+| Змоги наповнити кошик перед знімком (`cart`/`checkout`) | Пара знімається тільки з непорожнім кошиком (фаза 5.1, вихід «а»): свіжий контекст інспекції має кошик порожнім, а `/checkout` тоді редиректить на `/cart`. Нема чим наповнити — тип іде в таблицю 5.3 рядком «пара неможлива автоматично». Скріншот кошика в теці `_ours/checkout/` — заборонено. |
+| Даних на стенді (порожня картка товару, одна секція) | Пару все одно знімаємо; розбіжність іде класом **дані**, не «фіксимо кольором». Наповнення — demo-датасет діагностичного стенда (`scripts/dev-stand/README.md`, накочується поверх сіду пілота) або контент власника. |
+| Виміряного руху (`motion` порожній, `jsDrivenSuspected: true` або `'unknown'` при `revealSampled: 0`) | Пишемо в спеки чесний рядок — «motion керується JS» або «reveal не виміряно: вибірка порожня» — і просимо очі користувача. Вигадані тривалості й тихе `false` — гірше за відсутність даних. |
+| Часу або бажання користувача на фазу 6 | Фаза опційна: зупиняємось після таблиці 5.3 і віддаємо її як перелік відкритих рішень. Що заборонено — залишити розбіжність без класу й без рішення. |
+| Згоди на правові межі | Зупиняємось на фазі 0. |