figma-ai-plugin/IDEA.md

IDEA — Figma AI Plugin (MVP)

Проект: автономный Figma-плагин с AI-ассистентом. Локальная копия: /root/.hermes/projects/figma plugins/figma-ai-plugin/ Копия на Matebook: D:\Figma Plugins\figma-ai-plugin\ Gitea: http://x1qnvk08zec2u5cx6yh5iexh.155.212.186.39.sslip.io/admin/figma-ai-plugin

Ресурсы

UI-фреймворк (@create-figma-plugin/ui)

• Storybook компонентов (живые примеры, темы Light/Dark/FigJam): https://yuanqing.github.io/create-figma-plugin/ui/
• Репозиторий фреймворка: https://github.com/yuanqing/create-figma-plugin
• Cheat-sheet компонентов (InvStd): https://github.com/invstd/Figma-Plugin-Quickstart/blob/main/FIGMA-PLUGIN-UI-COMPONENTS-REFERENCE.md

Официальная документация по созданию плагинов Figma

• Plugin API (официальная): https://www.figma.com/plugin-docs/
• Quick start (plugin setup): https://www.figma.com/plugin-docs/plugin-quickstart/
• Руководство по UI (design/iframe): https://www.figma.com/plugin-docs/how-plugins-work/#the-iframe
• Типы плагина (plugin-typings): npm @figma/plugin-typings

Примеры плагинов (уже есть / опорные)

• Исходный плагин «AI assistant» (Николай, Matebook): D:\YandexDisk\Figma Plugins DEVs\AI assistant — рабочий движок (eval + RPC, CodeMirror), оттуда переиспользуем main.ts/ui.tsx.
• create-figma-plugin templates: https://github.com/yuanqing/create-figma-plugin/tree/main/templates
• Figma Plugin Quickstart (InvStd): https://github.com/invstd/Figma-Plugin-Quickstart
• create-figma-plugin-native (кастомные компоненты Tabs/Modal/Checkbox): https://www.npmjs.com/package/@inversestudio/create-figma-plugin-native

Стек

• TypeScript (зафиксирован ~5.6.3 — TS 7 ломает @create-figma-plugin/build)
• @create-figma-plugin/ui + @create-figma-plugin/utilities (Preact)
• Сборка: build-figma-plugin (npm run build / npm run watch)
• Важно: tsconfig наследует @create-figma-plugin/tsconfig (jsx: react + jsxFactory: h). Не оверрайдить jsx на react-jsx.

Рабочий флоу (Hello World проверен)

1. Пишешь код на VPS в /root/.hermes/projects/figma plugins/figma-ai-plugin/
2. Перед сборкой обновляешь patch-версию в package.json и src/ui.tsx (PLUGIN_VERSION)
3. npm run build — сборка должна пройти успешно
4. git push → Gitea (admin/figma-ai-plugin)
5. Собираешь архив из корня проекта, исключая только node_modules и .git; обязательно включаешь build/ и сохраняешь структуру каталогов. Проверка перед отправкой: unzip -l /tmp/figma-ai-plugin.tar.gz должна показывать build/main.js, build/ui.js, manifest.json — не main.js и ui.js в корне архива.
6. Передаёшь архив/файлы на Matebook в staging-папку, затем распаковываешь в D:\Figma Plugins\figma-ai-plugin\ с сохранением путей. Не отправляй flat ZIP (zip -j): он кладёт main.js/ui.js рядом с манифестом, а Figma загружает build/main.js/build/ui.js.
7. После синхронизации обязательно сверяешь SHA-256 удалённых build/main.js, build/ui.js, manifest.json с локальными. Проверяешь в build/ui.js маркер новой версии (0.1.N). Успешный scp/распаковка сами по себе не доказывают, что обновилась папка, из которой загружает Figma.
8. В Figma: Plugins → Development → Import plugin from manifest → выбрать manifest.json из папки Matebook; если уже импортирован — выполнить Reload.
9. Запустить плагин и проверить версию в статус-баре.

Важно: не заканчивай sync на наличии ZIP в Downloads. Цель — именно D:\Figma Plugins\figma-ai-plugin\build\, откуда Figma читает entrypoints. Подробная проверенная процедура — KNOWLEDGE.md, раздел «Синхронизация билда на Matebook».

Правила ведения репозитория

• Коммит + пуш в Gitea — обязательная часть рабочего флоу. Любое осмысленное изменение в коде/доках коммитится и пушится в origin/main сразу по завершении задачи (не копить локально).
• _reference/ — временные копии чужих/старых плагинов для сверки; в git не попадают (в .gitignore).
• build/ и node_modules/ не коммитятся (собираются локально / на Matebook), см. синхронизацию через tar в KNOWLEDGE.md.

Правила ведения KNOWLEDGE.md

• KNOWLEDGE.md — живая копилка gotcha/решений. Hermes (агент) имеет право дописывать и править KNOWLEDGE.md самостоятельно, без вопросов к пользователю, когда находит новую проблему и её решение по ходу работы над проектом.
• Формат записи: ### Заголовок + блоки Симптом / Причина / Решение / Ссылка (как в текущих записях).
• Если правишь рабочий флоу здесь (IDEA.md), продублируй связанное gotcha в KNOWLEDGE.md (напр. ловушка с --exclude build).