simplycms 0.4.0

package/skills/redesign-from-reference/scripts/lib/classify.mjs

@@ -0,0 +1,126 @@
+/**
+ * Класифікатор лінків сайту на канонічні типи сторінок (задача §2.C.2, план
+ * Р3/Р3b/Р5). Чиста функція без браузера — вхід уже зібраний DOM-обходом
+ * `discover.mjs` (Фаза 3): пара `{url, anchors}` на лінк, де `anchors` —
+ * АГРЕГОВАНІ тексти лінка (textContent + aria-label + title + img[alt] —
+ * іконковий лінк без видимого тексту читається саме звідси, Р3b).
+ *
+ * Джерел evidence три — рівно стільки ж значень має `source`: URL-патерни
+ * (`'url'`) й тексти якорів (`'anchor'`; словники — `classify-terms.mjs`)
+ * плюс структурний fan-out (`'structure'`, `classify-structure.mjs`,
+ * інкремент Б.3). 🔴 Окремого `'aria'` НЕМАЄ: aria-label агрегується в
+ * `anchors` ще на зборі лінків (вище), тож іконковий лінк без видимого
+ * тексту доводиться звичайним `'anchor'`. Збірка й ранжування пар
+ * (тип, url) — `classify-pairs.mjs`; тут лишається сама стратегія вибору.
+ *
+ * Шкала (Р3): кожен сигнал +2, поріг ≥2 — кожен сигнал сам закриває тип.
+ * Вибір — глобально-жадібний по всіх парах (type,url): перший
+ * непроконфліктований прохід відсортованого списку закриває і тип, і URL —
+ * програвший тип бере наступну свою пару нижче в списку (перепідбір —
+ * побічний ефект одного проходу, не окремий крок).
+ */
+import { analyzeStructure } from './classify-structure.mjs';
+import { OTHER_TYPES, rankedPairs } from './classify-pairs.mjs';
+
+/** Нормалізація pathname: без query/hash, без trailing slash, без `index.html` (Р3b). */
+export function normalizePathname(input) {
+  let pathname;
+  try {
+    pathname = new URL(input).pathname;
+  } catch {
+    pathname = input.split('#')[0].split('?')[0];
+  }
+  pathname = pathname.replace(/\/index\.html?$/i, '/');
+  if (pathname.length > 1) pathname = pathname.replace(/\/+$/, '');
+  return pathname || '/';
+}
+
+/**
+ * Згрупувати лінки за нормалізованим pathname з агрегацією ВСІХ якірних
+ * текстів (Р3b). 🔴 ОДНА реалізація на весь інструмент: `sitemap-links.mjs`
+ * будує з неї ж поле `links` пропозиції, і саме тому те поле є чесним
+ * записом входу класифікатора — включно зі стартовим pathname, який
+ * додається тут (сайт, що не лінкує сам на себе, інакше не мав би в наборі
+ * власної головної).
+ * @param {Array<{url: string, anchors?: string[]}>} links
+ * @param {string} startUrl
+ * @returns {Map<string, { url: string, anchors: Set<string> }>}
+ */
+export function groupLinksByPathname(links, startUrl) {
+  const candidates = new Map();
+  for (const link of links) {
+    const pathname = normalizePathname(link.url);
+    const texts = (link.anchors ?? []).map((a) => a.trim()).filter(Boolean);
+    const existing = candidates.get(pathname);
+    if (existing) texts.forEach((t) => existing.anchors.add(t));
+    else candidates.set(pathname, { url: link.url, anchors: new Set(texts) });
+  }
+  const startPathname = normalizePathname(startUrl);
+  if (!candidates.has(startPathname))
+    candidates.set(startPathname, { url: startUrl, anchors: new Set() });
+  return candidates;
+}
+
+/**
+ * Класифікувати лінки на типи сторінок.
+ * @param {Array<{url: string, anchors?: string[]}>} links
+ * @param {string} startUrl
+ * @param {Map<string, Set<string>>} [blockedPairs] пари (pathname → типи), уже
+ *   спростовані контент-пробом візиту (`lib/sitemap.mjs`); дефолт — порожньо
+ * @returns {{
+ *   pageTypes: Record<string, { url: string, score: number, evidence: Array<{urlPattern?: string, anchorMatch?: string, structural?: string, count?: number, source: 'url'|'anchor'|'structure'}> }>,
+ *   unresolved: Array<{ type: string, reason: 'no-candidate' }>,
+ * }}
+ */
+export function classifyLinks(links, startUrl, blockedPairs) {
+  const startPathname = normalizePathname(startUrl);
+  const candidates = groupLinksByPathname(links, startUrl);
+
+  const pageTypes = {};
+  const closedTypes = new Set(['home']);
+  const closedPathnames = new Set();
+
+  // home — окреме детерміноване правило: корінь, якщо він серед кандидатів, інакше стартовий URL.
+  const root = candidates.get('/');
+  if (root) {
+    pageTypes.home = {
+      url: root.url,
+      score: 2,
+      evidence: [{ urlPattern: '/', source: 'url' }],
+    };
+    closedPathnames.add('/');
+  } else {
+    pageTypes.home = { url: startUrl, score: 0, evidence: [{ source: 'url' }] };
+    closedPathnames.add(startPathname);
+  }
+
+  // Структурний розбір рахується по ПОВНОМУ набору кандидатів (разом із уже
+  // закритим коренем): форма сайту не залежить від того, який тип що забрав.
+  const structure = analyzeStructure(candidates);
+
+  for (const pair of rankedPairs(
+    candidates,
+    structure,
+    closedPathnames,
+    blockedPairs,
+  )) {
+    if (closedTypes.has(pair.type) || closedPathnames.has(pair.pathname))
+      continue;
+    pageTypes[pair.type] = {
+      url: pair.url,
+      score: pair.score,
+      evidence: pair.evidence,
+    };
+    closedTypes.add(pair.type);
+    closedPathnames.add(pair.pathname);
+  }
+
+  const unresolved = OTHER_TYPES.filter((type) => !closedTypes.has(type)).map(
+    (type) => ({
+      type,
+      reason: 'no-candidate',
+    }),
+  );
+
+  return { pageTypes, unresolved };
+}

