Export Icons

Export Icons (@sxl-studio/export-icons): утилита командной строки, которая скачивает иконки из компонентов Figma в папку проекта. Она экспортирует узлы COMPONENT и каждый вариант COMPONENT_SET, запоминает, что уже скачано, и при следующем запуске забирает только изменения. Из того же набора она собирает иконочный шрифт и SF Symbols для iOS.

#Быстрый старт

1. Установите пакет в проект. Нужен Node.js 20.9 или новее.
2. Запишите токен Figma и ключ файла в .env (см. раздел «Доступ к Figma» ниже).
3. Создайте конфиг мастером: он задаёт несколько вопросов и пишет валидный файл.
4. Проверьте конфиг и посмотрите изменения через --dry-run.
5. Запустите синхронизацию. Если в папке уже лежат скачанные ранее иконки, добавьте к первому запуску --adopt-existing: файлы будут приняты как базовое состояние, а не скачаны заново.

npm install --save-dev @sxl-studio/export-icons
pnpm exec sxl-export-icons init --wizard
pnpm exec sxl-export-icons validate-config --config sxl-export-icons.config.yaml
pnpm exec sxl-export-icons sync --config sxl-export-icons.config.yaml --dry-run
pnpm exec sxl-export-icons sync --config sxl-export-icons.config.yaml --adopt-existing
pnpm exec sxl-export-icons sync --config sxl-export-icons.config.yaml

С pnpm установленный бинарник запускается как pnpm exec sxl-export-icons, с npm как npx sxl-export-icons. Для разового запуска без установки используйте npx @sxl-studio/export-icons или pnpm dlx @sxl-studio/export-icons. Не используйте pnpx sxl-export-icons: в приватных registry он может попытаться найти unscoped-пакет sxl-export-icons и завершиться с 404.

#Когда использовать

• Иконки живут в библиотеке Figma и должны попадать в репозиторий файлами: со стабильными именами и без ручного экспорта.
• Одни и те же иконки нужны в нескольких форматах или размерах, например SVG для веба и превью в WebP.
• Из того же набора нужно собрать иконочный шрифт или SF Symbols.
• Иконки меняются часто, и вы хотите скачивать только изменения: из терминала или в CI.

#Доступ к Figma

1. Откройте настройки аккаунта Figma и создайте personal access token со scopes file_content:read и file_metadata:read. Права на запись не нужны. Токены Figma ограничены по сроку, выберите срок по вашей политике.
2. Возьмите ключ файла из URL: https://www.figma.com/design/<fileKey>/....
3. Сохраните оба значения в .env в корне репозитория и добавьте .env и .env.local в .gitignore.

FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxxx
SXL_ICONS_FILE_KEY=xxxxxxxxxxxx
# только для Bridge: mode: mcp, Figma Motion, экспорт через плагин
BRIDGE_AUTH_TOKEN=xxxxxxxxxxxx

CLI читает .env.local и .env из текущей папки и из всех родительских. Имена переменных можно поменять в конфиге: env.figmaTokenVar, sources[].fileKeyVar, bridge.authTokenVar.

#Команды

create-config равнозначно init, init-wizard равнозначно init --wizard. Без --config CLI ищет в текущей папке sxl-export-icons.config.yaml, icons.config.yaml, config/sxl-export-icons.config.yaml и config/icons.config.yaml.

#Флаги sync

#Флаги других команд

#Мастер настройки

init --wizard работает только в интерактивном терминале. Вопросы по порядку: язык (en или ru), создать ли .env с пустыми переменными, путь к state-файлу, разрешить ли пути вне проекта, идентификатор источника, режим источника (rest или mcp), переменная с ключом файла, имя страницы, скорость скачивания, идентификатор цели, папка вывода, формат (svg, png, jpg, webp, gif или pdf), стиль имён, иконочный шрифт (папка и форматы), SF Symbols (папка) и фильтр по marker в описании. Результат: конфиг version: 3 с шаблоном имени {prefix}{variant.style}{sectionName}{baseName}{suffix}. Для mp4 и webm добавьте motion.enabled: true вручную.

#Конфигурация

Конфиг: YAML-файл с version: 3. sources описывают, откуда читать иконки, targets описывают, куда и как их записывать. Относительные пути считаются от папки конфига.

version: 3
env:
  figmaTokenVar: FIGMA_TOKEN
bridge:
  baseUrl: http://127.0.0.1:37830
  authTokenVar: BRIDGE_AUTH_TOKEN
state:
  file: .sxl/cache/icons-state.json
safety:
  allowOutsideWorkspace: false
sources:
  - id: icons
    mode: rest
    fileKeyVar: SXL_ICONS_FILE_KEY
    pageName: Icons
