dsh-desktop-kit 0.0.0-stage → 1.0.0

package/skills/testing-strategy/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: testing-strategy
+description: "Универсальная стратегия тестирования — пирамида, герметичность, baseline, E2E/UI, визуальные снапшоты, доступность, CI."
+whenToUse: "Перед любой правкой кода и при выборе, чем и как тестировать; при настройке тестов в новом проекте."
+user-invocable: true
+---
+
+# Стратегия тестирования (любой проект)
+
+## Пирамида
+1. **Unit** — чистая логика, быстрые, без БД/сети.
+2. **Feature/интеграционные** — HTTP/сценарии, валидация, права; на **той же СУБД, что прод** (герметичная тестовая БД).
+3. **E2E/UI** — Playwright: вход, ключевые сценарии, ошибки форм, кросс-браузерность (минимально — Chromium).
+4. **Визуальные** — скриншоты ключевых экранов (`toHaveScreenshot`), фиксируют регрессии вёрстки.
+5. **Доступность** — axe-core в Playwright: контраст, aria, клавиатура.
+6. **Дымовые (smoke)** — 5–10 быстрых проверок после деплоя.
+
+## Правила
+- **Baseline до правки:** зафиксировать число тестов/assertion и падения; после — сравнить (не ухудшилось).
+- **Герметичность:** тесты не зависят от боевого `.env`, внешней сети и текущей даты; БД — отдельная.
+- Тест проверяет **поведение**, а не реализацию; не ходит в приватные методы.
+- Новый баг → сначала воспроизводящий тест (падает), затем фикс (проходит).
+- Flaky-тесты не игнорировать: искать гонку/время/данные, а не повторять.
+- Тесты должны быть быстрыми: без сна, без реальных писем/очередей (mail/queue — fake/array).
+- Отсутствующие необязательные файлы/сервисы — `skip` с внятной причиной, не падение.
+
+## Минимум для новой фичи
+- Feature-тест основного сценария + тест прав (админ/пользователь/гость).
+- Тест валидации и граничных случаев.
+- Unit для выделенной логики.
+- E2E/скриншот для UI-изменений.
+
+## CI (порядок шагов)
+1. `php -l`/сборка/линтер → 2. статанализ → 3. unit+feature на реальной СУБД → 4. E2E на поднятом стенде → 5. артефакты (скриншоты/логи) при падении.
+
+## Отчёт о проверках
+- Что запускал (команды), сколько тестов/assertion, что упало/скипнулось и почему, что проверено руками/скриншотами.

package/skills/ui-design-system/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ui-design-system
+description: "Универсальные правила интерфейса — дизайн-токены, компоненты, состояния, адаптивность, темы, доступность и визуальная проверка."
+whenToUse: "Любая работа с интерфейсом: новая страница, правка вёрстки/стилей, дизайн-апгрейд, проверка UX."
+user-invocable: true
+---
+
+# UI/UX и дизайн-система (универсально)
+
+> **Для WOW-уровня** (лендинги, дашборды, брендинг, «сделай красиво», дизайн-апгрейд) сначала загрузи
+> `wow-design` — там арт-направление AURORA, 5 пресетов, дизайн-кит, эталонные страницы и петля
+> скриншот-критики. Для аудита готового UI — `design-critique`. Этот скилл — универсальный минимум.
+
+## База
+- **Токены**, а не магические числа: цвета, отступы, радиусы, типографика, тени — в переменных/CSS-токенах.
+- **Компоненты**: кнопки, поля, селекты, бейджи, карточки, таблицы, модалки, уведомления — единый вид и поведение.
+- **Состояния обязательны:** default, hover, focus-visible, active, disabled, loading, empty, error.
+- **Сетка и ритм**: одна шкала отступов (4/8/12/16/24/32), выравнивание, максимум ширины контента.
+- **Типографика**: 2–3 размера основной шкалы, читаемая строка (60–75 символов), понятная иерархия.
+
+## UX
+- Один главный сценарий на экран; действия — заметные, в конце пути взгляда.
+- Подписи и подсказки — человеческим языком; ошибки — рядом с полем и с решением.
+- Пустые состояния: объяснить, что здесь будет и что сделать.
+- Не заставлять запоминать: подсказки, значения по умолчанию, автосохранение.
+- Скорость: не блокировать интерфейс, показывать прогресс/скелетоны.
+
+## Адаптивность
+- 3 точки: mobile (≤560), tablet (≤960), desktop (>960); проверить 360/390/768/1440.
+- Таблицы — горизонтальный скролл в контейнере, а не «поехавшая» страница; кнопки на mobile — на всю ширину.
+- Тач-цели ≥ 40–44px; не полагаться на hover для важных действий.
+
+## Темы и доступность
+- Светлая/тёмная/контрастная: контраст текста ≥ 4.5:1, не «зашивать» цвета в разметку.
+- Keyboard-first: focus-visible, Tab-порядок, Escape закрывает, aria-атрибуты у иконок/модалок.
+- Не только цветом: состояния дублировать текстом/иконкой.
+
+## Проверка
+- Playwright-скриншоты ключевых экранов (desktop+mobile, обе темы) «до/после».
+- axe-core: критичные нарушения доступности = 0.
+- Проверить длинные тексты, кириллицу, числа, переполнение, ошибки сети.
+
+## «ВАУ» без вреда
+- Спокойная палитра, аккуратные акценты, микроанимации 120–200мс только на действиях.
+- Красота не должна снижать скорость/читаемость; сначала ясность, потом эффекты.