package/skills/redesign-from-reference/scripts/lib/cli-entry.mjs

@@ -0,0 +1,22 @@
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Чи виконано модуль як CLI (`node <шлях>`), а не імпортовано з тестів.
+ *
+ * 🔴 Порівняння — через realpath: канонічний шлях запуску веде крізь симлінк
+ * `.claude/skills` → `.agents/skills`, а `import.meta.url` Node резолвить у
+ * РЕАЛЬНИЙ шлях — наївне ``file://${argv[1]}`` на симлінк-шляху хибне, і
+ * main() мовчки не викликався (exit 0 без жодного артефакту; спіймано
+ * лайв-тестом 2026-08-15). Realpath зрівнює обидві форми виклику.
+ */
+export function isCliEntry(metaUrl) {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return metaUrl === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    // Нерезолвний argv[1] (видалений файл тощо) — точно не наш CLI-запуск.
+    return false;
+  }
+}

package/skills/redesign-from-reference/scripts/lib/cluster.mjs

@@ -0,0 +1,95 @@
+/**
+ * Кластеризація колірних семплів за HSL-близькістю (Фаза 1, Р7 плану).
+ *
+ * Вхідні семпли — `{ value, frequency, area?, interactive? }`, де `value` —
+ * сирий CSS-колір (`#hex`/`rgb()`/`rgba()`, `lib/color.mjs`). Алгоритм
+ * жадібний (перший підхожий кластер за порядком вхідного масиву) — детермінізм
+ * тримається на тому, що вхідний масив сам детермінований (фікстура або
+ * `inspection.json`, зафіксовані на диску), а не на порядково-незалежній
+ * кластеризації.
+ */
+import { parseColor, rgbToHsl } from './color.mjs';
+
+/**
+ * Поріг кластеризації: сума трьох рівновагових відстаней — circular hue
+ * (0-180), saturation (0-100), lightness (0-100). 15 — емпіричний баланс:
+ * менше — близькі відтінки того самого елемента (напр. hover/active стан
+ * кнопки, антиаліасинг країв) лишаються окремими кластерами і засмічують
+ * `unmapped`; більше — різні поверхні (фон і картка) чи різні бренд-кольори
+ * (синій CTA і фіолетовий акцент) злипаються в один кластер і мапінг втрачає
+ * сигнал. Ахроматичні кольори (`s < 10%` — сірий/білий/чорний) кластеризуються
+ * ЛИШЕ за lightness: hue для них не визначено (без цього винятку білий і
+ * чорний з дрейфом hue не зливались би з власними відтінками взагалі).
+ */
+export const CLUSTER_THRESHOLD = 15;
+const GRAYSCALE_SATURATION = 10;
+
+function circularHueDistance(h1, h2) {
+  const diff = Math.abs(h1 - h2) % 360;
+  return diff > 180 ? 360 - diff : diff;
+}
+
+function hslDistance(a, b) {
+  const bothGray = a.s < GRAYSCALE_SATURATION && b.s < GRAYSCALE_SATURATION;
+  const hueDiff = bothGray ? 0 : circularHueDistance(a.h, b.h);
+  return hueDiff + Math.abs(a.s - b.s) + Math.abs(a.l - b.l);
+}
+
+/**
+ * Згрупувати колір-семпли, що потрапляють у той самий HSL-кластер.
+ *
+ * Кожен кластер несе `value`/`hsl` семпла з НАЙБІЛЬШОЮ частотою всередині
+ * себе (canonical pick — не усереднення, щоб значення лишалось реальним
+ * кольором зі сторінки), сумарну `frequency`/`area` і `interactive`, якщо
+ * хоч один злитий семпл був інтерактивним. Вивід відсортований за спаданням
+ * частоти, tie-break — зростання hue (Р7: стабільність незалежно від
+ * порядку елементів з однаковою частотою).
+ */
+export function clusterColors(samples, threshold = CLUSTER_THRESHOLD) {
+  const parsed = samples
+    .map((sample) => {
+      const rgb = parseColor(sample.value);
+      return rgb ? { ...sample, hsl: rgbToHsl(rgb) } : null;
+    })
+    .filter((sample) => sample !== null);
+
+  const clusters = [];
+
+  for (const sample of parsed) {
+    const match = clusters.find(
+      (c) => hslDistance(c.hsl, sample.hsl) <= threshold,
+    );
+    if (!match) {
+      clusters.push({
+        value: sample.value,
+        hsl: sample.hsl,
+        frequency: sample.frequency,
+        area: sample.area ?? 0,
+        interactive: Boolean(sample.interactive),
+        topFrequency: sample.frequency,
+      });
+      continue;
+    }
+
+    match.frequency += sample.frequency;
+    match.area += sample.area ?? 0;
+    match.interactive = match.interactive || Boolean(sample.interactive);
+    if (sample.frequency > match.topFrequency) {
+      match.topFrequency = sample.frequency;
+      match.value = sample.value;
+      match.hsl = sample.hsl;
+    }
+  }
+
+  // `topFrequency` — службове поле для вибору canonical-семпла (див. вище),
+  // назовні не віддаємо.
+  return clusters
+    .map((c) => ({
+      value: c.value,
+      hsl: c.hsl,
+      frequency: c.frequency,
+      area: c.area,
+      interactive: c.interactive,
+    }))
+    .sort((a, b) => b.frequency - a.frequency || a.hsl.h - b.hsl.h);
+}