targets:
  - id: web-svg
    sourceIds: [icons]
    output:
      path: assets/icons/svg
      format: svg

Конфиг version: 2 (icons.config.yaml) по-прежнему читается и мигрирует на лету; его относительные пути считаются от папки, из которой запущена команда.

#Источники (sources)

sources:
  - id: mono
    mode: rest
    fileKeyVar: SXL_ICONS_FILE_KEY
    pageName: Monochrome
    sectionName: Actions
    downloadSpeed: 20
    descriptionExportMarker:
      key: sxl-studio-export-icon
      includeWhenMissing: true

selectors:
  variantMatch:
    state: [default, hover]
    style: outlined

Селекторы работают и на уровне цели (targets[].selectors), и внутри переопределения (overrides[].patch.selectors); там они фильтруют только иконки этой цели или правила.

Marker в описании. Напишите sxl-studio-export-icon: true или sxl-studio-export-icon: false в описании компонента или набора компонентов. true экспортирует иконку, false пропускает, а без marker действует includeWhenMissing. Имя ключа настраивается.

#Цели (targets)

targets:
  - id: web-icons
    mode: sync
    sourceIds: [mono]
    download:
      enabled: true
      pruneUntracked: false
    output:
      path: assets/icons
      format: svg
      scale: 1
      quality: 100
      lossless: false
      unsafeSvgPolicy: fail
    naming:
      case: kebab
      pattern: "{prefix}{variant.style}{sectionName}{baseName}{suffix}"
      collisionStrategy: add-nodeid

#Настройки output

SVG оптимизируются через SVGO, растровые файлы через Sharp. webp и статический gif экспортируются из Figma как PNG и конвертируются локально; pdf приходит из Figma как есть.

#Имена файлов

Имя файла собирается из naming.pattern. Токены, пустые для конкретной иконки, пропускаются; остальные соединяются через separator и приводятся к case.

Без pattern имя складывается из prefix, свойства style (или variant), секции, если она включена, имени набора или компонента и suffix.

Дубли проверяются перед скачиванием. В интерактивном терминале CLI перечисляет их и спрашивает, что делать: refresh перечитывает Figma после того, как вы поправили имена, skip оставляет первую иконку из каждой пары, all скачивает всё и применяет стратегию коллизий, abort останавливает. Выбор стрелками и Enter. В CI, без терминала, стратегия из конфига применяется без вопросов.

#Переопределения (overrides)

Переопределения меняют output, sourceExport, naming, motion, font или sfSymbols для иконок, подходящих под правило, и могут добавить selectors.

targets:
  - id: web-icons
    sourceIds: [mono]
    output:
      path: assets/icons
      format: svg
    overrides:
      - name: flags-webp
        match:
          sectionName: Flags
        patch:
          output:
            format: webp
            quality: 85

match принимает pageName, pageId, sectionName, sectionId, componentName, componentSetName, nodeId и variantMatch. Изменение переопределения переэкспортирует только те иконки, которые под него подходят.

#Несколько форматов, источников и конфигов

• Несколько форматов одних и тех же иконок: несколько целей с одинаковым sourceIds и разными output.path и format.
• Несколько страниц или секций одного файла: несколько источников с одинаковым fileKeyVar и разными pageName или sectionName.
• Несколько файлов Figma: несколько источников с разными fileKeyVar; цель может перечислить их все в sourceIds.
• Несколько пакетов: запустите sync с несколькими флагами --config или с --config-glob.

#SVG со встроенными изображениями

Figma может вернуть неполный SVG для векторного слоя с заливкой изображением. Перед записью файлов CLI проверяет иконки каждой SVG-цели на этот случай.

• unsafeSvgPolicy: fail (по умолчанию): sync останавливается и перечисляет иконки. Исправьте их в Figma, если результат должен остаться векторным.
• unsafeSvgPolicy: embed-png: такие иконки скачиваются из Figma как PNG в масштабе output.scale (до 4) и оборачиваются в SVG со встроенным изображением, поэтому файл не зависит от временной ссылки Figma. Содержимое растровое и размывается при увеличении. Такие SVG нельзя использовать для шрифта и SF Symbols, поэтому держите их в отдельной цели без этих конвейеров, например отобранной через includeComponentNames.

--dry-run показывает, какие иконки получат встроенный PNG; в JSON-отчёте они перечислены в svgExport.embeddedPng.

#Растровый экспорт через плагин

По умолчанию растровые форматы рендерит Figma REST API в масштабе output.scale, не больше 4. Когда из маленького вектора нужен большой растр, например WebP 128 px из иконки 24 px, попросите плагин SXL Studio отрендерить промежуточное изображение: sourceExport.transport: plugin. sourceExport задаётся на уровне цели и внутри overrides[].patch.

