# Рабочие заметки по 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-макет: `vmk-ui-kit-figma.url` → https://www.figma.com/design/Wh7d0fPgbkslCoyQmO9DC4/%E2%9D%96-Oselya.ai?node-id=40002541-29833&p=f
  - На текущий момент файл недоступен для публичного WebFetch (403). Нужна публичная шара, Figma REST token, или ручная выгрузка токенов/экранов.
- 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:vue-adapter`, `build:example:vue`.
- Playwright добавлен в devDependencies.

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

1. Подключить Figma-макет (получить токены).
2. Создать структуру исходников:
   - `src/scss/` — токены, утилиты, компоненты.
   - `src/js/` — browser JS entry и UI-компоненты.
   - `src/vue/` — Vue 3 adapter.
   - `demo/` — demo/docs страница и HTML partials.
   - `public/assets/` — шрифты, иконки, изображения.
3. Создать начальную документацию в `docs/`:
   - `index.md` — обзор и quick start.
   - `getting-started.md` — подключение.
   - `vue.md` — Vue adapter.
   - `style-guide.md` — design tokens и принципы.
   - `release.md` — проверки перед релизом.
   - `component-coverage.md` — карта компонентов.
4. Настроить Playwright конфиг (`playwright.config.js`) и первый визуальный тест.
5. Создать Vue example в `examples/vue/` для smoke build.
6. Реализовать foundation: типографику, палитру, spacing, токены.
7. Реализовать базовые компоненты (button, input, badge и т.д.) и их Vue-адаптеры.

## Заметки по 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 недоступна публично — блокирует вытаскивание точных токенов.
- Нужно решить, копировать ли IBM Plex Mono + Phosphor Icons в `public/assets/` или подключать через npm/CDN.
- Нужно ли сохранять `dist/js/vmk-ui-kit.js` global namespace как `VMKUIKit` или дублировать под `GNexusUIKit` для совместимости? (Пока выбран `VMKUIKit`, потому что пакет новый.)