dsh-desktop-kit 0.0.0-stage → 2.0.0

package/skills/wow-design/references/stack-recipes.md

@@ -0,0 +1,96 @@
+# Stack Recipes — как встраивать AURORA в реальные проекты
+
+> Часть навыка wow-design. ≈2.3k токенов. Читать, когда: встраиваешь кит в React/Laravel/Bitrix
+> или статический HTML.
+
+> Принцип: **не переписывай проект, а перенеси токены и компоненты**. Сначала посмотри, что уже есть
+> (тема, переменные, UI-кит), и замапь новое на существующее. Ничего не ломать — часть дизайна.
+
+## Универсальный перенос (любой стек)
+1. Скопируй из `assets/kit/assets/css/`: `tokens.css`, `base.css`, `fonts.css` (и при необходимости `components.css`).
+2. Подключи первыми в каскаде: `tokens → base → components → styles проекта`.
+3. Если в проекте уже есть CSS-переменные — замапь:
+   ```css
+   :root{
+     --brand-accent: var(--accent);
+     --surface-page: var(--bg);
+     --text-primary: var(--ink);
+     --radius-md: var(--radius-card);
+   }
+   ```
+4. Проверь, что ни один компонент проекта не использует «магические» цвета — замени на токены постепенно.
+5. Тёмная тема: переключай `data-theme` на `<html>`; в проекте может быть свой механизм (class/`prefers-color-scheme`) —
+   адаптируй, а не дублируй две системы.
+
+## React + Vite (+ Tailwind, если есть)
+- **Токены:** `src/styles/tokens.css` + `base.css` импортируются в `main.tsx`/`index.css`.
+- **Tailwind v4:** в CSS вместо `tailwind.config`:
+  ```css
+  @import "tailwindcss";
+  @theme {
+    --color-bg: var(--bg);
+    --color-surface: var(--surface);
+    --color-ink: var(--ink);
+    --color-accent: var(--accent);
+    --color-line: var(--line);
+    --font-display: var(--font-display);
+    --font-sans: var(--font-body);
+    --radius-card: var(--radius-card);
+  }
+  ```
+  Тогда работают классы `bg-surface`, `text-ink`, `border-line`, `font-display`, `rounded-card`.
+- **Компоненты:** один каталог `src/components/ui` (Button, Input, Select, Badge, Card, Table, Modal, Tabs,
+  Toast, EmptyState). Варианты — через пропсы/`data-variant`, состояния — `data-state`, не через десятки классов.
+- **Тёмная тема:** `useEffect` ставит `data-theme` на `document.documentElement`, значение в `localStorage`,
+  первый рендер — из `prefers-color-scheme`.
+- **Проверка:** `npm run dev` → `capture.mjs http://localhost:5173` (или нужный роут) + `audit.mjs`.
+- **Тесты:** RTL — проверка доступных имён кнопок/полей, axe в Playwright/`vitest-axe`; скриншоты —
+  `toHaveScreenshot` для ключевых экранов (опционально, если проект уже на Playwright).
+- **Не тащи** тяжёлые UI-библиотеки ради дизайна: сначала токены и свои 8–12 компонентов.
+
+## Laravel + Blade
+- **Стили:** `resources/css/tokens.css`, `base.css`, `fonts.css`; `resources/css/app.css` импортирует их;
+  `vite.config.js` уже собирает `app.css`. Шрифты — `resources/fonts/`, пути в `@font-face` относительные.
+- **Layout:** `resources/views/layouts/app.blade.php` — `<html lang="ru" data-theme="{{ $theme ?? 'light' }}">`,
+  `@vite(['resources/css/app.css','resources/js/app.js'])`, skip-link, header/footer partials.
+- **Blade-компоненты:** `resources/views/components/ui/button.blade.php`:
+  ```blade
+  @props(['variant' => 'primary', 'size' => 'md', 'type' => 'button'])
+  <button type="{{ $type }}" {{ $attributes->class(['btn', "btn--$variant", "btn--$size"]) }}>
+    {{ $slot }}
+  </button>
+  ```
+  Аналогично input/select/badge/card/table/empty/modal. Никаких inline-стилей.
+- **Существующая вёрстка:** не заменяй весь шаблон. Добавь `resources/css/redesign.css` **после** старых стилей,
+  переопределяй только проблемные компоненты; проверь все основные страницы.
+- **Проверка:** `npm run build`, `php artisan serve`, скриншоты ключевых страниц (логин, список, карточка,
+  формы, ошибки), обе темы. PHPUnit/фича-тесты не должны упасть — дизайн не меняет логику.
+- **Blade-подводные камни:** экранирование в атрибутах, `@class([...])`, не ломать `old()`/`@error` в формах,
+  CSRF остаётся, не переносить формы на JS без причины.
+
+## Bitrix / Aspro («Медицинский центр 3.0» и др.)
+- **Где править:** только `local/` (свой шаблон/компоненты) или кастомные файлы шаблона сайта;
+  **не** трогать `/bitrix/` ядро и файлы маркетплейс-шаблона, которые перезапишутся обновлением.
+- **CSS:** обычно `.../local/templates/<template>/styles/custom.css` или `template_styles.css`;
+  подключай токены через `init.php`/`<link>`; селекторы скоупи под контейнер страницы
+  (`.page-<name> .btn { ... }`), чтобы не сломать другие разделы и админку.
+- **Шрифты:** положи в `local/templates/<template>/fonts/` и подключи `@font-face` с относительными путями;
+  не тяни с CDN, если сайт работает в закрытом контуре.
+- **Кэш:** после правок CSS/шаблонов чистить кэш (`Настройки → Очистить кэш` или удалить
+  `/bitrix/cache/css/s1/<template>/`), иначе увидишь старое.
+- **Проверка:** открыть живую страницу в браузере (desktop/mobile), проверить другие разделы (шапка/футер общие),
+  админку не задеть. Для локальных наработок — статический HTML-снимок страницы.
+- **Аспро-подводные камни:** свои классы `.btn`, `.card`, `--palette-*`, вложенные `.wrapper`/`.maxwidth`;
+  проверяй каскад и `!important` (лучше без него), не ломай мобильное меню и попапы.
+- **Контент:** заголовки h3 в анкетах/статьях не менять на h2 без необходимости — SEO-структура важна.
+
+## Статический HTML (лендинг/прототип)
+- Скопируй папку `assets/kit` → в проект; замени контент и бренд-акцент; оставь структуру и токены.
+- Проверь `file://` (нет сборки): относительные пути, шрифты локально, никаких fetch/CDN.
+- Дальше — `capture.mjs`/`audit.mjs`, скриншоты, правки по рубрике.
+
+## Что считать «интеграцией» в отчёте
+- Какие файлы добавлены/изменены (точные пути).
+- Какие токены/переменные замаплены на существующую тему.
+- Какие экраны проверены скриншотами (desktop/mobile, light/dark).
+- Что не тронуто (логика, БД, роуты, чужие компоненты).

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