package/skills/redesign-from-reference/scripts/lib/collect-links.mjs

@@ -0,0 +1,57 @@
+/**
+ * Збір лінків із уже завантаженої й прокрученої сторінки (задача §2.C.1,
+ * план Р4/Р3b): усі `a[href]` з DOM НЕЗАЛЕЖНО від видимості — бургер-меню з
+ * `display:none` теж має href-и в DOM (Р4). Тексти якоря агрегуються тут-таки,
+ * у браузерному контексті (textContent + aria-label + title + img[alt]
+ * усередині лінка) — Р3b, іконковий кошик без видимого тексту читається саме
+ * звідси; `classifyLinks` (Фаза 2) далі агрегує ці тексти по нормалізованому
+ * pathname з УСІХ входжень лінка на сторінці.
+ */
+
+/** Ліміт кількості лінків у виводі (Р4) — запобіжник для сторінок з тисячами href. */
+export const LINKS_LIMIT = 200;
+
+/**
+ * @param {import('@playwright/test').Page} page Уже завантажена й прокручена
+ *   (`scrollThrough`) сторінка.
+ * @returns {Promise<Array<{ url: string, anchors: string[] }>>}
+ */
+export async function collectLinks(page) {
+  const raw = await page.evaluate(() => {
+    return Array.from(document.querySelectorAll('a[href]')).map((a) => {
+      const imgAlts = Array.from(a.querySelectorAll('img[alt]')).map(
+        (img) => img.getAttribute('alt') || '',
+      );
+      const texts = [
+        a.textContent || '',
+        a.getAttribute('aria-label') || '',
+        a.getAttribute('title') || '',
+        ...imgAlts,
+      ]
+        .map((t) => t.trim())
+        .filter(Boolean);
+      // `a.href` (НЕ getAttribute) — браузер сам резолвить відносний href у
+      // абсолютний URL відносно поточного document.baseURI.
+      return { href: a.href, texts };
+    });
+  });
+
+  // Origin — з фактичного URL сторінки (після можливих редиректів), не з
+  // вхідного startUrl: same-origin фільтр має звірятись із тим, де ми
+  // реально опинились.
+  const origin = new URL(page.url()).origin;
+  const links = [];
+  for (const { href, texts } of raw) {
+    if (links.length >= LINKS_LIMIT) break;
+    let parsed;
+    try {
+      parsed = new URL(href);
+    } catch {
+      continue; // `javascript:`/биті href — не URL
+    }
+    if (parsed.origin !== origin) continue;
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') continue;
+    links.push({ url: parsed.href, anchors: texts });
+  }
+  return links;
+}