Требования экспорта через плагин:

• output.format: png, jpg, webp или gif; нельзя совмещать с motion.enabled.
• Bridge запущен, плагин SXL Studio открыт в исходном файле с включённым Remote Connect. За один sync экспорт через плагин работает только с одним файлом Figma; остальные файлы разделите по конфигам или через --target.
• У источника есть fileKey или fileKeyVar, в том числе в mode: mcp. CLI сверяет его с открытым документом до записи файлов.
• В промежуточном изображении уже должно быть достаточно пикселей: CLI не увеличивает локально. Поднимите constraint.value, если видите ошибку о том, что источник меньше запрошенного размера.
• Ограничения на иконку: стороны до 4096 px, 16 миллионов пикселей, 16 МиБ PNG или JPG.

Community-версия плагина. Community-сборка плагина может не знать ключ открытого файла. Откройте Repository connection в SXL Studio (то же поле есть в настройках Git Sync), заполните Figma file URL or key и сохраните. Ключ хранится в документе для всех; после дублирования файла введите его заново. Если ключ отсутствует или не совпадает с источником, sync останавливается.

Пример: вектор 24x24 из секции Illustrations рендерится Figma в 128 px и сохраняется как WebP 128x128 без потерь.

overrides:
  - name: illustrations-webp-128
    match:
      sectionName: Illustrations
    patch:
      output:
        format: webp
        width: 128
        height: 128
        quality: 100
        lossless: true
      sourceExport:
        transport: plugin
        format: png
        constraint:
          type: WIDTH
          value: 128

--dry-run печатает, сколько иконок пойдёт через плагин; JSON-отчёт записывает каждую из них с форматом и ограничением.

#Анимированные иконки (Figma Motion)

Иконки, анимированные в Figma Motion, экспортирует обычный sync, если у цели задано motion.enabled: true.

Требования: Bridge запущен, плагин SXL Studio открыт в том же файле с включённым Remote Connect, а источник либо rest с ключом файла, либо mcp. Цели с Motion переэкспортируются при каждом sync: данные анимации приходят из плагина, а не из снимка файла, который сравнивает отслеживание изменений.

targets:
  - id: motion-webm
    sourceIds: [icons]
    output:
      path: assets/motion
      format: webm
    motion:
      enabled: true
      fps: 30
      loop: true

Чтобы увидеть, что Figma сообщает об анимированной иконке до настройки цели, запустите probe-motion. Без --node-id проверяется текущее выделение в Figma.

pnpm exec sxl-export-icons probe-motion --format MP4,WEBM,GIF,SVG --inspect-only
pnpm exec sxl-export-icons probe-motion --node-id 1:2 --format SVG --include-id-attribute

#Иконочный шрифт и SF Symbols

Оба конвейера работают внутри цели после скачивания и берут SVG-файлы этой цели.

font:
  enabled: true
  path: assets/icons/font
  formats: [woff2, woff, ttf, eot, svg]
  fontName: icons
  engine: webfonts-generator
sfSymbols:
  enabled: true
  path: assets/icons/ios

SF Symbols пропускают иконки с градиентами, фильтрами, масками и встроенными изображениями.

Чтобы собрать шрифт или SF Symbols из SVG, которые уже лежат на диске, используйте цель convert-local: sourceIds: [], download.enabled: false, output.format: svg и хотя бы один включённый font или sfSymbols. Запускайте её отдельно через --target.

targets:
  - id: icons-font-only
    mode: convert-local
    sourceIds: []
    download:
      enabled: false
    output:
      path: assets/icons
      format: svg
    font:
      enabled: true
      path: assets/icons/font
      includeNames: [filled-menu, outline-menu]

#Состояние и отслеживание изменений

CLI запоминает каждую экспортированную иконку в state.file, по парам sourceId::targetId. При следующем запуске он сравнивает Figma с state и обрабатывает только разницу.

• Первый запуск без state: каждая иконка NEW и скачивается, даже если файлы есть. --adopt-existing вместо этого принимает существующие файлы как UNCHANGED.
• --full очищает state и экспортирует всё заново.
• download.pruneUntracked: true дополнительно удаляет файлы формата цели, о которых state не знает.
• report показывает по парам, сколько иконок отслеживается, на месте ли файлы и в каких форматах.
• clean удаляет отслеживаемые файлы и папки шрифта и SF Symbols, затем очищает state; --skip-aux сохраняет эти папки, --dry-run только перечисляет.

#Если что-то не работает

#Связанные страницы

• Bridge
• Transformer
• Токены в код
• Экспорт изображений