package/skills/web-research/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: web-research
+description: "Живой поиск в интернете в реальном времени: находить актуальные факты, новости, цены, версии, законы и документацию, проверять по источникам и цитировать ссылки."
+whenToUse: "Когда нужны свежие/внешние данные: новости, «что сейчас», цены, версии ПО, изменения законов, документация, конкуренты, проверка факта; а также по просьбе «поищи в интернете»."
+user-invocable: true
+---
+
+# Живой веб-поиск (реальное время)
+
+## Когда обязательно
+- Вопрос про **сейчас/сегодня/последние** изменения, новости, курсы, цены, релизы, версии, тарифы.
+- Проверка факта, цитаты, даты, имени, закона, медицинской/юридической нормы.
+- Актуальная документация библиотеки/сервиса перед кодом (версии API, breaking changes).
+- Конкуренты/рынок для SEO и контента; свежие исследования для статьи.
+
+## Процесс
+1. **Сформулируй 2–4 запроса** (рус/англ; синонимы; официальные термины). Для версий — `site:`/официальный домен.
+2. `web_search` → выбери 2–3 **независимых** источника, начни с официальных (docs, .gov, производитель, крупные СМИ).
+3. `web_fetch` — открой ключевые страницы целиком, если нужен контекст/детали; не полагайся только на сниппеты.
+4. **Сверь** минимум два источника; расхождения — покажи оба и объясни.
+5. Зафиксируй **дату поиска** и дату публикации источника. Свежесть: по умолчанию — не старше 12 месяцев (если не историческая справка).
+6. В ответе — **ссылки markdown** и пометка «актуально на YYYY-MM-DD». Не выдумывай URL/цифры.
+
+## Правила достоверности
+- Отличай **факт** от мнения/маркетинга; для медицины/юридических норм — только официальные источники (Минздрав, Росздравнадзор, законы) и осторожные формулировки.
+- Если источник платный/закрыт — так и скажи; не выдавай пересказ за первоисточник.
+- Если поиск не дал результата — честно сообщи и предложи уточнить запрос; не заполняй пробел догадкой.
+- Не используй устаревшие данные без предупреждения; при смене версии/цены — укажи оба значения и даты.
+
+## Формат ответа
+1. Короткий вывод (1–3 предложения).
+2. Детали с датами/версиями.
+3. «Источники:» — список ссылок (title + URL), дата публикации, если известна.
+4. «Актуально на: YYYY-MM-DD».
+
+## Связка с другими скиллами
+- `content-writing` — факты и цитаты только после `web-research`, со ссылками в черновике.
+- `seo` — свежая семантика/конкуренты/тренды и проверка выдачи.
+- `php-laravel`, `javascript-typescript`, `bitrix-aspro` — сверять версии и API с официальной документацией.
+- `requirements-and-planning` — рыночные/правовые вводные подтверждать источниками.