@@ -0,0 +1,82 @@
+# Visual QA — петля «собрал → снял → раскритиковал → исправил»
+
+> Часть навыка wow-design. ≈1.7k токенов. Читать, когда: запускаешь capture/audit, разбираешь
+> скриншоты, настраиваешь CI или скрипты не стартуют.
+
+> Без скриншотов дизайн не считается проверенным. Глазами по 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`), в ревью смотри диффы.

package/skills/wow-design/references/wow-levers.md

@@ -0,0 +1,43 @@
+# Рычаги «ВАУ» — 8 приёмов с параметрами
+
+> Часть навыка wow-design. ≈1k токенов. Читать, когда: выбираешь 3–5 приёмов «ВАУ» для страницы
+> и нужны конкретные параметры, чтобы приём не превратился в декор.
+
+Выбирай **3–5 из 8**, не все сразу. Каждый приём должен работать на задачу экрана, а не «чтобы было красиво».
+
+## 1. Типографический контраст — 80% впечатления
+Огромный serif-display + мелкий капс-лейбл с трекингом + спокойный body. Display 56–96px
+(`clamp(3rem,7vw,6rem)`), лейблы 11–12px капсом с трекингом `.12–.14em`, body 16–18px.
+Одна display-пара на страницу; не смешивать два похожих гротеска.
+
+## 2. Редакционная сетка
+Асимметрия 7/5 или 8/4, номерные секции (01/02/03), волосяные линии, поля-воздух. Контейнер
+1200–1360px, 12 колонок, gutter `clamp(20px,4.5vw,56px)`; секции `clamp(64px,8vw,128px)`.
+Сетка должна читаться по краям: всё выровнено по одной линии.
+
+## 3. Одна смелая деталь
+Гигантская цифра/буква, эмблема, вертикальный текст, необычный разделитель — **ровно одна**,
+повторённая в 2–3 местах. Пять «фишек» сразу (градиент + блоб + стекло + 3D + карусель) = шум.
+
+## 4. Материальность
+Тёплая бумага, лёгкое зерно 2–3% (`--grain-opacity:.022`), hairline-бордеры, слоистые тени из
+2 слоёв, без «пластика». Статичные карточки — hairline, тени только у всплывающих слоёв.
+
+## 5. Точные данные
+SVG-графики, sparklines, таблицы с `font-variant-numeric:tabular-nums`, моно-цифры для ID и кодов,
+правые числа. Точность и выравнивание цифр читаются как «дорого» даже без декора.
+
+## 6. Микродетали
+Offset у подчёркиваний, цвет `::selection`, аккуратный скроллбар, видимое фокус-кольцо
+(`2px` + offset `3px`), иконки stroke 1.5–1.6, оптическое выравнивание иконок в строке.
+Мелочи не объясняют — они создают ощущение качества.
+
+## 7. Движение с достоинством
+Reveal 700ms `cubic-bezier(.16,1,.3,1)`, stagger 60ms, hover 180ms; только `transform`/`opacity`.
+Без bounce, parallax-цирка и бесконечных анимаций. `prefers-reduced-motion` отключает всё,
+контент остаётся видимым.
+
+## 8. Копирайт
+Глаголы, конкретика, числа, польза. Заголовок продаёт результат, а не описывает отдел:
+«Запись к кардиологу за 2 минуты», «94% заявок закрыты в SLA». Без «инновационных решений»
+и «команды профессионалов».

package/tools/skill-cost.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Token budget report for the bundled skills.
+//
+// Every SKILL.md is loaded whole when the model calls `skill`, so the core file
+// is a hard context cost. This script prints that cost and fails CI when a core
+// crosses the budget, which keeps the library honest as it grows.
+//
+//   node tools/skill-cost.mjs            table + totals
+//   node tools/skill-cost.mjs --json     machine-readable report
+//   node tools/skill-cost.mjs --check     exit 1 when a core exceeds --budget
+import fs from "node:fs";
+import path from "node:path";
+
+const repoRoot = path.resolve(import.meta.dirname, "..");
+const skillsRoot = path.join(repoRoot, "skills");
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const check = args.includes("--check");
+const budgetIndex = args.indexOf("--budget");
+const budget = budgetIndex >= 0 ? Number(args[budgetIndex + 1]) || 6000 : 6000;
+
+const rows = [];
+for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+  if (!entry.isDirectory()) continue;
+  const file = path.join(skillsRoot, entry.name, "SKILL.md");
+  if (!fs.existsSync(file)) continue;
+  const text = fs.readFileSync(file, "utf8");
+  const bytes = Buffer.byteLength(text, "utf8");
+  let references = 0;
+  let referenceBytes = 0;
+  const refDir = path.join(skillsRoot, entry.name, "references");
+  if (fs.existsSync(refDir)) {
+    for (const reference of fs.readdirSync(refDir, { withFileTypes: true })) {
+      if (!reference.isFile()) continue;
+      references += 1;
+      referenceBytes += fs.statSync(path.join(refDir, reference.name)).size;
+    }
+  }
+  rows.push({
+    name: entry.name,
+    bytes,
+    tokens: Math.round(bytes / 3.2),
+    references,
+    referenceTokens: Math.round(referenceBytes / 3.2),
+  });
+}
+rows.sort((left, right) => right.tokens - left.tokens);
+
+const totalTokens = rows.reduce((sum, row) => sum + row.tokens, 0);
+const totalReferences = rows.reduce((sum, row) => sum + row.referenceTokens, 0);
+const over = rows.filter((row) => row.tokens > budget);
+
+if (json) {
+  console.log(JSON.stringify({ budget, totalTokens, totalReferences, rows, over }, null, 2));
+} else {
+  console.log(`Навыков: ${rows.length}. Ядра: ${totalTokens} токенов, references: ${totalReferences} токенов.`);
+  console.log(`Бюджет ядра: ${budget} токенов${over.length > 0 ? ` · превышают: ${over.length}` : " · все в бюджете"}`);
+  console.log("");
+  const header = ["навык", "ядро", "токены", "refs", "ref-токены"].map((label, index) => label.padEnd(index === 0 ? 30 : 10));
+  console.log(header.join(""));
+  for (const row of rows) {
+    const mark = row.tokens > budget ? " !" : "";
+    console.log([
+      (row.name + mark).padEnd(30),
+      String(row.bytes + " Б").padEnd(10),
+      String(row.tokens).padEnd(10),
+      String(row.references).padEnd(10),
+      String(row.referenceTokens).padEnd(10),
+    ].join(""));
+  }
+}
+
+if (check && over.length > 0) {
+  console.error(`\nПеребор бюджета: ${over.map((row) => `${row.name} (${row.tokens})`).join(", ")}`);
+  process.exit(1);
+}