package/skills/redesign-from-reference/scripts/lib/color-tokens.mjs

@@ -0,0 +1,135 @@
+/**
+ * Мапінг ОДНОГО набору колір-семплів (світлого АБО темного) на підмножину
+ * `ThemeTokenValues` (задача §2.B.1, план Р4/Р7). Спільна логіка для `tokens`
+ * і `tokens.dark` — викликається з `map.mjs` двічі.
+ *
+ * Винесено окремо від `map.mjs`, щоб той лишався ≤150 рядків (канон файлу).
+ */
+import { contrastRatio, hslToRgb, hslTriple } from './color.mjs';
+import { clusterColors } from './cluster.mjs';
+import { collectUnmapped } from './unmapped.mjs';
+
+/** Поріг насиченості (%), нижче якого колір вважають ахроматичним (не акцентом). */
+const SAT_THRESHOLD = 20;
+/** Мінімальна різниця lightness (%) між `background` і `card` — інакше це той самий колір. */
+const MIN_CARD_GAP = 3;
+const WHITE_HSL = { h: 0, s: 0, l: 100 };
+
+function byRole(colors, role) {
+  return colors.filter((c) => c.role === role);
+}
+
+/** Частка `count` від `total`, округлена до сотих (0 при порожньому знаменнику). */
+function ratio(count, total) {
+  return total > 0 ? Math.round((count / total) * 100) / 100 : 0;
+}
+
+/** Обрати білий чи «чорнильний» (текстовий) колір — той, що дає вищий контраст на `base`. */
+function pickForeground(baseHsl, inkHsl) {
+  const baseRgb = hslToRgb(baseHsl);
+  const whiteRatio = contrastRatio(baseRgb, hslToRgb(WHITE_HSL));
+  const inkRatio = inkHsl ? contrastRatio(baseRgb, hslToRgb(inkHsl)) : 0;
+  return whiteRatio >= inkRatio ? WHITE_HSL : inkHsl;
+}
+
+/** Записати акцентний токен + його `-foreground` + опційний дзеркальний ключ (secondary↔accent). */
+function applyAccent(tokens, key, cluster, fgHsl, mirrorKey) {
+  tokens[key] = hslTriple(cluster.hsl);
+  tokens[`${key}-foreground`] = hslTriple(pickForeground(cluster.hsl, fgHsl));
+  if (mirrorKey) {
+    tokens[mirrorKey] = tokens[key];
+    tokens[`${mirrorKey}-foreground`] = tokens[`${key}-foreground`];
+  }
+}
+
+/**
+ * Мапити семпли → `{ tokens, confidence, unmapped }` (підмножина `ThemeTokenValues`).
+ *
+ * Явний JSDoc-тип — щоб TS (`allowJs`, споживання з `.test.ts`) не звужував
+ * тип `tokens` до лише тих ключів, які видно у прямих присвоєннях: ключі,
+ * дописані через `applyAccent` (динамічний `tokens[key] = …`), інакше
+ * лишились би невидимими для структурної інференції.
+ * @returns {{ tokens: Record<string, string>, confidence: Record<string, number>,
+ *   unmapped: import('./unmapped.mjs').UnmappedEntry[] }}
+ */
+export function mapColorTokens(colors) {
+  const bgClusters = clusterColors(byRole(colors, 'background'));
+  const textClusters = clusterColors(byRole(colors, 'text'));
+  const borderClusters = clusterColors(byRole(colors, 'border'));
+  const totalOf = (clusters) =>
+    clusters.reduce((sum, c) => sum + c.frequency, 0);
+
+  const tokens = {};
+  const confidence = {};
+  // `used` тримає ПОСИЛАННЯ на кластери, не рядкові значення: однаковий hex у
+  // різних ролях (темний текст = темний фон секції) — це РІЗНІ кластери, і
+  // дедуп за значенням мовчки губив би другий із них і з tokens, і з unmapped.
+  const used = new Set();
+  const pick = (clusters, predicate = () => true) =>
+    clusters.find((c) => predicate(c) && !used.has(c)) ?? null;
+
+  const bg = pick(bgClusters);
+  if (bg) {
+    tokens.background = hslTriple(bg.hsl);
+    confidence.background = ratio(bg.frequency, totalOf(bgClusters));
+    used.add(bg);
+  }
+
+  const fg = pick(textClusters);
+  if (fg) {
+    tokens.foreground = hslTriple(fg.hsl);
+    confidence.foreground = ratio(fg.frequency, totalOf(textClusters));
+    used.add(fg);
+  }
+
+  // «Насичений акцент на інтерактивних елементах → primary»; ring дзеркалить
+  // primary. Акценти резервуються ДО card: інакше частотний CTA-колір (та сама
+  // кнопка на кожній картці каталогу) діставався б card як «наступна
+  // поверхня», і primary зникав би з пропозиції без сліду.
+  const interactive = bgClusters.filter((c) => c.interactive);
+  const primary = pick(
+    bgClusters,
+    (c) => c.interactive && c.hsl.s >= SAT_THRESHOLD,
+  );
+  if (primary) {
+    applyAccent(tokens, 'primary', primary, fg?.hsl, null);
+    tokens.ring = tokens.primary;
+    confidence.primary = ratio(primary.frequency, totalOf(interactive));
+    used.add(primary);
+  }
+
+  // «Другорядний → accent/secondary» — наступний насичений колір (без вимоги interactive).
+  const secondary = pick(bgClusters, (c) => c.hsl.s >= SAT_THRESHOLD);
+  if (secondary) {
+    applyAccent(tokens, 'secondary', secondary, fg?.hsl, 'accent');
+    confidence.secondary = ratio(secondary.frequency, totalOf(bgClusters));
+    used.add(secondary);
+  }
+
+  const card = pick(bgClusters); // «поверхні → card»: наступна background-поверхня
+  if (card && (!bg || Math.abs(card.hsl.l - bg.hsl.l) >= MIN_CARD_GAP)) {
+    tokens.card = hslTriple(card.hsl);
+    if (fg) tokens['card-foreground'] = hslTriple(fg.hsl);
+    tokens.popover = tokens.card;
+    if (fg) tokens['popover-foreground'] = tokens['card-foreground'];
+    used.add(card);
+  }
+
+  const border = pick(borderClusters);
+  if (border) {
+    tokens.border = hslTriple(border.hsl);
+    tokens.input = tokens.border;
+    confidence.border = ratio(border.frequency, totalOf(borderClusters));
+    used.add(border);
+  }
+
+  // Р7: `unmapped` — не голий список hex, а записи з роллю, частотою, площею
+  // і контрастом на обох запропонованих поверхнях (`lib/unmapped.mjs`).
+  const unmapped = collectUnmapped(
+    { background: bgClusters, text: textClusters, border: borderClusters },
+    used,
+    tokens,
+  );
+
+  return { tokens, confidence, unmapped };
+}