package/skills/wow-design/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: wow-design
+description: "Дизайн-директор уровня топового web-UI дизайнера: арт-направление, токены, композиция, типографика, петля скриншот-критики. Использовать перед ЛЮБОЙ вёрсткой/дизайном интерфейса."
+whenToUse: "Любая задача, где создаётся или меняется внешний вид интерфейса: новая страница, лендинг, дашборд, форма, компоненты, темы, адаптив, дизайн-апгрейд, «сделай красиво». Загружать ДО первой строки HTML/CSS."
+user-invocable: true
+---
+
+# WOW-DESIGN — дизайн-директор
+
+> Ты — старший web-UI дизайнер с 40-летним опытом и безупречным вкусом.
+> Твой результат должен выглядеть дорого и уместно **с первого раза**, а не после десяти правок.
+> Красота здесь — не украшение, а ясность, иерархия и доверие. ВАУ без потери удобства.
+
+## 0. КОНТРАКТ (нарушать нельзя)
+
+1. **Не начинай вёрстку без арт-направления.** Сначала 5–10 минут на «Design Brief» (шаблон: `references/design-brief-template.md`):
+   аудитория, задача экрана, 3 слова настроения, 1–2 референса, 1 анти-референс, палитра/пресет, шрифт, signature-деталь.
+2. **Никогда не изобретай палитру и типографику с нуля**, если нет сильного бренд-контекста. Бери дизайн-кит:
+   `assets/kit/` — токены, компоненты, 5 пресетов, локальные шрифты. Адаптируй только акцент/шрифт под бренд.
+3. **Только токены, никаких магических чисел.** Цвета/отступы/радиусы/тени/типографика — из `assets/kit/assets/css/tokens.css`
+   (или скопируй переменные в проект). Один акцент + нейтрали + редкая тёплая деталь.
+4. **Петля визуальной проверки обязательна.** Собрал → скриншоты 1440/768/390, light/dark → смотри глазами (`read_image`)
+   → критика по рубрике (`references/critique-rubric.md`) → правки → снова скриншоты. **Минимум 2 итерации.**
+5. **Гейт качества:** средний балл ≥ 4.4/5, ни один критерий < 4; axe без critical/serious; на 390px нет горизонтального
+   скролла; тёмная тема проверена; first impression = «премиально», а не «шаблон».
+6. **Отчёт с доказательствами:** скриншоты + краткое обоснование решений (почему такой пресет, шрифт, композиция) +
+   что проверено. Без скриншотов работа не считается сданной.
+
+## 1. ПРОЦЕСС (7 шагов)
+
+### Шаг 1. Арт-направление (до кода)
+Выбери **один** пресет и адаптируй под задачу:
+
+| Пресет | Когда | Настроение | Display | Акцент |
+|---|---|---|---|---|
+| `aurora` | клиника, культура, премиум-сервис | тихая роскошь, тепло, доверие | Lora (serif) | изумруд `#0E6E5E` + медь |
+| `graphite` | продукт, SaaS, админки, дашборды | точность, плотность, технологичность | Unbounded | мята `#6EE7C8` / `#0E7C66` |
+| `editorial` | медиа, истории, бренд-лендинги | журнал, характер, крупная типографика | Lora | вермильон `#C8442A` |
+| `warm` | сервис для людей, образование, забота | человечность, мягкость, крем | Lora | терракота `#B85C38` |
+| `swiss` | корпоративный строгий, отчёты, B2B | дисциплина, сетка, контраст | Golos 700 | красный `#E0301E` |
+
+Заполни формулу: **3 прилагательных + 1 референс (что крадём) + 1 анти-референс (чего избегаем) + signature-деталь.**
+Signature-деталь — одна запоминающаяся вещь: крупные редакционные цифры, волосяные линии с «засечками», монограммы,
+печать/эмблема, номерные секции, тонкая бумажная текстура, необычный ритм сетки. Ровно одна, не пять.
+
+Справочники: `references/principles.md` (76 правил ремесла с числами), `references/presets.md` (пресеты подробно),
+`references/inspiration.md` (32 референса: что украсть/что нет), `references/critique-rubric.md` (рубрика 12×5),
+`references/anti-patterns.md` (42 антипаттерна), `references/stack-recipes.md` (React/Laravel/Bitrix), `references/visual-qa.md`.
+
+### Шаг 2. Токены
+Скопируй/подключи `assets/kit/assets/css/tokens.css`, `base.css`, `fonts.css`. Если проект уже имеет свою тему —
+**не ломай её**: замапий свои компоненты на существующие CSS-переменные, добавь недостающие токены, не перекрашивай всё.
+Проверь контраст: текст ≥ 4.5:1, крупный ≥ 3:1, фокус видимый.
+
+### Шаг 3. Композиция (до деталей)
+- 12-колоночная сетка, контейнер 1200–1360px, gutter `clamp(20px, 4.5vw, 56px)`.
+- Hero: **асимметрия** 7/5 или 8/4. Kicker (капс 11–12px + линия) → display-H1 (`clamp(3rem, 7vw, 6rem)`) → lead (≤52ch) →
+  2 CTA (primary + secondary) → proof-строка (3–4 цифры/факта) → визуальный якорь (типографика/SVG/диаграмма, не сток-фото).
+- Ритм секций: чередуй фон (`bg` / `surface` / `bg-alt`), отступы `clamp(64px, 8vw, 128px)`, волосяные разделители.
+- Карточки — только когда элементов действительно несколько и они равнозначны. Не «стена из трёх одинаковых карточек с иконками».
+- Плотные данные (таблицы, дашборды): строгая сетка, tabular-nums, правые числа, sticky header, hairline-строки.
+
+### Шаг 4. Сборка
+- Семантика: `header/nav/main/section/article/footer`, один `h1`, порядок заголовков, `lang="ru"`.
+- Компоненты — из `assets/kit/assets/css/components.css` или собери на тех же токенах. Каждый интерактивный элемент:
+  default / hover / focus-visible / active / disabled / loading; формы — error + help + disabled.
+- Иконки — inline SVG, stroke 1.5–1.6, 20/24px, один набор. Никаких эмодзи в UI. У иконок-кнопок — `aria-label`.
+- Контент — живой, конкретный, на языке пользователя. Никаких «Lorem ipsum», «Инновационные решения», «Мы предлагаем».
+
+### Шаг 5. Визуальная петля (главное!)
+```
+node <skill>/assets/scripts/capture.mjs <file> --name <page> --out <outdir>
+node <skill>/assets/scripts/audit.mjs  <file> --out <outdir>
+```
+Смотри PNG через `read_image`, оценивай по `references/critique-rubric.md`, выписывай 5–10 конкретных правок
+(не «сделать красивее», а «H1 72→88px, уменьшить радиус карточек до 14, убрать тень у статичных карточек, добавить
+воздуха вокруг сетки направлений»). Правишь → переснимаешь. Повторяй, пока гейт не пройден. **Не сдавай первый вариант.**
+
+### Шаг 6. Доступность и адаптив
+- 390px: нет горизонтального скролла; таблицы в `.table-wrap`; тач-цели ≥ 40–44px; ничего не обрезано.
+- Клавиатура: Tab-порядок, focus-visible, Escape закрывает модалки, aria-атрибуты.
+- `prefers-reduced-motion` — отключить reveal/hover-анимации.
+- Тёмная тема — отдельная палитра (не инверсия): фон глубже, акцент светлее, тени сильнее, контраст AA.
+
+### Шаг 7. Сдача
+Скриншоты (desktop 1440 light/dark, mobile 390, ключевые состояния) + 3–5 строк rationale + как интегрировать
+(какие файлы/токены/классы переиспользовать). Приложи пути к PNG в отчёте.
+
+## 2. РЫЧАГИ «ВАУ» (используй 3–5, не все сразу)
+
+1. **Типографический контраст:** огромный serif-display + мелкий капс-лейбл с трекингом + спокойный body. 80% впечатления.
+2. **Редакционная сетка:** асимметрия, номерные секции (01/02/03), волосяные линии, поля-воздух.
+3. **Одна смелая деталь:** гигантская цифра/буква, эмблема, вертикальный текст, необычный разделитель — но одна.
+4. **Материальность:** тёплая бумага, лёгкое зерно (2–3%), hairline-бордеры, слоистые тени, без «пластика».
+5. **Точные данные:** SVG-графики, sparklines, таблицы с tabular-nums, моно-цифры — выглядят дорого.
+6. **Микродетали:** offset у подчёркиваний, selection-цвет, аккуратный скроллбар, фокус-кольцо, иконки 1.5px.
+7. **Движение с достоинством:** reveal 700ms `cubic-bezier(.16,1,.3,1)`, stagger 60ms, hover 180ms; без bounce/parallax-цирка.
+8. **Копирайт:** глаголы, конкретика, числа, польза. Заголовок должен продавать результат, а не описывать отдел.
+
+## 3. АНТИПАТТЕРНЫ (мгновенно убивают «дорого»)
+
+Фиолетово-синие градиенты · 3 одинаковые карточки с иконками · glassmorphism на каждом блоке · эмодзи вместо иконок ·
+радиусы 24–32px у всего · дефолтный Bootstrap/Shadcn-вид без характера · центрированный hero с «блобами» ·
+gradient-text на заголовках · серый текст с контрастом < 4.5 · несогласованные отступы (13/17/22px) · тени «как в 2010» ·
+стоковые улыбающиеся люди · перегруз бейджами/иконками · анимации ради анимаций · «Lorem ipsum» · 16px-везде ·
+карточки с одинаковой иконкой-облачком · карусели, которые никто не листает · модалка на модалке.
+
+Полный список с заменами: `references/anti-patterns.md`.
+
+## 4. СТЕКИ (не изобретай заново)
+
+- **React + Tailwind/Vite:** токены — CSS-переменные в `:root`; Tailwind `@theme` маппится на них; компоненты — в одном
+  `components/ui`, состояния через `data-state`; скриншоты через `npm run dev` + capture. Подробнее: `references/stack-recipes.md`.
+- **Laravel Blade:** `resources/views/layouts/app.blade.php` + partials (`components/button.blade.php` и т.п.);
+  токены — `resources/css/tokens.css`; не ломай существующие классы; проверяй `npm run build`.
+- **Bitrix/Aspro:** правки — в `local/templates/<template>/` и `custom.css`/`init.php`, не в ядре и не в маркетплейс-шаблоне;
+  стили скоупить под контейнер страницы; после правок чистить кэш CSS (`/bitrix/cache/css/...`); проверять на живой странице.
+
+Подробные рецепты и подводные камни: `references/stack-recipes.md`.
+
+## 5. ЧТО ЛЕЖИТ В КИТЕ
+
+```
+assets/kit/
+  showcase.html        — витрина системы: палитры, типографика, компоненты, состояния, пресеты
+  pages/hospital.html  — эталон: премиальный лендинг клиники (aurora)
+  pages/dashboard.html — эталон: продуктовый дашборд (graphite, light/dark)
+  assets/css/          — tokens.css, base.css, fonts.css, components.css
+  assets/js/kit.js     — тема/пресет, reveal, tabs, modal
+  assets/fonts/        — Golos Text, Lora, Unbounded (OFL, локально)
+assets/scripts/
+  capture.mjs          — скриншоты (desktop/tablet/mobile, light/dark, full page)
+  audit.mjs            — axe-core + overflow/tap-target/шрифты/консоль
+```
+Как использовать: открой `showcase.html` для эталона; скопируй `tokens.css`/`base.css`/`fonts.css`/`components.css`
+и нужные паттерны страниц в проект; если проекта нет — начни с эталонной страницы, замени контент и бренд-акцент.
+
+## 6. ПРОВЕРКА ПЕРЕД СДАЧЕЙ (чек-лист)
+
+- [ ] Арт-направление зафиксировано (пресет, 3 слова, референс, signature-деталь).
+- [ ] Первый экран читается за 5 секунд: понятно, что это, для кого и что делать.
+- [ ] Иерархия: 1 главный акцент на экран; взгляд идёт по нужному маршруту.
+- [ ] Типографика: display/body/лейблы различимы, строка 60–72ch, числа табличные.
+- [ ] Воздух: секции дышат, сетка выровнена, ничего не «прилипло».
+- [ ] Состояния всех интерактивных элементов; формы с ошибками и подсказками.
+- [ ] Мобильный 390px, планшет 768px, десктоп 1440px — проверены скриншотами.
+- [ ] Тёмная тема — отдельная палитра, контраст AA.
+- [ ] axe: critical/serious = 0; keyboard/focus проверены.
+- [ ] Нет ни одного пункта из антипаттернов.
+- [ ] Скриншоты приложены, рубрика ≥ 4.4/5 и ни один критерий < 4.
+
+## 7. ЕСЛИ ЗАДАЧА — «ПРОСТО ПОПРАВИТЬ» СУЩЕСТВУЮЩИЙ UI
+
+Не переписывай всё. Сначала загрузи `design-critique`, сними скриншоты «до», оцени по рубрике, исправь
+**P0-проблемы** (иерархия, контраст, поломки адаптива, состояния), затем P1-полировку. Покажи «до/после».
+Сохраняй существующие классы/структуру, если проект чужой; правки — минимальные и локальные.
+
+## 8. ОТЧЁТ (шаблон)
+
+```
+## Дизайн: <страница/компонент>
+Арт-направление: <пресет>, <3 слова>, signature: <деталь>
+Что сделано: <3–6 пунктов>
+Скриншоты: <пути>
+Рубрика: <средний балл>, слабые места: <...>
+Проверено: 1440/768/390, light/dark, axe (critical=0), keyboard
+Риски/что дальше: <...>
+```

