# Рабочие заметки по VMK UI Kit

## Контекст и цель

Создать UI kit `vmk-ui-kit` на основе Figma-макета, с сохранением API-совместимости с `gnexus-ui-kit`. Существующие проекты, использующие `gnexus-ui-kit`, должны иметь возможность мигрировать без массовой переписки кода.

## Согласованные решения

- **Пакет:** новый пакет `vmk-ui-kit`, а не drop-in replacement. API импортов и компонентов повторяет `gnexus-ui-kit`, но имя пакета своё.
- **Билд-стек:** Gulp 5 + Dart Sass (`@use`/`@forward`) + PostCSS/autoprefixer + clean-css + esbuild + BrowserSync. Максимальная близость к reference для простоты совместимости.
- **Playwright:** добавлен `@playwright/test` для визуального сравнения и точной подгонки компонентов под дизайн.
- **Коммиты:** без `Co-Authored-By` и прочего соавторства.
- **Документация:** ведём `PROJECT_NOTES.md` для внутреннего состояния; публичная документация разработчика и демо-страницы компонентов — в `docs/` и `demo/`, как в `gnexus-ui-kit`.
- **Порядок работы:**
  1. Общие стили и токены.
  2. Компоненты, общие для нового и старого наборов.
  3. Компоненты из `gnexus-ui-kit`, отсутствующие в новом дизайне, — перерисовать в новом стиле.
  4. Новые компоненты, есть только в новом наборе.
- **Figma-токен:** сохранён вне репозитория (memory-файл), в `.gitignore` добавлен `.figma-token`.
- **Иконки:** пользователь предоставил `Icons_svg.zip` с SVG-иконками. Архив распакован в `public/assets/icons/svg/`, все `stroke="black"` заменены на `currentColor`, создан `index.json` для поиска по имени, добавлен `icon-helper.js` для загрузки SVG inline.

## Ссылки

- Figma-макет: `vmk-ui-kit-figma.url` → https://www.figma.com/design/scEx4ahLAQbx9akCuttfQC/Oselya.AI_Copy?m=auto&t=M7v0vsNdgVY308YR-1
- Reference kit: `/home/gmikcon/Projects/gnexus-ui-kit-reference` (read-only clone).

## Текущее состояние

### Что сделано

- Созданы `package.json`, `gulpfile.js`, `.gitignore`.
- Добавлены npm-скрипты: `build`, `build:vue`, `dev`, `start`, `test:e2e`, `test:visual`, `test:vue-adapter`, `build:example:vue`.
- Playwright добавлен в devDependencies; Chromium установлен; smoke test проходит.
- Создана структура исходников и документации.
- **Токены из Figma вытащены и применены:**
  - `src/scss/_palette-colors.scss` — primitive scales (neutral, lavender, mint, yellow) и semantic primitives.
  - `src/scss/_design-tokens.scss` — semantic surfaces, borders, motion, radius placeholders, focus.
  - `src/scss/_fonts.scss` — Plus Jakarta Sans + полная типографическая шкала.
  - `docs/style-guide.md` — человекочитаемая документация по токенам.
- **Иконки подключены:**
  - 967 SVG-иконок распакованы в `public/assets/icons/svg/`.
  - Все `stroke="black"`/`fill="black"` заменены на `currentColor`.
  - `public/assets/icons/index.json` — карта имя → путь.
  - `src/js/components/icon-helper.js` — асинхронная загрузка и рендер SVG inline.
  - `src/scss/components/_icons.scss` — базовые стили для inline-иконок.
- Проверены команды:
  - `npm run build` — проходит.
  - `npm run build:example:vue` — проходит.
  - `npm run test:e2e` — проходит.

### Что нужно сделать

1. Подключить шрифт Plus Jakarta Sans (локально или через CDN).
2. Уточнить radius-токены через Playwright-сравнение с компонентными фреймами.
3. Зафиксировать spacing scale (если в Figma есть отдельная страница — найти; иначе оставить текущую).
4. Реализовать foundation-компоненты demo: Typography, Palette, Utilities.
5. Реализовать базовые компоненты и Vue-адаптеры (Button, Input, Badge, Alert и т.д.).
6. Обновить `docs/component-coverage.md` по мере добавления компонентов.
7. Создать визуальные Playwright-тесты для сравнения компонентов с Figma-экспортами.

## Заметки по reference

- `gnexus-ui-kit` публикует browser API в `window.GNexusUIKit` и одновременно в `window` (Helper, Toasts, Modals и т.д.).
- Vue adapter — render-function `.js` файлы, без `.vue` SFC.
- CSS entry `src/scss/kit.scss` импортирует все компоненты и базовые стили.
- Иконки — Phosphor Icons, обязательный base class `ph`.
- Варианты: `primary`, `secondary`, `accent`, `success`, `warning`, `danger`, `error`, `info`.

## Риски и открытые вопросы

- Figma REST token не имеет scope `file_variables:read`, поэтому переменные пришлось вытаскивать через PNG-экспорт. Это ограничивает точность, но базовые токены получены.
- Нужно подключить Plus Jakarta Sans — либо скачать локально, либо через Google Fonts / npm пакет.
- Нужно ли сохранять `dist/js/vmk-ui-kit.js` global namespace как `VMKUIKit` или дублировать под `GNexusUIKit` для совместимости? (Пока выбран `VMKUIKit`, потому что пакет новый.)