Кадры из Figma (references/figma.md)

Источник: ds-internal/presentations/component-video-skill/references/figma.md — справочник скилла astra-component-video

Справочник к шагу 4. Основной путь — официальный Figma MCP; без него — выгрузки от пользователя или REST API (в конце).

Ссылка → fileKey и nodeId

https://www.figma.com/design/<fileKey>/<имя>?node-id=40016871-145809 → fileKey, nodeId 40016871:145809 (дефис в двоеточие). Ссылка на ветку …/design/<fileKey>/branch/<branchKey>/… — вместо fileKey берётся branchKey.

Figma MCP требует прав редактора на файл даже для чтения. Ответ «Looks like you don't have edit access» — попросить у пользователя доступ, а не искать обход.

Выгрузка: download_assets

download_assets(fileKey, nodeId, defaultFormat, defaultScale) возвращает:

  • export — весь узел одним файлом. Нужен только он;
  • svgAssets — иконки поддерева и сообщение, что их больше двадцати. К ролику не относятся.

Ссылка в export временная — скачать сразу:

curl -sSL -o "assets/<ролик>/_raw/svg/<имя>.svg" "<ссылка export>"

В Windows PowerShell 5.1 curl — псевдоним другой команды; писать curl.exe.

Выгрузка MCP рисует всё, что лежит под узлом: фон страницы, заливки родителей, серый прямоугольник #EBEBEB под инстансом. Прозрачного PNG компонента так не получить, а get_screenshot выше 1x не отдаёт. Отсюда правило: компонент крупно — только очищенный SVG.

Компонент крупно — SVG и чистка

Для variants, scaleSteps, composite и SVG-ячеек grid:

  1. download_assets(fileKey, <узел варианта или инстанса>, defaultFormat: "svg");
  2. скачать export в assets/<ролик>/_raw/svg/<имя>.svg;
  3. очистить:
python -I tools/clean_figma_svg.py assets/<ролик>/_raw/svg/<имя>.svg assets/<ролик>/svg/<имя>.svg

Скрипт оставляет только группу самого узла с её <defs> и печатает размер — он обязан совпасть с width × height узла из get_metadata. Текст в выгрузке уже переведён в кривые: шрифт не нужен, на другой машине кадр выглядит так же.

Корень узла скрипт ищет по очереди:

  1. группа с обрезкой, чей контур начинается в начале координат узла;
  2. группа варианта — в её id Figma пишет «Prop=Value, …»;
  3. группа с именем из --name — для экземпляра без обрезки содержимого:
python -I tools/clean_figma_svg.py <сырой.svg> assets/<ролик>/svg/x1.svg --name "Toolbar AF"

«Корень узла не найден» после всех трёх — сказать пользователю. Не подменять кадр PNG молча.

Матрица — PNG и нарезка

Для grid с большим числом мелких ячеек (11×6 у Current Product AF). Ячейки показываются в треть натуральной величины, поэтому хватает 1x.

  1. download_assets(fileKey, <матрица>, defaultFormat: "png", defaultScale: 1) → assets/<ролик>/_raw/matrix-1x.png. Размер картинки равен размеру матрицы из get_metadata;
  2. нарезать по координатам инстансов из get_metadata. Скрипт сохранить в файл средствами записи файлов (не через heredoc в Windows) и запустить python -I <файл>:
from pathlib import Path
from PIL import Image

colX = [0, 367, 734, 1101, 1468, 1835]          # x колонок из get_metadata
cellW = 343
rows = [(53, [88, 88, 122, 128, 134, 140]),      # (y строки, высоты ячеек по колонкам)
        (217, [88, 88, 122, 128, 134, 140])]
src = Image.open("assets/<ролик>/_raw/matrix-1x.png")
out = Path("assets/<ролик>/grid")
out.mkdir(parents=True, exist_ok=True)
for r, (y, hs) in enumerate(rows):
    for c, (x, h) in enumerate(zip(colX, hs)):
        src.crop((x, y, x + cellW, y + h)).save(out / f"r{r}-c{c}.png")

Те же colX, cellW и rows идут в данные сцены, src — "assets/<ролик>/grid/r{r}-c{c}.png".

Подложку в углах ячеек срезает движок контуром сглаженного угла Astra Fintech (clip: true). У компонента с другим углом подложка проступит — тогда ячейки выгружаются SVG по одной, как крупные кадры, и в данных clip: false. Так же поступать с маленькой матрицей (2×2–3×3): SVG-ячейки чётче.

Экраны — PNG 2x

Для phones, device, flow: download_assets(fileKey, <фрейм экрана 375×812>, defaultFormat: "png", defaultScale: 2) → assets/<ролик>/screens/<имя>.png, 750×1624.

Если экраны стоят рядом в одном фрейме — выгрузить фрейм целиком и нарезать тем же скриптом, умножив координаты из get_metadata на 2.

Слои страниц для flow (страница «до», «после», лист поверх) выгружаются каждый отдельно, тоже 2x.

Без Figma MCP

Пользователь выгружает сам. Попросить: выделить узел → панель Export → SVG, в настройках включить «Outline text». Экраны и матрицу — PNG 2x и 1x. Ручная выгрузка обычно уже без подложки, но её всё равно прогнать через clean_figma_svg.py и сверить размер; если скрипт не нашёл корень, а подложки в файле нет — взять файл как есть.

REST API с личным токеном Figma (у пользователя, в переменной окружения, в файлы не писать):

GET https://api.figma.com/v1/images/<fileKey>?ids=<nodeId>&format=svg&svg_outline_text=true&svg_include_id=true

Ответ — ссылка на файл, дальше как с export. Этот путь в шаблоне не обкатан: после чистки обязательно сверить размер и посмотреть кадр на снимке.

Геометрию без MCP — размеры вариантов, сетку матрицы — пользователь может прочитать в панели Inspect Figma или прислать скриншот с размерами. Числа в данные — только из макета, не на глаз.