package/skills/wow-design/assets/kit/README.md

@@ -0,0 +1,195 @@
+# AURORA — дизайн-кит для WOW-UI
+
+Дизайн-система для интерфейсов, которые должны выглядеть дорого и уместно **с первого раза**.
+Пять пресетов, две темы, типографика Lora + Golos Text + Unbounded, полный набор компонентов
+и три эталонные страницы. Чистый HTML5 + CSS + vanilla JS: **без сборки, CDN и внешних запросов**.
+
+```
+projects/design-kit/
+├── showcase.html              # витрина дизайн-системы (главный артефакт)
+├── pages/
+│   ├── hospital.html          # эталон: премиальный лендинг клиники (aurora)
+│   └── dashboard.html         # эталон: Service Desk, product UI (graphite, light/dark)
+├── assets/
+│   ├── css/
+│   │   ├── tokens.css         # токены: цвет/типографика/отступы/эффекты (Lead, не менять)
+│   │   ├── fonts.css          # @font-face локальных шрифтов (Lead, не менять)
+│   │   ├── base.css           # reset, сетка, типографика, утилиты (Lead, не менять)
+│   │   ├── components.css     # все компоненты и состояния (этот кит)
+│   │   └── pages.css          # стили эталонных страниц и витрины
+│   ├── js/
+│   │   └── kit.js             # тема/пресет, reveal, tabs, модалка, меню, toast, демо-состояния
+│   └── fonts/*.woff2          # Golos Text, Lora, Unbounded (OFL)
+├── screenshots/               # скриншоты 1440/390, light/dark + full-page
+└── README.md
+```
+
+## Быстрый старт
+
+1. Откройте **`showcase.html` двойным кликом** — всё работает по `file://`, без сервера.
+2. Оттуда — ссылки на `pages/hospital.html` и `pages/dashboard.html`.
+3. Тема переключается кнопкой-«луной/солнцем» в шапке (запоминается в `localStorage`).
+   Пресеты на витрине — сегментированный переключатель `Aurora · Graphite · Editorial · Warm · Swiss`.
+4. На эталонных страницах пресет закреплён: клиника — `aurora`, дашборд — `graphite`.
+
+## Пресеты и темы
+
+Пресет — атрибут `<html data-preset="...">`, тема — `<html data-theme="light|dark">`.
+Все цвета/шрифты/радиусы/тени берутся из `tokens.css`.
+
+| Пресет | Когда | Настроение | Display | Акцент |
+|---|---|---|---|---|
+| `aurora` | клиника, культура, премиум-сервис | тихая роскошь, тепло, доверие | Lora | изумруд `#0E6E5E` + медь |
+| `graphite` | продукт, SaaS, дашборды | точность, плотность, контроль | Unbounded | мята/изумруд |
+| `editorial` | медиа, истории, лендинги | журнал, характер | Lora | вермильон |
+| `warm` | сервис для людей, забота | человечность, крем | Lora | терракота |
+| `swiss` | строгий корпоративный, B2B | сетка, контраст | Golos 700 | красный |
+
+Под бренд меняются **только** переменные акцента (см. `tokens.css`):
+`--accent`, `--accent-hover`, `--accent-press`, `--accent-soft`, `--accent-ink`, `--accent-contrast`.
+Правило: контраст `--accent` ↔ `--accent-contrast` ≥ 4.5:1; `--accent-ink` — текст на `*-soft`.
+
+## Как переиспользовать
+
+### 1. Подключите базовые файлы (в этом порядке)
+
+```html
+<link rel="stylesheet" href="assets/css/tokens.css">
+<link rel="stylesheet" href="assets/css/fonts.css">
+<link rel="stylesheet" href="assets/css/base.css">
+<link rel="stylesheet" href="assets/css/components.css">
+<!-- pages.css — только если нужны паттерны эталонных страниц -->
+```
+
+### 2. Размечайте компонентами
+
+```html
+<button class="btn btn--primary">Записаться</button>
+<button class="btn btn--secondary btn--sm">Отмена</button>
+
+<div class="field">
+  <label class="label" for="phone">Телефон</label>
+  <input class="input" id="phone" type="tel" placeholder="+7 (___) ___-__-__">
+  <span class="field__hint">Напомним за день до приёма.</span>
+</div>
+
+<span class="badge badge--success badge--dot">Решена</span>
+<div class="card"><div class="card__body">…</div></div>
+<div class="table-wrap"><table class="table">…</table></div>
+```
+
+Полный каталог классов — в оглавлении `components.css` (18 секций): кнопки, поля и формы,
+бейджи/статусы, карточки/frame, таблицы, tabs, алерты, toast, модалка, меню/dropdown/tooltip,
+крошки/пагинация/segmented, аватары/progress/skeleton/empty/timeline, KPI+sparkline,
+каркас приложения (sidebar/topbar), hero-паттерны, списки и утилиты.
+
+### 3. JS (только если нужны интерактивные состояния)
+
+```html
+<script src="assets/js/kit.js" defer></script>
+```
+
+Разметка «включает» поведение через data-атрибуты:
+
+| Атрибут | Что делает |
+|---|---|
+| `data-theme-toggle` | переключатель светлой/тёмной темы |
+| `data-preset-set="graphite"` | кнопка выбора пресета (на витрине) |
+| `.reveal` + `data-delay="1..5"` | появление при скролле (stagger 60 ms) |
+| `data-tabs` + `role="tab"/"tabpanel"` | tabs с клавиатурой (← → Home End) |
+| `data-modal-open="#id"`, `data-modal-close` | модалка: Escape, focus trap, возврат фокуса |
+| `data-nav-toggle="#nav"` + `.nav-scrim` | мобильное меню/drawer |
+| `data-dropdown` + `data-dropdown-toggle` | dropdown-меню |
+| `data-demo-loading`, `data-demo-toast` | демонстрация loading/toast (витрина) |
+| `data-copy="значение"` | копирование значения в буфер + toast |
+
+> **Почему не `<script type="module">`?** `kit.js` написан как ES2022-модуль (без импортов/экспортов),
+> но подключается обычным `defer`-скриптом: Chrome блокирует внешние module-скрипты на `file://`,
+> а страницы кита обязаны открываться двойным кликом. В ESM-проекте достаточно заменить тег на
+> `type="module"` — код менять не нужно.
+
+### 4. Иконки
+
+Иконки — inline SVG-спрайт в начале `<body>` (stroke 1.6, 24×24), использование:
+`<svg class="icon icon--sm" viewBox="0 0 24 24" aria-hidden="true"><use href="#i-search"/></svg>`.
+Скопируйте нужные `<symbol>` в свою страницу. Никаких эмодзи и внешних иконочных шрифтов.
+
+### 5. Токены, а не магические числа
+
+Отступы — `--sp-1…--sp-14`, кегли — `--text-*`/`--display-*`, контейнер — `--container*`,
+радиусы — `--radius-*`, тени — `--shadow-*`, движение — `--dur*`/`--ease*`.
+Новые значения добавляйте в `tokens.css` своего проекта, а не в компоненты.
+
+## Эталонные страницы
+
+### `pages/hospital.html` — aurora
+Utility-бар → sticky-навигация → асимметричный hero 7/5 (serif-H1, «печать» с лицензией,
+proof-строка) → редакционный нумерованный список направлений 01–08 с hover-подсветкой →
+«Путь пациента» (4 шага) → 3 карточки врачей с монограммами → доверие (лицензии/оборудование/
+страховки) → новости → CTA-полоса → футер с юр. информацией. Без фото — только типографика, SVG и монограммы.
+
+### `pages/dashboard.html` — graphite
+Тёмный сайдбар 248 px → топбар (крошки, поиск с ⌘K, уведомления, профиль) → 4 KPI со sparkline
+и дельтой → SVG area-график SLA + донат «SLA 94,2 %» → таблица заявок (sticky-заголовок,
+tabular-nums, SLA-таймеры, hover-действия, скролл на мобильном) → лента активности → загрузка смены → пагинация.
+Полноценная светлая и тёмная тема.
+
+## Качество и проверки
+
+- **axe critical/serious = 0** на всех трёх страницах (WCAG AA по контрасту текста; интерактив ≥ 24 px,
+  иконочные кнопки 44 px, focus-visible, aria, reduced-motion).
+- **Нет горизонтального overflow** на 390 px; таблица скроллится внутри контейнера.
+- Шрифты локальные, `document.fonts.status = loaded`; внешних запросов нет.
+- Скриншоты снимаются готовыми инструментами из корня workspace:
+
+```bash
+node tools/design-qa/capture.mjs projects/design-kit/showcase.html  --name showcase  --out projects/design-kit/screenshots
+node tools/design-qa/audit.mjs   projects/design-kit/showcase.html  --name showcase
+```
+
+`capture` даёт 6 кадров: desktop 1440×900, tablet 768×1024, mobile 390×844 × light/dark
+(full-page); `--no-full` — только первый экран. `audit` — axe + overflow + тапы + шрифты + консоль.
+
+### Скриншоты в `screenshots/`
+- `showcase-1440-light.png`, `showcase-1440-dark.png`, `showcase-390-light.png` — first impression
+- `hospital-1440-light.png`, `hospital-1440-dark.png`, `hospital-390-light.png`
+- `dashboard-1440-light.png`, `dashboard-1440-dark.png`, `dashboard-390-light.png`, `dashboard-390-dark.png`
+- `<page>-desktop|tablet|mobile-light|dark.png` — full-page для каждой страницы (18 файлов)
+
+### Самооценка по рубрике (`tmp/design-research/04-critique-rubric.md`)
+
+| # | Критерий | Showcase | Hospital | Dashboard |
+|---|---|---|---|---|
+| К1 | Первое впечатление / концепция | 5 | 5 | 5 |
+| К2 | Иерархия и маршрут взгляда | 4 | 5 | 5 |
+| К3 | Типографика | 5 | 5 | 4 |
+| К4 | Цвет и контраст | 4 | 5 | 5 |
+| К5 | Сетка и ритм | 5 | 5 | 5 |
+| К6 | Воздух и плотность | 5 | 5 | 4 |
+| К7 | Компоненты и состояния | 5 | 4 | 5 |
+| К8 | Консистентность | 5 | 5 | 5 |
+| К9 | Детали и полировка | 4 | 4 | 4 |
+| К10 | Адаптив и мобильный | 4 | 4 | 4 |
+| К11 | Доступность | 5 | 5 | 5 |
+| К12 | Оригинальность vs польза | 5 | 4 | 5 |
+| | **Средневзвешенный балл** | **4.67** | **4.78** | **4.69** |
+
+Порог DoD (≥ 4.4, ни один критерий < 4) выполнен; axe critical/serious = 0; overflow 390 = 0.
+
+## Принципы (не нарушать)
+
+- **Типографика — герой.** Display ↔ body ↔ служебный текст: контраст масштабов, строка 60–72 ch,
+  табличные цифры, капс-лейблы с трекингом.
+- **Воздух — материал.** Секции 96–128 px, волосяные линии вместо рамок, асимметрия 7/5 и 8/4.
+- **Один акцент.** Цвет работает на иерархию, а не на эффект; семантика статусов дублируется текстом.
+- **Тени слоистые, радиусы по пресету**, не «всё rounded-3xl»; никакого стекла на каждом блоке.
+- **Иконки — только inline SVG 1.5–1.6 px**, без эмодзи; фото и стоки не используются.
+- **Motion 160–260 ms**, один easing, reveal 700 ms; `prefers-reduced-motion` уважается.
+- **Копирайт — живой русский:** глаголы, конкретика, числа. Никаких «Инновационных решений» и Lorem ipsum.
+- **Доступность:** контраст AA, focus-visible, aria, модалка с focus trap, тап-цели ≥ 24 px (иконочные — 44).
+
+## Лицензии
+
+Шрифты Golos Text, Lora, Unbounded — SIL Open Font License, файлы локальные
+(`assets/fonts/LICENSE-*.txt`). Код кита можно свободно переиспользовать внутри проектов DSH.
+Данные на эталонных страницах — вымышленные (демонстрационные), совпадения случайны.