figma-ai-plugin/KNOWLEDGE.md

Knowledge — Figma AI Plugin

Копилка находок и решений по проекту. Не наступай на грабли дважды. Пополняется по ходу разработки. Формат: проблема → решение (+ контекст/ссылка). Hermes имеет право править и дополнять этот файл самостоятельно (см. IDEA.md).

Сборка / окружение

TypeScript 7.x ломает @create-figma-plugin/build

• Симптом: TypeError: Cannot read properties of undefined (reading 'getCurrentDirectory') при build-figma-plugin.
• Причина: build-figma-plugin ожидает ts.sys, которого нет в TS 7.
• Решение: зафиксировать typescript на ~5.6.3 в package.json devDependencies.
• Ссылка: package.json

tsconfig: не оверрайдить jsx на react-jsx

• Симптом: error TS5089: Option 'jsxFactory' cannot be specified when option 'jsx' is 'react-jsx'.
• Причина: базовый @create-figma-plugin/tsconfig уже задаёт jsx: react + jsxFactory: h.
• Решение: в проектном tsconfig только extends + добавляем lib/types. Не трогать jsx/jsxFactory. Preact h уже импортируется в ui.tsx.
• Ссылка: tsconfig.json

Text muted не существует — используй Muted

• Симптом: Property 'muted' does not exist on type ... Text.
• Решение: для приглушённого текста брать компонент <Muted> из @create-figma-plugin/ui, а не проп muted у <Text>.
• Ссылка: src/ui.tsx

Кнопка-иконка рядом с другими IconButton — бери РОДНУЮ иконку, не инлайн-SVG

• Симптом: иконка копирования рядом с кнопкой развернуть выглядит «другого размера»/тоньше, хотя viewBox один (24×24).
• Причина: IconButton из @create-figma-plugin/ui оборачивает иконку в <div class="icon"> (position:absolute, БЕЗ задания размера) — размер берётся целиком из самой SVG. Родные иконки сета (IconExpand24, IconCheck24, IconCopySmall24 и т.п.) — залитые (fill="currentColor"). Моя инлайн-SVG была контурной (stroke, fill="none", stroke-width=2) — на том же 24×24 viewBox контурные lucide-иконки визуально кажутся меньше и легче, чем залитые соседки. Отсюда ощущение «разные размеры».
• Правило (как делать правильно):
  1. Рядом с IconButton НИКОГДА не ставить текстовую <Button> с лейблом — только IconButton (пользователь прямо сказал: "Очевидно же, что там достаточно кнопки иконки").
  2. Брать иконку из родного сета @create-figma-plugin/ui (он же — адаптация lucide, залитые 24px): IconCopySmall24, IconDuplicateSmall24, IconClipboardSmall24, IconCheck24, IconExpand24 и т.д. — гарантированно совпадёт по габариту и весу с соседями.
  3. Если нужной иконки в сете нет (напр. copy/clipboard там только 16px -small), и ты делаешь инлайн-SVG — делай её залитой (fill="currentColor", без stroke), width/height=24, viewBox="0 0 24 24, чтобы вес совпал с родными. Контурные (stroke) иконки lucide рядом с залитыми соседями НЕ класть.
  4. Подтверждение действия (копирование) — переключать иконку на IconCheck24 на ~1.2 с, без текстовой подписи.
• Ссылка: node_modules/@create-figma-plugin/ui/lib/components/icon-button/icon-button.module.css (.icon без размера), icon-24/icon-*-24.js (залитые SVG), src/ui.tsx (кнопки в тулбаре).

Плагин не запускается в Figma — нет папки build/ на Matebook

• Симптом: плагин не открывается / Figma молча ничего не делает при Run (ошибка не всегда видна).
• Причина: manifest.json указывает main: build/main.js и ui: build/ui.js, но в скопированной на Matebook папке папки build/ нет (старая команда синхронизации исключала её через --exclude build).
• Решение: пересобрать на VPS (npm run build) и залить на Matebook ВЕСЬ проект вместе с build/ — исключать только node_modules и .git (они для запуска в Figma не нужны, Figma исполняет собранные build/*.js). После распаковки проверить наличие build/main.js и build/ui.js.
• Ссылка: IDEA.md (раздел «Рабочий флоу», шаг 4), этот файл (раздел синхронизации через tar).

Рабочий флоу (VPS → Matebook → Figma)

Копия на Matebook через tar (rsync/scp с пробелами в пути падают)

• Симптом: rsync: command not found (на Windows), scp: ambiguous target (пробел в пути).
• Решение:
  1. На VPS: npm run build (обязательно — иначе нет папки build/)
  2. На VPS: tar czf /tmp/x.tar.gz --exclude node_modules --exclude .git . ← build/ НЕ исключать!
  3. scp /tmp/x.tar.gz risow@10.200.201.5:D:/x.tar.gz
  4. На Matebook (PowerShell): Set-Location 'D:/Figma Plugins/figma-ai-plugin'; tar xzf 'D:/x.tar.gz'
• Ловушка: старая команда исключала --exclude build → в папке плагина на Matebook не было build/, и Figma не находила build/main.js/build/ui.js → плагин не запускался. См. gotcha «Плагин не запускается — нет build/».
• Ссылка: IDEA.md (раздел «Рабочий флоу»)

Gitea push через токен в URL

• Симптом: could not read Username при git push (нет credential helper).
• Решение: remote как http://<TOKEN>:@<host>/admin/figma-ai-plugin.git. Токен должен иметь scope write:repository (без write:user создать репо нельзя — создавать через basic auth admin-ом).
• Ссылка: IDEA.md, Gitea http://x1qnvk08zec2u5cx6yh5iexh.155.212.186.39.sslip.io/admin/figma-ai-plugin

Ресурсы (не терять)

• UI Storybook: https://yuanqing.github.io/create-figma-plugin/ui/
• Figma Plugin API docs: https://www.figma.com/plugin-docs/
• Исходный плагин «AI assistant» (движок): D:\YandexDisk\Figma Plugins DEVs\AI assistant (Matebook)