EugineKosenko/majordom

analyze-fig

Розбір експорту Figma (.fig) без звернень до Figma API: дерево вузлів, тексти й растри читаються з самого файлу, а коментарі автора, яких у .fig немає, беруться окремо через MCP за посиланням. Результат — md-файли в spcfctn/ui/, з якими далі працюємо замість повторного читання Figma.

Коли не запускати

Питання про вже розібраний макет («що вказано в коментарі до фільтра…», «які колонки в екрані…») розв'язуй читанням spcfctn/ui/*.md, а не цією навичкою. Розбір потрібен на новий чи оновлений .fig або коли в md відповіді немає (див. spcfctn-code.md).

Каталоги (єдиний каталог чернеток draft, поза git)

• spcfctn/ui/draft/ — вхідний .fig (і будь-які інші чернетки). Файл кладе користувач.
• spcfctn/ui/draft/<назва>/ — результат розпакування: message.json (усі вузли), meta.json, images/, screens.json і screens.txt, а також зібрані коментарі (comments.json). Відтворюється з .fig, у git не йде. Окремих raw/ і data/ немає (modeling.md).
• spcfctn/ui/*.md — результат аналізу; тільки це лишається в git.

<назва> — ім'я файлу без розширення в нижньому регістрі через дефіс (internal-interfaces).

Крок 0 — підготовка

• Знайди spcfctn/ проєкту. Якщо його немає — попроси користувача створити (spcfctn-code.md). Артефакт ui/ і його підкаталог draft/ створюй сам.
• Перевір spcfctn/ui/.gitignore (репозиторій артефакта): має бути draft (див. modeling.md); чого бракує — додай через gitignore.org.
• Fig-файл: його назву вказує користувач; не вказано — покажи spcfctn/ui/draft/*.fig і спитай.
• Прочитай CLAUDE.md проєкту (мова прози, конвенції) та наявні spcfctn/ui/*.md: розбір має продовжувати їхню структуру й терміни, а не починати з нуля.
• Потрібні python3 і zstd у PATH.

Крок 1 — розпакувати й декодувати

python3 ~/.claude/skills/analyze-fig/scripts/fig.py spcfctn/ui/draft/X.fig spcfctn/ui/draft/<назва>

Виводить версію формату, кількість вузлів, блобів і зображень. Скрипт перевірено на версії 106; на іншій версії чи з помилкою — не вгадуй формат і не читай чужі декодери, скажи користувачу. meta.json містить exported_at: час експорту знадобиться на кроці 5. message.json великий, безпосередньо його не друкуй.

Крок 2 — розібрати на секції й екрани

python3 ~/.claude/skills/analyze-fig/scripts/screens.py spcfctn/ui/draft/<назва>

Виводить перелік сторінок, секцій (фрейми верхнього рівня) і екранів (їхні діти) з кількістю текстів і растрів. Уся суть — у screens.txt: для кожного екрана текстові шари, згруповані в рядки зверху вниз і зліва направо (так читаються фільтри, заголовки колонок і кнопки), плюс посилання на растри.

• Порівняй кількості з очікуваними (наприклад, зі старим md); розбіжність — привід зупинитися.
• Текстові шари не бачать елементів без тексту (голі іконки) і вмісту растрів. Для кожного растра з images/ відкрий файл (Read) і опиши, чого немає в текстових шарах; позначай, що це прочитано з картинки. Дерево й тексти — основне свідчення, картинки — доповнення.
• Компонентні екземпляри (INSTANCE) можуть мати перевизначені тексти, яких скрипт не бачить; screens.txt про це попереджає.

Крок 3 — записати spcfctn/ui/*.md

• Один md на секцію (чи на файл, коли секція одна). Файл уже є — прочитай його повністю й онови, а не переписуй: md-файли веде лише агент, але втрачати попередні уточнення не можна.
• Мова прози — за CLAUDE.md проєкту.
• Структура (зразок — spcfctn/ui/internal-dashboard.md у job/vale/kylada): вступ із джерелом і перевіркою (що прочитано, дата експорту, кількість екранів і текстів), правила читання макетів, відповідність підписів UI внутрішнім термінам, екрани по порядку (фільтри в порядку макета, кнопка переліку, колонки, дії в рядках), відкриті питання.
• Усе, що є твоїм прочитанням, а не текстом макета чи коментарем, позначай inferred.
• Проєктні правила читання макетів (наприклад, що Select під заголовком колонки — керування сортуванням) бери з CLAUDE.md проєкту й застосовуй, а не вигадуй.

Крок 4 — коментарі через MCP за посиланням

Коментарів у .fig немає (перевірено): вони лишаються на сервері Figma.

• Потрібне посилання на файл у Figma (з node-id чи без). Немає — попроси в користувача.
• Використовуй лише MCP-інструмент comments того Figma MCP-сервера, який підключено в проєкті (назву бери зі списку підключених серверів); параметр file — це посилання. Немає такого інструмента — скажи користувачу. Офіційний figma-cs коментарів не віддає, а REST із токеном напряму не викликай і .env не чіпай.
• Виклик без node_id дає всі коментарі файлу гілками (номер, дата, стан, вузол @id, текст, відповіді). refresh без потреби не став. Ендпоінт коментарів рахується окремо від читання файлу й працює, навіть коли читання дало 429.
• Прив'язка до екрана:
  • @id збігається з id екрана з screens.json — екран визначено;
  • @id секції чи сторінки — екран визначають за геометрією, для цього потрібні node_id і node_offset коментаря. Склади рядки КЛЮЧ ВУЗОЛ X Y (наприклад, #144 979:3 500 5471) і подай на вхід: python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<назва> < рядки. Вивід: ключ, секція, екран; чи причина й найближчий екран, якщо точка не на екрані.
  • Перевір вивід: інструмент comments може не друкувати node_offset (так було на момент створення навички). Тоді коментарі до секції чи сторінки точно не розкласти: не вгадуй екран за текстом, а віднеси їх до секції, познач екран не визначено й скажи користувачу, що для розкладання потрібен зсув коментаря.
• Відповіді (↳) належать до гілки батька.

Крок 5 — перевірити, що коментарі відповідають файлу

Для кожного коментаря з визначеним екраном (і для групи коментарів секції) перевір:

• Чи названі в коментарі поля, колонки, кнопки, значення є серед текстових шарів цього екрана (Amount of integrated services ↔ колонка Services; цитати в лапках; переліки значень).
• Чи не суперечить коментар макету (кількість колонок, порядок, тип елемента, «є фільтр» / «немає»).
• Дата: коментар новіший за exported_at з meta.json — експорт застарів. Тоді попроси свіжий експорт у spcfctn/ui/draft/.
• Вузол коментаря відсутній у файлі (видалено чи перейменовано) — це осиротілий коментар.
• Коментар без екрана й без розпізнаваного змісту.

Розбіжності зведи в невелику таблицю (номер #N, екран, у чому розбіжність) і спитай користувача, що правильне: не виправляй мовчки й не вибирай сам між макетом і коментарем. До відповіді познач їх в md як conflict.

Крок 6 — записати підсумок

• У md додай розділ з коментарями автора: дайджест (що вони з'ясовують) і всі коментарі по екранах з номерами #N. Де коментар уточнює те, що було inferred, виправ запис і вкажи на коментар.
• Оновити «Verification» у вступі: що прочитано (.fig, версія, дата експорту, тексти, растри, коментарі, дата їх отримання) і що не покрито.
• Відкриті питання — окремим списком; відповіді користувача переноси в «Resolved».
• Нічого не коміть без прохання. Усно (українською) підсумуй: скільки секцій, екранів, коментарів, скільки розбіжностей і що саме треба уточнити.

Чого не робити

• Не викликай Figma REST із токеном, не читай і не редагуй .env.
• Не читай сторонній код (kiwi-декодери тощо): формат уже реалізовано в scripts/.
• Не клади .fig і розбір (усе під draft/) у git.
• Не вгадуй екран коментаря за словами, а зміст макета — за картинкою, коли є текстові шари.