package/skills/redesign-from-reference/scripts/lib/color.mjs

@@ -0,0 +1,150 @@
+/**
+ * Колірна математика для design-import (Фаза 1, Р1/Р2 плану).
+ *
+ * Нуль зовнішніх залежностей (Р2): власний парсинг CSS-кольорів, конвертація
+ * RGB↔HSL і WCAG-контраст. Приймаються ЛИШЕ формати, які реально повертає
+ * `getComputedStyle` у Chromium — `#hex` (у розмітці фікстур) та `rgb()`/
+ * `rgba()` (те, що бачить `inspect.mjs` у браузері). Сучасний CSS Color 4
+ * синтаксис (пробіли замість ком) свідомо НЕ підтримується — інспекція
+ * завжди йде через браузер, а не парсить чужий CSS-текст (YAGNI).
+ */
+
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB_RE =
+  /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/i;
+/** Формат токена (`packages/simplycms/src/themes/types.ts`): `"H S% L%"` без `hsl()`. */
+const HSL_TRIPLE_RE = /^(\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%$/;
+
+function expandHex(hex) {
+  if (hex.length > 4) return hex; // HEX_RE лишає рівно {3,4,6,8}
+  return hex
+    .split('')
+    .map((c) => c + c)
+    .join('');
+}
+
+/** Розпарсити CSS-колір (`#hex`, `rgb()`, `rgba()`) → `{ r, g, b, a }` (0-255, a 0-1). */
+export function parseColor(input) {
+  if (typeof input !== 'string') return null;
+  const value = input.trim();
+
+  const hexMatch = HEX_RE.exec(value);
+  if (hexMatch) {
+    const hex = expandHex(hexMatch[1].toLowerCase());
+    return {
+      r: parseInt(hex.slice(0, 2), 16),
+      g: parseInt(hex.slice(2, 4), 16),
+      b: parseInt(hex.slice(4, 6), 16),
+      a: hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1,
+    };
+  }
+
+  const rgbMatch = RGB_RE.exec(value);
+  if (rgbMatch) {
+    const [, r, g, b, a] = rgbMatch;
+    return {
+      r: Number(r),
+      g: Number(g),
+      b: Number(b),
+      a: a === undefined ? 1 : Number(a),
+    };
+  }
+
+  return null;
+}
+
+/** RGB (0-255) → HSL, округлено до цілих (конвенція `themes/default/tokens.ts`). */
+export function rgbToHsl({ r, g, b }) {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+
+  if (max === min) {
+    return { h: 0, s: 0, l: Math.round(l * 100) };
+  }
+
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === rn) h = (gn - bn) / d + (gn < bn ? 6 : 0);
+  else if (max === gn) h = (bn - rn) / d + 2;
+  else h = (rn - gn) / d + 4;
+  h *= 60;
+
+  return { h: Math.round(h), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+/** HSL → RGB (0-255, цілі) — зворотна конвертація для контраст-перевірки. */
+export function hslToRgb({ h, s, l }) {
+  const sn = s / 100;
+  const ln = l / 100;
+
+  if (sn === 0) {
+    const gray = Math.round(ln * 255);
+    return { r: gray, g: gray, b: gray };
+  }
+
+  const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+  const p = 2 * ln - q;
+  const hue2rgb = (t0) => {
+    let t = t0;
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+
+  const hn = h / 360;
+  return {
+    r: Math.round(hue2rgb(hn + 1 / 3) * 255),
+    g: Math.round(hue2rgb(hn) * 255),
+    b: Math.round(hue2rgb(hn - 1 / 3) * 255),
+  };
+}
+
+/** RGB (0-255) → канонічний `#rrggbb` (Р7: ключ дедупу `unmapped`). */
+export function rgbToHex({ r, g, b }) {
+  const channel = (v) => Math.round(v).toString(16).padStart(2, '0');
+  return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+
+/** Форматувати HSL у рядок-токен `"H S% L%"`. */
+export function hslTriple({ h, s, l }) {
+  return `${h} ${s}% ${l}%`;
+}
+
+/** Розпарсити рядок-токен `"H S% L%"` → `{ h, s, l }`, або `null`, якщо формат інший. */
+export function parseHslTriple(value) {
+  if (typeof value !== 'string') return null;
+  const match = HSL_TRIPLE_RE.exec(value.trim());
+  if (!match) return null;
+  return { h: Number(match[1]), s: Number(match[2]), l: Number(match[3]) };
+}
+
+function channelLuminance(channel) {
+  const cs = channel / 255;
+  return cs <= 0.03928 ? cs / 12.92 : ((cs + 0.055) / 1.055) ** 2.4;
+}
+
+/** Відносна яскравість за формулою WCAG 2.x (для контраст-відношення). */
+export function relativeLuminance({ r, g, b }) {
+  return (
+    0.2126 * channelLuminance(r) +
+    0.7152 * channelLuminance(g) +
+    0.0722 * channelLuminance(b)
+  );
+}
+
+/** Контраст-відношення WCAG (1..21) між двома RGB-кольорами. */
+export function contrastRatio(rgbA, rgbB) {
+  const lA = relativeLuminance(rgbA);
+  const lB = relativeLuminance(rgbB);
+  const lighter = Math.max(lA, lB);
+  const darker = Math.min(lA, lB);
+  return (lighter + 0.05) / (darker + 0.05);
+}

package/skills/redesign-from-reference/scripts/lib/contrast.mjs

@@ -0,0 +1,57 @@
+/**
+ * WCAG-контраст пар `*`/`*-foreground` (Фаза 1, задача §2.B.3).
+ *
+ * Скрипт нічого не «виправляє» — лише чесно повідомляє провалені пари;
+ * рішення лишається за агентом + користувачем (Р7 плану).
+ */
+import { contrastRatio, hslToRgb, parseHslTriple } from './color.mjs';
+
+/** WCAG AA поріг контрасту для тексту (задача §2.B.3). */
+export const AA_MIN_RATIO = 4.5;
+
+/**
+ * Канонічні пари `*`/`*-foreground` контракту тем
+ * (`packages/simplycms/src/themes/types.ts`, 23 кольорові ключі). `border`/
+ * `input`/`ring` пари не мають — контракт не визначає для них `-foreground`.
+ */
+export const CONTRAST_PAIRS = [
+  ['background', 'foreground'],
+  ['card', 'card-foreground'],
+  ['popover', 'popover-foreground'],
+  ['primary', 'primary-foreground'],
+  ['secondary', 'secondary-foreground'],
+  ['muted', 'muted-foreground'],
+  ['accent', 'accent-foreground'],
+  ['destructive', 'destructive-foreground'],
+  ['success', 'success-foreground'],
+  ['warning', 'warning-foreground'],
+];
+
+/**
+ * Перевірити контраст пар, присутніх у `values` (`ThemeTokenValues`-подібний
+ * обʼєкт). Пари з відсутнім чи нерозпізнаним значенням мовчки пропускаються —
+ * це не помилка формату, а просто ще не мапований токен.
+ *
+ * `prefix` дозволяє позначити попередження від `dark`-блоку (напр.
+ * `"dark:"`) без дублювання логіки для світлого/темного набору.
+ */
+export function checkContrastPairs(values, prefix = '') {
+  const warnings = [];
+
+  for (const [baseKey, fgKey] of CONTRAST_PAIRS) {
+    const baseHsl = parseHslTriple(values?.[baseKey]);
+    const fgHsl = parseHslTriple(values?.[fgKey]);
+    if (!baseHsl || !fgHsl) continue;
+
+    const ratio = contrastRatio(hslToRgb(baseHsl), hslToRgb(fgHsl));
+    if (ratio < AA_MIN_RATIO) {
+      warnings.push({
+        pair: `${prefix}${baseKey}/${fgKey}`,
+        ratio: Math.round(ratio * 100) / 100,
+        required: AA_MIN_RATIO,
+      });
+    }
+  }
+
+  return warnings;
+}