Рабочие заметки по 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.

Ссылки

• 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 (danger, info, success, warning).
  • src/scss/_design-tokens.scss — semantic surfaces, borders, motion, radius placeholders, focus.
  • src/scss/_fonts.scss — Plus Jakarta Sans + полная типографическая шкала.
  • docs/style-guide.md — человекочитаемая документация по токенам.
• Проверены команды:
  • npm run build — проходит.
  • npm run build:example:vue — проходит.
  • npm run test:e2e — проходит.

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

1. Уточнить radius-токены через Playwright-сравнение с компонентными фреймами.
2. Найти spacing-токены в Figma (если есть отдельная страница) или зафиксировать свою шкалу.
3. Подключить реальные шрифты (Plus Jakarta Sans) и Phosphor Icons в public/assets/.
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 + Phosphor Icons в public/assets/ или подключать через npm/CDN.
• Нужно ли сохранять dist/js/vmk-ui-kit.js global namespace как VMKUIKit или дублировать под GNexusUIKit для совместимости? (Пока выбран VMKUIKit, потому что пакет новый.)