Figma Code Connect — полный гайд¶

Code Connect — это мост между вашей кодовой базой и Dev Mode в Figma, связывающий компоненты в репозиториях напрямую с компонентами в файлах дизайна. После настройки эти связи расширяют возможности сервера Figma MCP по предоставлению AI-агентам более точных деталей реализации за счёт прямых ссылок на ваш фактический код.

Информация

Доступно на тарифном месте (seat) Dev или Full в рамках планов Organization и Enterprise

Code Connect CLI¶

Сделайте дизайн-систему легко доступной для разработчиков и создайте единый источник правды как для дизайна, так и для кода.

Наше руководство по началу работы проведёт вас через настройку Code Connect CLI и публикацию первых компонентов. Начало работы с Code Connect CLI →

Code Connect UI¶

Code Connect UI позволяет связывать компоненты прямо в Figma с интеграцией GitHub для доступа к репозиторию и контекста сопоставления. Code Connect UI поддерживает связи «один ко многим», позволяя сопоставить один дизайн-компонент с несколькими реализациями в коде на разных фреймворках и языках (например, React, Vue). Это упрощает масштабирование для команд дизайна и разработки; в планах — автоматическое сопоставление и расширенная поддержка фреймворков. Начало работы с Code Connect UI →

Информация

Code Connect UI и Code Connect CLI можно использовать вместе — связи, созданные через CLI, отображаются в UI, но редактировать их можно только в CLI. В обоих случаях связи используются для предоставления более полного контекста кода через сервер Figma MCP.

Файлы шаблонов (рекомендуется)¶

Рекомендуемый способ использования Code Connect CLI — файлы шаблонов: подход, не привязанный к фреймворку, при котором вы пишете файлы TypeScript, определяющие, как именно должны выглядеть ваши сниппеты кода. Файлы шаблонов работают с любой кодовой базой независимо от фреймворка или языка и дают полный контроль над генерацией кода.

Button.figma.ts

// url=https://www.figma.com/file/your-file-id/Button?node-id=123
import figma from 'figma';

const instance = figma.selectedInstance;

export default {
    example: figma.code`
    <Button
      size={${instance.getEnum('Size', { Large: 'large', Medium: 'medium', Small: 'small' })}}
      disabled={${instance.getBoolean('Disabled')}}
    >
      ${instance.getString('Text Content')}
    </Button>
  `,
    imports: ['import { Button } from "components/Button"'],
    id: 'button',
};

Подробнее о файлах шаблонов →

Если вы используете AI-агент для кодирования, навык figma-code-connect поможет создать шаблоны Code Connect по URL компонента Figma. Подробнее обо всех навыках Figma см. в Справочном центре.

Устаревшие API, специфичные для фреймворков¶

Code Connect CLI также включает интеграции для конкретных фреймворков. Наши руководства по интеграции проведут вас через сопоставление пропсов (props) и вариантов для:

React (и React Native) →
HTML (например, Web Components, Angular и Vue) →

Публикация в Figma для упрощения передачи в разработку¶

После публикации ваши компоненты будут доступны в Dev Mode Figma и покажут соответствующие продакшену сниппеты кода из дизайн-системы вместо автоматически сгенерированных примеров.

Начало работы с Code Connect UI¶

Информация

Доступно на тарифном месте (seat) Dev или Full в рамках планов Organization и Enterprise

Требуется файл библиотеки Figma с опубликованными дизайн-компонентами

Code Connect UI позволяет сопоставить дизайн-компоненты в библиотеках Figma с соответствующими компонентами кода в репозитории. Эти сопоставления расширяют возможности сервера Figma MCP, предоставляя AI-агентам прямые ссылки на ваш код и обеспечивая более точные рекомендации по реализации.

Примечание

Компоненты, подключённые через Code Connect UI, не отображают сниппеты кода на панели Inspect. Сейчас показываются только путь к файлу и имя компонента (если указаны), а также поддерживаются превью AI-сгенерированных сниппетов кода. Чтобы отображать сниппеты кода в Inspect, используйте Code Connect CLI.

Подключение компонентов из библиотеки дизайна¶

В Figma откройте файл библиотеки с дизайн-компонентами.
Переключитесь в Dev Mode.
В выпадающем меню рядом с именем файла выберите Library → Connect components to code (Библиотека → Подключить компоненты к коду).

Откроется Code Connect UI со списком всех опубликованных компонентов библиотеки. Отсюда можно начать сопоставление компонентов с кодовой базой.

Подключение репозитория GitHub (необязательно)¶

Информация

Подключение к GitHub необязательно. Вы можете сопоставить компоненты дизайн-системы с путями в коде вручную без подключения к GitHub.

Нажмите значок Параметры в Code Connect UI, чтобы подключить репозиторий к GitHub.

Подключение к GitHub даёт дополнительные возможности:

Поля сопоставления автодополняются путями к файлам из репозитория.
Можно просматривать и искать компоненты напрямую в GitHub.

Ручное подключение компонентов¶

Без подключения к GitHub вы всё равно можете создавать сопоставления, вводя вручную:

Путь к компоненту в кодовой базе (например, src/components/Button.tsx)
При необходимости — имя компонента (например, Button)

Все сопоставления передаются серверу Figma MCP. Когда используется сопоставленный дизайн-компонент, его контекст кода включается в данные, отправляемые AI-агентам.

Примечание

При работе в IDE Code Connect также может предлагать встроенные подсказки (открытая бета-версия) через удалённый сервер MCP. Эти подсказки в реальном времени показывают релевантные сопоставления компонентов и обновления кода, помогая синхронизировать дизайн и код.

Подключение компонентов из выбранного фрейма¶

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

Если во фрейме есть несопоставленные компоненты, у сервера MCP не будет полного контекста, и результаты могут быть менее точными.
На панели Inspect в Dev Mode нажмите Connect components (Подключить компоненты), чтобы открыть Code Connect UI. Так можно подключить недостающие компоненты для текущего фрейма.
После добавления сопоставления сразу передаются серверу MCP и используются как контекст, повышая точность AI-сгенерированных результатов.

Подключение одного компонента к нескольким фреймворкам¶

Code Connect UI поддерживает связи «один ко многим», позволяя сопоставить один дизайн-компонент с несколькими компонентами кода на разных языках или фреймворках. Например, дизайн-компонент Button можно одновременно связать с реализациями на React, и Vue.

Это полезно, когда дизайн-система поставляет компоненты для нескольких платформ. Каждая связь независима: для каждого фреймворка можно указать разные пути к файлам, имена компонентов и пользовательские инструкции.

Добавление нескольких связей¶

В Code Connect UI прокрутите до дизайн-компонента, который нужно подключить.
Если компонент ещё не подключён — подключите его.
При наведении на строку компонента появится кнопка добавления, позволяющая подключить ещё один компонент кода.
Укажите путь к файлу и имя нового компонента кода (например, src/components/Button.tsx).
Повторите для каждого дополнительного фреймворка или языка.

Добавление пользовательских инструкций для генерации кода AI¶

После подключения компонента к кодовой базе можно добавить дополнительный контекст, чтобы AI-агенты генерировали лучший код. Это особенно полезно для компонентов со специфическими паттернами использования, требованиями доступности или соглашениями команды.

Добавление инструкций для MCP¶

Для любого подключённого компонента можно добавить пользовательские инструкции, которые ваш LLM будет использовать через сервер Figma MCP:

В Code Connect UI выберите подключённый компонент.
Нажмите кнопку Add instructions for MCP (Добавить инструкции для MCP).
Напишите промпты, описывающие, как следует использовать компонент, включая:
- Конкретные пропсы (props) или паттерны конфигурации
- Соображения по доступности
- Типичные сценарии использования или варианты
- Соглашения по коду, принятые в команде

Эти инструкции отправляются вместе с сопоставлением компонента на сервер MCP, помогая AI генерировать код, лучше соответствующий реализации вашей дизайн-системы.

Превью AI-сгенерированных сниппетов кода¶

Чтобы проверить, что сопоставления и инструкции дадут нужный код, можно просмотреть AI-сгенерированные сниппеты прямо в Code Connect UI:

Выберите подключённый компонент в Code Connect UI.
Измените свойства дизайн-компонента, чтобы проверить разные конфигурации (например, размеры, состояния или варианты кнопки).
Посмотрите превью сниппета кода, чтобы увидеть, что ваш LLM сгенерировал бы на основе:
- Сопоставления компонента
- Пользовательских инструкций для MCP
- Текущих значений свойств

Это превью помогает уточнить инструкции и убедиться, что AI сгенерирует подходящий код для всех вариантов компонента.

Информация

Сниппеты в превью генерируются в ином контексте, чем при реальных запросах к серверу MCP. Поэтому код в превью может немного отличаться от того, что ваш LLM выдаст при фактическом использовании, когда у него есть полная история диалога и дополнительный контекст.

Подключение репозитория GitHub¶

Подключение репозитория GitHub к Figma позволяет Code Connect UI обращаться к кодовой базе, упрощая и ускоряя сопоставление компонентов и предоставляя дополнительный контекст об этих сопоставлениях.

Информация

GitHub Enterprise Server (GHES) не поддерживается.

Что даёт интеграция¶

При подключении репозитория GitHub к Code Connect UI в Figma становятся доступны следующие возможности:

Подсказки из кодовой базы: поля сопоставления компонентов автодополняются путями к файлам и именами компонентов из репозитория, что ускоряет создание точных сопоставлений.
Расширенный контекст для AI через MCP: подключённые компоненты дают более богатый контекст серверу Figma MCP. Когда AI-агенты работают с вашими макетами, они получают прямые ссылки на фактическую реализацию в коде.
Пользовательские инструкции для LLM: для каждого сопоставленного компонента можно добавить инструкции через функцию «Add instructions for MCP». Эти промпты помогают LLM генерировать более подходящий код при работе с конкретными компонентами, чтобы AI-код соответствовал паттернам и лучшим практикам вашей команды.

Подключение файла библиотеки¶

Примечание

Вы должны быть владельцем файла, который подключаете к GitHub, или администратором организации.

Откройте Code Connect UI в файле библиотеки Figma.
Нажмите значок Параметры.
Выберите Connect to GitHub (Подключить к GitHub). Войдите в учётную запись GitHub с доступом к нужному репозиторию.
По запросу предоставьте доступ к:
- Всем репозиториям в вашей учётной записи.
- Конкретным репозиториям, в которых находятся компоненты вашей дизайн-системы.

Авторизация доступа¶

Следующий шаг зависит от вашей роли в организации GitHub, для которой вы запрашиваете авторизацию:

Если у вас есть права администратора
1. Выберите Install and Authorize (Установить и авторизовать), чтобы предоставить Figma доступ.
2. Подтвердите, к каким репозиториям Figma может обращаться.
Если прав администратора нет
1. Выберите Request access (Запросить доступ).
2. Будет отправлен запрос администратору организации; он должен одобрить доступ, прежде чем вы сможете продолжить.

Информация

Обзор запрашиваемых разрешений при авторизации через GitHub см. в Обзор разрешений приложения GitHub →

Подключение к репозиторию¶

После завершения авторизации выберите один репозиторий для подключения к файлу библиотеки Figma. К одному файлу библиотеки можно подключить только один репозиторий.
Укажите каталоги в этом репозитории, в которых находятся UI-компоненты.
Эти каталоги станут доступны в Code Connect.

Сравнение Code Connect UI и Code Connect CLI¶

Code Connect предлагает два способа связать дизайн-компоненты в Figma с продакшен-кодом: Code Connect UI и Code Connect CLI. Оба участвуют в одной инфраструктуре MCP, но отличаются интеграцией в рабочий процесс, доступом к коду и контекстом, который они передают MCP.

Обзор¶

Code Connect CLI ориентирован на разработчиков и запускается локально в репозитории. Позволяет задавать сопоставление свойств, генерировать динамические примеры кода и опубликовать связи в Figma из терминала. Встроенные парсеры для React, Web Components, а также поддержка документации Code Connect на JavaScript дают и глубину в популярных фреймворках, и гибкость для любого языка. Подходит командам разработки, которым нужны точность и контроль.

Code Connect UI рассчитан на доступность и совместную работу. Работает целиком в Figma, поэтому сопоставления можно создавать прямо в файлах дизайна или библиотеках без установки. При подключении к репозиторию GitHub получает пути и имена компонентов в кодовой базе и связывает их с дизайн-компонентами. Также можно вручную указать путь и имя компонента без подключения к репозиторию. Code Connect UI поддерживает связи «один ко многим: один дизайн-компонент можно сопоставить с несколькими реализациями на разных фреймворках и языках (например, React, Vue). Пока нет сопоставления свойств и динамических примеров, но подход не привязан к языку, прост в настройке и хорошо масштабируется для команд дизайна и разработки.

Сравнение возможностей¶

Возможность	Code Connect CLI	Code Connect UI
Контекст MCP	Путь к компоненту, имя компонента, сопоставление свойств и динамические примеры кода	Путь к компоненту, имя компонента, пользовательский промпт и контекст компонента из кодовой базы
Пользовательский опыт	Локально в репозитории; публикация из терминала	Интеграция с Figma; сопоставление прямо в файлах дизайна или библиотеках; сейчас ограничено одной кодовой библиотекой
Доступ к кодовой базе	Локально на вашей машине и в репозитории	Подключение к репозиторию через Figma
Фреймворк и язык	Парсеры для React, Web Components; документация на JS для любого языка	Достаточно пути к коду и имени компонента; не привязан к языку; связи «один ко многим» между фреймворками
Сниппеты кода	Показывает сниппеты кода дизайн-системы на панели Inspect.	Показывает путь к файлу и имя компонента (если указаны); поддерживает превью AI-сгенерированных сниппетов кода.

Начало работы с Code Connect CLI¶

В этом руководстве мы настроим Code Connect CLI с использованием файлов шаблонов — рекомендуемого подхода для связи компонентов дизайна с кодом. Файлы шаблонов не зависят от фреймворка и дают полный контроль над фрагментами кода, отображаемыми в Figma.

Мы пройдём по шагам:

Установка Code Connect CLI
Настройка проекта
Создание первого файла шаблона — с помощью AI-агента для кодирования или вручную
Опубликовать в Figma
Дальнейшие шаги

Перед началом¶

Для использования этого руководства вам нужна кодовая база дизайн-системы с компонентами и библиотека дизайна в Figma (файл Figma с корневыми компонентами дизайн-системы).

Для практики по руководству вы можете опционально использовать Simple Design System (SDS) от Figma. Если вы хотите использовать SDS:

Откройте community file Simple Design System в Figma и при запросе выберите Make a copy (Создать копию). Community file SDS содержит компоненты дизайн-системы.
Клонируйте репозиторий sds. Репозиторий содержит кодовые компоненты, которые вы подключите к вашей копии файла SDS.

Требования

Для установки и использования Code Connect необходимо:

Установить Node.js 18 или новее
Сгенерировать персональный токен доступа с областью Code Connect Write и областью File content Read.

Установка инструмента командной строки Code Connect¶

Для использования Code Connect сначала нужно установить инструмент командной строки Code Connect. Он позволяет подключать компоненты, публиковать их и снимать с публикации.

Самый простой способ установки — через Node Package Manager (npm). Для установки используйте:

npm install --global @figma/code-connect@latest

Конфиденциальность и Code Connect¶

Figma собирает только минимальный объём данных, необходимый для работы Code Connect в интерфейсе. При запуске figma connect через интерфейс командной строки Code Connect Figma получает следующие данные:

Пути к добавленным компонентам
URL репозитория, в котором реализованы компоненты Code Connect
Свойства и код в файлах .figma

Figma логирует только базовые события для понимания использования Code Connect: когда компоненты опубликованы или сняты с публикации, и вызовы получения данных Figma при использовании интерфейса командной строки.

Дополнительную информацию о подходе Figma к конфиденциальности см. в политике конфиденциальности Figma.

Настройка проекта¶

Создайте файл figma.config.json в корне проекта:

{
    "codeConnect": {
        "include": ["**/*.figma.ts"],
        "label": "React",
        "language": "jsx"
    }
}

Значения label и language определяют, как фрагменты кода помечаются в Figma. Измените их в соответствии с вашей кодовой базой.

Если вы используете TypeScript, добавьте определения типов шаблонов в tsconfig.json для автодополнения и проверки типов в файлах шаблонов:

tsconfig.json

{
    "compilerOptions": {
        "types": ["@figma/code-connect/figma-types"]
    }
}

Создание файлов шаблонов с помощью AI-агента¶

Если вы используете агента с поддержкой Figma MCP server, навык figma-code-connect создаёт файлы шаблонов за вас. Укажите на компонент или фрейм Figma — и он сгенерирует файлы .figma.ts в вашем репозитории, готовые к публикации через CLI.

Навык выполняет ту же работу, что описана в следующем разделе: разбирает URL Figma, определяет компоненты в выделении без Code Connect mapping, читает определения их свойств, находит соответствующий кодовый компонент в репозитории и создаёт файл шаблона с заполненными сопоставлениями свойств. Проверьте результат, при необходимости скорректируйте, затем опубликуйте.

Для использования навыка необходимо:

Агент с установленным Figma MCP server. Инструкции по настройке см. в Подключение к удалённому серверу Figma MCP.
Навык figma-code-connect установлен в агенте. Самый простой способ — установить плагин Figma для вашей IDE, который включает все навыки Figma. Альтернативно — установить навык вручную из репозитория mcp-server-guide.
Code Connect CLI установлен и figma.config.json настроен, как описано выше.

Полные инструкции навыка и используемый API см. в figma-code-connect/SKILL.md. О всех навыках Figma для MCP server см. в Help Center.

После создания файлов шаблонов опубликуйте их в Figma так же, как файлы, написанные вручную.

Создание первого файла шаблона вручную¶

Файлы шаблонов связывают компонент Figma с фрагментом кода. Они используют расширение .figma.ts (или .figma.js) и располагаются рядом с кодовыми компонентами.

Для подключения компонента Figma:

В Figma щёлкните правой кнопкой мыши на компонент и выберите Copy link to selection, чтобы получить URL.
Создайте файл .figma.ts для вашего компонента. Имя файла должно соответствовать имени компонента, например Button.figma.ts:

Button.figma.ts

// url=https://www.figma.com/file/your-file-id/Button?node-id=123
import figma from 'figma';

const instance = figma.selectedInstance;

const label = instance.getString('Label');
const disabled = instance.getBoolean('Disabled');
const size = instance.getEnum('Size', {
    Large: 'large',
    Medium: 'medium',
    Small: 'small',
});

export default {
    example: figma.code`
    <Button size={${size}} disabled={${disabled}}>
      ${label}
    </Button>
  `,
    imports: ['import { Button } from "components/Button"'],
    id: 'button',
};

Файл состоит из трёх основных частей:

Метаданные в комментарии (// url=...): связывает этот файл с конкретным компонентом Figma. URL должен указывать на компонент в файле дизайн-системы (в Figma щёлкните правой кнопкой на компонент и выберите Copy link to selection).
Доступ к свойствам: используйте методы figma.selectedInstance для чтения свойств компонента Figma и сопоставления их с значениями в коде. Часто используются getString, getBoolean, getEnum и getInstanceSwap.
export default: определяет фрагмент кода (example), операторы import для отображения в начале фрагмента и уникальный id для этого шаблона.

Полный API шаблонов, включая все доступные методы и расширенные возможности, см. в Writing template files.

Publish Code Connect files¶

Чтобы видеть фрагменты Code Connect для компонентов в Dev Mode, сначала нужно опубликовать файлы:

В корне репозитория выполните следующую команду с вашим персональным токеном доступа:
1
npx figma connect publish --token=PERSONAL_ACCESS_TOKEN
Где PERSONAL_ACCESS_TOKEN — токен доступа к API Figma, который вы сгенерировали.

Примечание

Опционально можно использовать переменную окружения FIGMA_ACCESS_TOKEN для передачи персонального токена доступа в инструмент командной строки Code Connect. При использовании переменной окружения параметр --token не нужен.

Инструмент опубликует ваши файлы Code Connect и вернёт список имён компонентов и URL соответствующих узлов.
Чтобы посмотреть сопоставленные компоненты в Figma, щёлкните ссылки в списке после публикации. Ссылки откроют соответствующие компоненты в файле дизайн-системы Figma.
На панели инструментов щёлкните Dev Mode. Фрагмент кода из Code Connect появится в панели Inspect в правой боковой панели.

Unpublish Code Connect files¶

При проблемах с сопоставлениями или необходимости отключить компонент можно снять файл Code Connect с публикации. Для этого используйте:

npx figma connect unpublish --node=NODE_URL --label=LABEL

Где NODE_URL — URL конкретного узла в файле дизайн-системы, а label — тип для снятия с публикации, например «React» или «Vue».

Информация

Важно: если не указать URL узла, Code Connect снимет с публикации все компоненты, определённые в директории файлов Code Connect. При вопросах о других настройках используйте флаг --help для списка всех доступных параметров.

Следующие шаги¶

После публикации первого файла шаблона можно изучить следующее:

Writing template files →: полный API шаблонов, включая вложенные компоненты, условный рендеринг и другие возможности.
Template API reference →: полный справочник всех доступных методов и типов.
Configuration →: расширенные параметры конфигурации для figma.config.json.
Framework-specific APIs: Code Connect также поддерживает интеграции для конкретных фреймворков: React (и React Native), HTML/Web Components.

Настройка проекта¶

Code Connect настраивается через файл figma.config.json, который должен находиться в корне проекта (например, рядом с package.json или .xcodeproj).

Для каждой платформы доступны общие параметры конфигурации в дополнение к платформо-специфичным.

Общие параметры конфигурации¶

`include` и `exclude`¶

include и exclude — списки glob-паттернов для мест, где разбирать файлы Code Connect, и для поиска кодовых компонентов при использовании интерактивной настройки. Пути в include и exclude должны быть относительными к расположению файла конфигурации.

{
    "codeConnect": {
        "include": [],
        "exclude": ["test/**", "docs/**", "build/**"]
    }
}

`parser`¶

Code Connect определяет тип проекта по корневой директории:

Если найден package.json с react, проект определяется как React
Если найден package.json без react, проект определяется как HTML
Если найден файл Package.swift или *.xcodeproj, проект определяется как Swift
Если найден файл build.gradle.kts, проект определяется как Jetpack Compose

Если фреймворк проекта определён неверно, можно задать тип проекта через ключ parser в figma.config.json. Допустимые значения: react, html, swift и compose.

{
    "codeConnect": {
        "parser": "react"
    }
}

`label`¶

label позволяет указать метку, отображаемую в Figma для фрагментов Code Connect. По умолчанию метка соответствует типу проекта, например React. Другая метка для фрагментов в Dev Mode может быть полезна, например для отображения разных версий кода.

Для HTML-проектов Code Connect устанавливает метку по умолчанию на основе HTML-фреймворков, обнаруженных в первом родительском package.json рабочей директории, соответствующем одному из следующих:

Если найден package.json с angular, метка устанавливается в Angular
Если найден package.json с vue, метка устанавливается в Vue
В остальных случаях метка устанавливается в Web Components

`language`¶

language позволяет указать язык для подсветки синтаксиса фрагментов Code Connect в Figma Dev Mode. Полезно при необходимости переопределить автоматически определённый язык или при использовании настройки без парсера.

Допустимые значения для language:

jsx
typescript
swift
kotlin
html
plaintext
cpp
ruby
css
javascript
json
graphql
python
go
sql
rust
bash
xml
tsx
dart

Пример:

{
    "codeConnect": {
        "language": "typescript"
    }
}

Если указаны и label, и language, для подсветки синтаксиса приоритет имеет language, а label определяет, как фрагмент помечается в Figma.

`interactiveSetupFigmaFileUrl`¶

interactiveSetupFigmaFileUrl позволяет указать файл Figma для интерактивной настройки. При наличии в figma.config.json этот URL автоматически используется как URL файла Figma для подключения компонентов.

Если figma.config.json уже существует, можно добавить этот параметр в существующий файл.

{
    "codeConnect": {
        "interactiveSetupFigmaFileUrl": "https://www.figma.com/design/abc123/my-design-system"
    }
}

`documentUrlSubstitutions`¶

documentUrlSubstitutions позволяет задать набор подстановок, применяемых к URL figmaNode при разборе или публикации документов.

Это даёт возможность использовать несколько файлов figma.config.json для публикации фрагментов Code Connect для разных файлов Figma без изменения каждого файла Code Connect. Например, подстановки можно использовать для тестовой версии компонентов Code Connect.

Подстановки задаются объектом: ключ — строка для замены, значение — строка замены.

Рассмотрим пример:

{
    "codeConnect": {
        "documentUrlSubstitutions": {
            "https://figma.com/design/1234abcd/File-1": "https://figma.com/design/5678dcba/File-2"
        }
    }
}

Подстановка в примере выше преобразует URL узлов Figma, например https://figma.com/design/1234abcd/File-1/?node-id=12:345, в https://figma.com/design/5678dbca/File-2/?node-id=12:345.

`defaultBranch`¶

defaultBranch позволяет указать имя основной ветки репозитория, когда она не может быть определена автоматически. Code Connect использует это при генерации ссылок на исходный код в Figma.

{
    "codeConnect": {
        "defaultBranch": "release"
    }
}

Конфигурация проекта для React¶

{
    "codeConnect": {
        "parser": "react",
        "include": [],
        "exclude": ["test/**", "docs/**", "build/**"],
        "importPaths": {
            "src/components/*": "@ui/components"
        },
        "paths": {
            "@ui/components/*": ["src/components/*"]
        }
    }
}

`importPaths`¶

importPaths позволяет переопределить относительные пути импорта кодовых компонентов в файлах Code Connect. Указание пути импорта полезно, когда пользователям дизайн-системы нужно импортировать компоненты из конкретного пакета, а не из директории относительно файлов Code Connect. Пути должны быть локальными.

Пути задаются в объекте importPaths: ключ — путь для сопоставления и переопределения, значение — путь для использования вместо него.

Например, кодовый компонент Button.tsx находится в ./src/components/ (относительно корня проекта). В той же директории — соответствующий файл Code Connect Button.figma.tsx:

import { Button } from './';
figma.connect(Button, 'https://...');

Для импорта Button нужно переопределить относительный путь (./) и указать другой путь импорта. В figma.config.json добавьте:

{
    "codeConnect": {
        "importPaths": {
            "src/components/*": "@ui/components"
        }
    }
}

В importPaths ключ src/components/* с wildcard * включает все кодовые компоненты в этой директории, включая Button.tsx. Значение задано как @ui/components. При следующем использовании Code Connect CLI для управления файлами файл Code Connect для Button обновится:

import { Button } from '@ui/components';

`paths`¶

При использовании path aliases в конфигурации TypeScript необходимо задать paths в figma.config.json, чтобы Code Connect мог разрешать импорты. Объект paths в конфигурации Code Connect должен соответствовать объекту paths в tsconfig.json проекта.

`imports`¶

Можно переопределить генерируемые операторы import для подключённого компонента, передав массив imports. Полезно, когда автоматическое разрешение не подходит для вашего случая.

figma.connect(Button, 'https://...', {
    imports: ["import { Button } from '@lib'"],
});

Написание файлов шаблонов¶

Файлы шаблонов предоставляют независимый от фреймворка способ связать ваш код с компонентами Figma. Вместо парсеров для конкретных фреймворков вы пишете TypeScript-файлы, которые явно определяют, как ваши компоненты должны отображаться. Этот подход проще в сопровождении, гибче и мощнее, чем API для конкретных фреймворков.

Файлы шаблонов дают полный контроль над генерацией кода, поэтому они идеальны, когда вам нужно:

Связи независимые от фреймворка: подключить любую codebase, независимо от фреймворка или языка
Точный контроль кода: генерировать именно тот код, который вам нужен, без парсерных API

Мы активно инвестируем в файлы шаблонов как основной формат Code Connect. Если вы начинаете новую интеграцию Code Connect или хотите участвовать в формировании её будущего, мы рекомендуем попробовать и оставить отзыв.

Совет

Если вам нужно подключить большое количество компонентов с одинаковой структурой кода — например, библиотеку иконок — см. Batch files-файлы) для более эффективного подхода, который позволяет не создавать один файл шаблона на каждый компонент.

Совет

Если вы используете AI-агента для кодирования, figma-code-connect skill помогает писать шаблоны Code Connect из URL компонента Figma. Подробнее обо всех skills от Figma см. в Help Center.

Настройка¶

Убедитесь, что в figma.config.json указаны файлы .figma.ts (или .figma.js), и задайте label и language (см. Настройка проекта):

{
    "codeConnect": {
        "include": ["**/*.figma.ts"],
        "label": "React",
        "language": "jsx"
    }
}

При использовании TypeScript добавьте определения типов шаблонов в tsconfig.json, чтобы редактор мог предоставлять автодополнение и проверку типов в файлах шаблонов:

tsconfig.json

{
    "compilerOptions": {
        "types": ["@figma/code-connect/figma-types"]
    }
}

Напишите файл .figma.ts (см. Формат файла шаблона)
Опубликуйте файлы шаблонов в Figma, когда будете готовы:

npx figma connect publish

Формат файла шаблона¶

Файлы шаблонов связывают ваш код с компонентом в Figma и определяют, как инстансы этого компонента должны отображаться в фрагменте кода. Пример файла:

MyComponent.figma.ts

// url=https://www.figma.com/file/your-file-id/Component?node-id=123
import figma from 'figma';

const instance = figma.selectedInstance;

const labelText = instance.getString('Label');
const iconInstance = instance.findInstance('Icon');

export default {
    example: figma.code`
    <MyComponent
      label={${labelText}}
      icon={${iconInstance.executeTemplate().example}}
    />
  `,
    imports: ['import MyComponent from "components/MyComponent"'],
    id: 'my-component',
    metadata: {
        nestable: true,
    },
};

Метаданные в комментариях¶

Каждый файл шаблона должен начинаться с блока специальных комментариев в следующем формате:

url — компонент Figma, к которому опубликован ваш шаблон. В Figma щёлкните правой кнопкой мыши на компонент и выберите «Copy link to selection» (Копировать ссылку на выделение) или скопируйте URL из браузера.
source (необязательно) — путь к файлу (или URL) вашего кодового компонента. Отображается в Figma.
component (необязательно) — имя вашего кодового компонента. Отображается в Figma.

// url=https://www.figma.com/file/your-file-id/Component?node-id=123
// source=src/components/MyButton.tsx
// component=MyButton

Построение фрагмента¶

Пример фрагмента — основная часть файла шаблона; он описывает, как фрагмент кода должен выглядеть в соответствии с инстансом компонента Figma.

Доступ к свойствам инстанса¶

Используйте методы на figma.selectedInstance для чтения свойств из вашего компонента Figma:

import figma from 'figma';

const instance = figma.selectedInstance;

// Get the value of the Figma instance "Label" string property
const label = instance.getString('Label');

// Get the value of the Figma instance "Disabled" boolean property
const disabled = instance.getBoolean('Disabled');

// Map the possible values of the "Size" enum property to code values
// (e.g. if the Figma "Size" property is "Small", map to 'sm' in code)
const size = instance.getEnum('Size', {
    Small: 'sm',
    Medium: 'md',
    Large: 'lg',
});

Работа с вложенными инстансами¶

Чтобы включить вложенные инстансы компонентов (например, иконку внутри кнопки), используйте findInstance() или getInstanceSwap() для поиска дочернего элемента, затем вызовите executeTemplate() для его отображения:

import figma from 'figma';

const instance = figma.selectedInstance;

// Find a nested instance by layer name
const iconInstance = instance.findInstance('Icon');

// Get the snippet from the nested instance
const iconSnippet = iconInstance.executeTemplate().example;

Информация

Важно: хотя фрагменты записываются в строкоподобной синтаксисе, под капотом они используют структуру массива, чтобы pills и ошибки могли отображаться корректно.

При построении фрагмента важно не выполнять строковые операции (например, конкатенацию) на них. Вместо этого оборачивайте их в figma.code:
1
figma.code`<MyExample/>${showIcon ? iconSnippet : null}`;

Работа со слотами¶

Слоты — свойства компонентов, которые создают гибкие области внутри компонента и позволяют свободно редактировать содержимое. В коде слоты обычно соответствуют children или пропсам content, например children в React.

Когда компонент Figma имеет свойство слота, используйте getSlot() для его ссылки в шаблоне:

import figma from 'figma';

const instance = figma.selectedInstance;

// Get the slot property named "Content"
const content = instance.getSlot('Content');

В Dev Mode слот отображается как кликабельная подпись с именем свойства слота. Клик по ней выбирает слой слота в дизайне. remote Figma MCP server также может пройти в слот, чтобы получить детали layout и любое вложенное содержимое.

Чтобы отобразить код для инстансов компонентов, размещённых прямо в слоте, используйте свойство connectedInstances. Каждый элемент — InstanceHandle, поэтому вызовите executeTemplate() для включения связанного примера:

import figma from 'figma';

const slot = figma.selectedInstance.getSlot('Actions');
const actions = slot.connectedInstances.map(
    (action) => action.executeTemplate().example,
);

const example = figma.code`<ActionBar>${actions.flat()}</ActionBar>`;

Включаются только инстансы с собственными определениями Code Connect. Поиск поверхностный: текст, слои, несвязанные инстансы и инстансы вложенные внутри другого инстанса опускаются.

Выбор между слотами и `findConnectedInstances`¶

Оба подхода работают с вложенным содержимым, но правильный выбор зависит от предсказуемости этого содержимого.

Используйте getSlot(), когда слот может содержать свободное содержимое: дополнительный layout, смешанные типы компонентов или другие фреймы с разной структурой. Слот отображается как кликабельная подпись в Dev Mode и позволяет Figma MCP server пройти внутрь него.

Используйте getSlot().connectedInstances, когда слот содержит code-connected компоненты, которые могут различаться по типу и порядку, и вы хотите отобразить их код inline. В отличие от findConnectedInstances(), это ограничивает поиск конкретным свойством слота без необходимости селектора.

Используйте findConnectedInstances() и отображайте children inline, когда все дочерние элементы имеют один и тот же тип компонента и вы хотите полностью развернуть их код прямо во фрагменте родителя. Например, меню выбора, которое содержит только элементы списка:

import figma from 'figma';

const instance = figma.selectedInstance;

// List variant: all children are the same type, render them inline
const options = instance
    .findConnectedInstances((node) => node.hasCodeConnect())
    .map((child) => child.executeTemplate().example);

const example = figma.code`<Select>${options}</Select>`;

findConnectedInstances принимает два параметра:

selectorFn: (node: InstanceHandle) => boolean: фильтрует, какие дочерние инстансы включать. Аргумент node предоставляет методы, такие как hasCodeConnect(), codeConnectId() и name, для сужения совпадений.
opts (необязательно):
- traverseInstances: boolean — при true выполняет рекурсивный поиск через вложенные инстансы, а не только среди прямых дочерних элементов. По умолчанию false.
- path: string[] — ограничивает совпадения инстансами на конкретной позиции в иерархии слоёв, выражённой как упорядоченный список имён родительских слоёв.

import figma from 'figma';

const instance = figma.selectedInstance;

// Custom variant: slot content is freeform, renders as a clickable label in the inspect panel
const content = instance.getSlot('Content');

const example = figma.code`<Select>${content}</Select>`;

Отображение фрагмента¶

В конце постройте пример, записав ваш код обёрнутый в figma.code:

import figma from 'figma';

const instance = figma.selectedInstance;

const example = figma.code`Button(
  variant = ButtonVariant.Primary
)`;

Полный API, включая все доступные методы, хелперы и продвинутые возможности, см. в Template API Reference.

Формат экспорта¶

Файл шаблона должен содержать default export в следующем формате:

export default {
  example: ResultSection[],
  imports: string[]
  id: string,
  metadata?: {
    nestable?: boolean,
    props?: Record<string, any>,
  }
}

example — построенный вами фрагмент. Важно: он должен быть обёрнут в figma.code`<MyExample/>`
imports — массив строк, которые будут отображаться в начале фрагмента. Если фрагмент вложен, импорты поднимаются наверх и дедуплицируются.
id — идентифицирует этот шаблон Code Connect, позволяя другим шаблонам ссылаться на него
metadata
- nestable (необязательно) — должен ли фрагмент отображаться inline при вложении в родителя. При false отображается как кликабельная ссылка
- props (необязательно) — делает данные доступными родительским шаблонам через executeTemplate().metadata.props

Скрипт миграции¶

Информация

Если у вас есть отзыв или проблемы со скриптом, сообщите нам, создав GitHub issue.

Инструмент командной строки Code Connect предлагает скрипт для локального создания файлов шаблонов из существующих файлов Code Connect. Поскольку создаются новые файлы, мы рекомендуем сначала закоммитить незакоммиченные изменения в codebase. Также рекомендуем использовать --outDir для тестирования — это упрощает публикацию и отмену публикации новых файлов.

По умолчанию скрипт миграции сканирует текущий проект Code Connect с использованием настроек include/exclude из figma.config.json. Чтобы мигрировать папку или поддерево, ограничьте include/exclude в figma.config.json. Используйте --file для миграции одного или нескольких точных файлов из выбранного проекта.

По умолчанию скрипт миграции выводит файлы .figma.ts. Если нужен JavaScript, передайте флаг --javascript:

npx figma connect migrate [options]

Опции:

--file <file...> — мигрировать один или несколько конкретных файлов Code Connect. Если не указано, мигрируются все файлы в проекте.
--outDir <dir> — записать файлы шаблонов в указанную директорию вместо размещения рядом с исходными файлами
--javascript — выводить файлы .figma.js вместо стандартных .figma.ts
--delete — удалить исходные файлы Code Connect после успешной миграции
--batch <auto|all|none> — контроль пакетной миграции. По умолчанию auto — пытается мигрировать исходные файлы с 10 или более связями Code Connect. Используйте all для попытки миграции каждого выбранного исходного файла или none для отключения пакетной миграции.
--include-props — сохранить блоки метаданных __props в результате миграции. По умолчанию они удаляются, так как являются деталями реализации parser-based файлов и не нужны в файлах шаблонов. Передайте этот флаг при использовании модификаторов React .getProps() или .render(), или если другие файлы шаблонов читают executeTemplate().metadata.__props из мигрированных компонентов.

Полная ссылка на команду см. в CLI reference.

Мигрированные файлы¶

Считайте результат миграции отправной точкой, а не готовым к production Code Connect. Файлы будут отображаться корректно, но обычно есть возможности упростить их — удалить ненужные хелперы, очистить избыточные пропсы и реструктурировать логику вариантов. См. разделы ниже для самых частых областей проверки.

Для большинства parser-based файлов Code Connect скрипт миграции создаёт один файл шаблона на каждую связь. Есть два исключения:

Файлы с ограничениями вариантов мигрируются в один файл шаблона с логикой ветвления.
Исходные файлы с 10 или более связями Code Connect автоматически рассматриваются для вывода batch file-файлы). Если связи могут разделять одну безопасную форму шаблона, скрипт миграции создаёт один файл .figma.batch.ts и один .figma.batch.json. Если пакетирование небезопасно, скрипт показывает предупреждение и возвращается к обычному выводу одного шаблона на связь.

Передача --batch all пытается выполнить пакетную миграцию для каждого выбранного исходного файла Code Connect, даже если в нём меньше 10 связей. Полезно для файлов, которые вы знаете, что должны пакетироваться, и хорошо работает с --file:

npx figma connect migrate --file src/icons.figmadoc.tsx --batch all

Передача --batch none пропускает автоматические попытки пакетирования и всегда использует обычный вывод шаблонов.

Мигрированные файлы шаблонов используют figma.helpers для корректного отображения кода. Если вы точно знаете, как должен выглядеть код, может быть проще удалить некоторые из них. Например, если вы отображаете обязательный проп в React, который всегда имеет известный тип, то этот код:

figma.code`<Counter${figma.helpers.react.renderProp('count', count)} />`;

Можно упростить до:

figma.code`<Counter count={${count}} />`;

Проверка пакетной миграции¶

Автоматическая пакетная миграция намеренно консервативна. Она создаёт batch только когда каждая связь в исходном файле может быть сведена к одной совместимой форме шаблона с читаемыми параметрами figma.batch.*. Например, обычно справляется с файлами в стиле иконок, где имя компонента, id, import member или простые именованные значения, такие как name="..." или size={...}, различаются между связями. Она избегает параметризации произвольного текста, сложных выражений, алиасов или несвязанных форм шаблонов.

При успешном пакетировании проверьте оба созданных файла:

Файл .figma.batch.ts должен быть легко читаемым и содержать только поля, общие для каждой связи.
Файл .figma.batch.json должен содержать Figma url для каждой связи и любые значения, различающиеся между связями.

При неудачном пакетировании мигрированные обычные файлы шаблонов всё равно валидны. Если вы хотите вручную преобразовать их в batch files, можете использовать этот промпт с AI-агентом для кодирования:

Я мигрировал Code Connect на основе парсеров в файлы шаблонов. Некоторые из сгенерированных файлов связаны между собой и достаточно похожи, чтобы заменить их одним batch JSON-файлом и шаблоном.

Сначала прочитай документацию, чтобы понять точный формат: https://developers.figma.com/docs/code-connect/batch-files/

Найди файлы шаблонов, которые хорошо подходят для преобразования в batch-файлы, и мигрируй их. Будь внимателен и пропускай те, которые нельзя мигрировать чисто.

Предпочитай крупные группы, например наборы иконок. Небольшие группы пропускай, если выигрыш неочевиден.

При тестировании в репозитории без локального бинарника figma CLI используй:
npx --yes --package @figma/code-connect figma connect parse --file {path}

Если добавляешь JSON-файлы, убедись, что они включены в figma.config.json, например `**/*.figma.batch.json`.

Отдельные файлы шаблонов удаляй только после того, как batch-файл успешно парсится и сохраняет ту же документацию Code Connect.

Проверь до/после с помощью `npx figma connect parse --file {pathToTemplateFileOrBatchJson}`

Ограничения вариантов¶

Компоненты, которые использовали ограничения вариантов (несколько вызовов figma.connect указывающих на один URL Figma с разными объектами variant), мигрируются в один файл со структурой ветвления if/else-if/else. Например:

// Migration output
let template;
if (figma.selectedInstance.getPropertyValue('Has Label') === 'true') {
    template = {
        example: figma.code`<InputField label={${label}} />`,
        imports: ['import { InputField } from "./InputField"'],
        id: 'input-field',
    };
} else {
    template = {
        example: figma.code`<Input />`,
        imports: ['import { Input } from "./Input"'],
        id: 'input',
    };
}

export default template;

Эта структура работает, но громоздка и требует больше ручной проверки, чем другой вывод миграции. В большинстве случаев её можно упростить с помощью getBoolean(), getEnum() или стандартной условной логики:

// Cleaned up
const hasLabel = figma.selectedInstance.getBoolean('Has Label');

export default {
    example: hasLabel
        ? figma.code`<InputField label={${label}} />`
        : figma.code`<Input />`,
    imports: hasLabel
        ? ['import { InputField } from "./InputField"']
        : ['import { Input } from "./Input"'],
    id: 'input',
};

При проверке мигрированных файлов вариантов обратите особое внимание на:

Условия с getPropertyValue(): это прямой перевод оригинальных ограничений вариантов, и обычно их можно заменить типизированными методами, такими как getBoolean() или getEnum().
Один компонент Figma сопоставляется с несколькими кодовыми компонентами: когда разные значения свойств должны отображать совершенно разные компоненты (как в примере выше), очищенная версия часто использует тернарный оператор или early return вместо полного блока if/else.
Несколько свойств вариантов объединены через AND: миграция генерирует условия getPropertyValue('A') === 'x' && getPropertyValue('B') === 'y'. Их часто можно упростить или свернуть с помощью getEnum() с объектом сопоставления.

Тестирование в Figma¶

Для тестирования этих изменений в Figma нужно настроить figma.config.json. Мы рекомендуем задать label временным значением, чтобы легко публиковать и отменять публикацию без влияния на существующий Code Connect, и ограничить include только новыми файлами. Подробнее об этих значениях см. в Настройка.

{
    "include": ["**/*.figma.ts"],
    "label": "TEST",
    "language": "jsx"
}

Затем можно опубликовать под временным label для тестирования в Figma:

npx figma connect publish --config <your figma.config.json path>

Когда закончите, можно удалить их из Figma с помощью unpublish:

npx figma connect unpublish --config <your figma.config.json path>

Справочник Template API¶

Template API позволяет создавать шаблоны Code Connect, которые контролируют, как ваши компоненты выводятся в MCP или отображаются в панели Code Connect Figma.

Эта ссылка документирует полный API — от базовой структуры шаблона до продвинутых возможностей, таких как доступ к свойствам и поиск слоёв. Если вы только начинаете, мы рекомендуем сначала прочитать о файлах шаблонов.

`figma`¶

Это основной объект, предоставляющий доступ к данным вашего файла Figma. Вы можете импортировать его в файле шаблона так:

import figma from 'figma';

Формат экспорта¶

Шаблоны должны экспортировать объект в следующем формате:

export default {
  example: figma.code`<code>`, // The rendered code sections
  id: string,               // Your custom identifier (also known as a Code Connect ID) to connect this template with a Figma instance
  metadata?: {
    /**
     * Controls how nested components appear in the Code Connect panel:
     * - true: Component code is shown directly in its parent
     *   Example: Small icons or labels within a button
     * - false: Component appears as a pill that expands on click
     *   Example: Complex components like modals or forms
     */
    nestable?: boolean,

    /**
     * Data that will be available to components that use this instance.
     * See the executeTemplate() method below for details on accessing these props.
     */
    props?: Record<string, any>,
  }
}

Поле id позволяет задать пользовательский идентификатор, также известный как Code Connect ID, для этого шаблона. Вы можете использовать любую строку — этот ID определяет, как другие шаблоны найдут и ссылаются на этот инстанс с помощью методов, таких как findConnectedInstance(id).

Поле metadata содержит необязательные настройки отображения:

nestable: при true показывает код вложенного компонента inline с родителем; при false показывает вложенные компоненты как раскрывающиеся pills
props: делает данные доступными родительским шаблонам через executeTemplate().metadata.props

`figma.selectedInstance:` `InstanceHandle`¶

Объект selectedInstance представляет текущий выбранный слой в документе Figma. Он предоставляет доступ к различным свойствам и методам для взаимодействия с выбранным слоем.

`figma.code`¶

figma.code — tagged template literal для построения фрагментов кода. В него можно интерполировать значения (строки, булевы, enum), вложенные фрагменты кода и вложенные списки отображённых секций.

const iconSnippet = instance.findInstance('Icon').executeTemplate().example
const labelContent = instance.findInstance('Label').executeTemplate().example

const label = figma.code`<label>${labelContent}</label>`

export default {
  example: figma.code`
    <Button disabled={${disabled}}>
      ${iconSnippet}
      ${label}
    </Button>
  `,
  ...
}

Информация

Важно: хотя фрагменты выглядят как template strings, под капотом они используют структуру массива для поддержки кликабельных pills и отображения ошибок. Не выполняйте строковые операции, такие как конкатенация, на значениях фрагментов — всегда композируйте их внутри figma.code:
1
2
3
4
5
// ✓ correct
figma.code`<MyExample />${showIcon ? iconSnippet : null}`;

// ✗ incorrect — breaks rendering
'<MyExample />' + iconSnippet;

`figma.batch`¶

figma.batch доступен в batch template files-файлы) и предоставляет доступ к данным на компонент, определённым в соответствующем файле .figma.batch.json. Включает зарезервированные поля url, source и component, плюс любые дополнительные свойства, определённые для записи компонента.

figma.batch: {
  url: string
  source?: string
  component?: string
  [key: string]: any
}

Полные детали см. в Batch files-файлы).

`figma.helpers`¶

Примечание

Примечание: эти хелперы полезны при работе с широким спектром возможных типов или способов отображения в коде. Часто их можно пропустить, если вы точно знаете, как должен выглядеть код.

Объект figma.helpers предоставляет утилиты для корректного отображения значений шаблона в разных языках и фреймворках. Эти хелперы обрабатывают форматирование, экранирование и отображение сложных значений.

React Helpers¶

Доступны в figma.helpers.react:

`renderProp(name: string, prop: any): string`¶

Отображает React проп корректно в зависимости от типа. Этот хелпер обрабатывает всю сложность форматирования разных типов пропов для JSX.

Примеры:

// Boolean props
figma.helpers.react.renderProp('disabled', true);
// Returns: " disabled"

figma.helpers.react.renderProp('disabled', false);
// Returns: ""

// String props
figma.helpers.react.renderProp('label', 'Click me');
// Returns: ' label="Click me"'

// Number props
figma.helpers.react.renderProp('count', 42);
// Returns: " count={42}"

// Instance/component props
const icon = figma.selectedInstance.getInstanceSwap('Icon');
figma.helpers.react.renderProp('icon', icon?.executeTemplate().example);
// Returns: " icon={<Icon />}" (as sections)

`renderChildren(prop: any): string | ResultSection[]`¶

Отображает React children корректно в зависимости от типа. Обрабатывает строки, числа, булевы значения, инстансы и специальные типы значений.

Примеры:

// String children
figma.helpers.react.renderChildren('Hello')
// Returns: "Hello"

// Instance children
const children = figma.selectedInstance.findConnectedInstances(...)
figma.helpers.react.renderChildren(children.map(c => c.executeTemplate().example))
// Returns: array of ResultSections representing the children

Хелперы типов значений¶

Эти хелперы создают типизированные значения, которые renderProp и renderChildren знают, как форматировать:

jsxElement(value: string) — оборачивает значение для отображения как JSX

figma.helpers.react.jsxElement('<CustomIcon />');
// When used in renderProp: icon={<CustomIcon />}

function(value: string) — оборачивает значение для отображения как функция

figma.helpers.react.function('() => alert("clicked")');
// When used in renderProp: onClick={() => alert("clicked")}

identifier(value: string) — оборачивает значение для отображения как идентификатор

figma.helpers.react.identifier('myVariable');
// When used in renderProp: value={myVariable}

object(value: Record<string, any>) — оборачивает значение для отображения как object literal

figma.helpers.react.object({ color: 'red', size: 'large' });
// When used in renderProp: sx={{ color: "red", size: "large" }}

templateString(value: string) — оборачивает значение для отображения как template literal

figma.helpers.react.templateString('Hello ${name}');
// When used in renderProp: message={`Hello ${name}`}

reactComponent(value: string) — оборачивает значение для отображения как React компонент

figma.helpers.react.reactComponent('MyComponent');
// When used as children: <MyComponent />

array(value: any[]) — оборачивает значение для отображения как массив

figma.helpers.react.array([1, 2, 3]);
// When used in renderProp: items={[1,2,3]}

`renderPropValue(prop: any): string | ResultSection[]`¶

Отображает значение пропа для использования в object literals. Аналогичен renderProp, но форматирует значение для контекстов объектов, а не JSX атрибутов.

Пример:

// Used internally by object literals
const styleObj = {
    color: figma.selectedInstance.getString('color'),
    size: figma.selectedInstance.getEnum('size', { small: 12, large: 16 }),
};
// renderPropValue handles formatting these values correctly

`stringifyObject(obj: any): string`¶

Преобразует объект в строковое представление подходящее для генерации кода. Обрабатывает вложенные объекты и массивы.

Пример:

figma.helpers.react.stringifyObject({ a: 1, b: [2, 3], c: { d: 4 } });
// Returns: "{ a: 1, b: [2,3], c: { d: 4 } }"

`isReactComponentArray(prop: any): boolean`¶

Type guard, проверяющий, является ли значение массивом секций React компонентов (секции CODE, INSTANCE или ERROR).

Примечание: этот хелпер в основном используется внутренне системой отображения, но может быть полезен для продвинутой логики шаблонов.

Объект `InstanceHandle`¶

Свойства¶

`properties: Record<string, string | boolean | InstanceHandle>`¶

Объект, содержащий все свойства инстанса.

Методы¶

`getBoolean(propName: string, options?: Record<string, any>): boolean | any`¶

Получает значение булевого свойства.
Необязательный объект сопоставления может преобразовать булевое значение в любой другой тип.

`getString(propName: string): string`¶

Получает значение строкового свойства.

`getEnum(propName: string, options: Record<string, any>): any`¶

Получает значение enum свойства с необязательным сопоставлением значений.
Объект options сопоставляет значения enum с нужными выходными значениями.

`getSlot(propName: string):` `SlotResult` `| undefined`¶

Получает значение свойства слота.
Возвращает SlotResult или undefined, если свойство слота не найдено или не имеет валидной ссылки.

Примечание

Примечание: для использования слотов нужно установить последнюю версию Code Connect CLI.

`getInstanceSwap(propName: string):` `InstanceHandle`¶

Получает значение свойства инстанса.
Возвращает InstanceHandle для заменённого инстанса.

`getPropertyValue(propName: string): string | boolean`¶

Получает сырое значение свойства.

`executeTemplate(): { example: ResultSection[], metadata: Metadata }`¶

Выполняет шаблон инстанса и возвращает отображённые секции и метаданные.

`hasCodeConnect(): boolean`¶

Возвращает, имеет ли инстанс Code Connect.

`codeConnectId(): string | null`¶

Возвращает Code Connect ID инстанса, если он существует.

`findText(layerName: string, opts?: SelectorOptions):` `TextHandle` `| ErrorHandle`¶

Находит текстовый слой по имени.
Необязательные опции селектора для сопоставления пути и поведения обхода.

`findInstance(layerName: string, opts?: SelectorOptions):` `InstanceHandle` `| ErrorHandle`¶

Находит дочерний инстанс-слой по имени.
Необязательные опции селектора для сопоставления пути и поведения обхода.

`findConnectedInstance(codeConnectId: string, opts?: SelectorOptions):` `InstanceHandle` `| ErrorHandle`¶

Находит дочерний инстанс по его Code Connect ID.
Необязательные опции селектора для сопоставления пути и поведения обхода.

`findConnectedInstances(selectorFn: (node:` `InstanceHandle) => boolean, opts?: SelectorOptions):` `InstanceHandle[]`¶

Находит все дочерние инстансы, соответствующие функции селектора.
Необязательные опции селектора для сопоставления пути и поведения обхода.

`findLayers(selectorFn: (node:` `InstanceHandle` `|` `TextHandle) => boolean, opts?: SelectorOptions): (InstanceHandle` `|` `TextHandle` `| ErrorHandle)[]`¶

Находит все слои (инстансы или текст), соответствующие функции селектора.
Необязательные опции селектора для сопоставления пути и поведения обхода.

Объект `TextHandle`¶

Свойства¶

`textContent: string`¶

Текстовое содержимое текстового слоя.

Объект `SlotResult`¶

SlotResult — значение, возвращаемое getSlot(). Может быть интерполирован в figma.code для отображения кликабельной ссылки на слот.

Свойства¶

`connectedInstances:` `InstanceHandle[]`¶

Code-connected инстансы компонентов, размещённые прямо в слоте.
Поиск поверхностный и опускает текст, слои, несвязанные инстансы и инстансы вложенные внутри другого инстанса.

Для inline отображения связанных примеров вызовите executeTemplate() на каждом инстансе:

const slot = figma.selectedInstance.getSlot('Items');
const items = slot.connectedInstances.map(
    (item) => item.executeTemplate().example,
);

const example = figma.code`<Menu>${items}</Menu>`;

Типы объектов¶

Следующие типы предоставляются пакетом figma и используются во всём API. Вам не нужно определять их самостоятельно — они доступны при import figma from 'figma'.

Секции кода¶

Эти типы определяют, как код представлен в панели Code Connect:

/**
 * Represents a section of code that will be rendered verbatim in the Code Connect panel
 */
type CodeSection = {
    type: 'CODE';
    code: string;
};

/**
 * Represents a child instance that will be rendered either inline or as a pill
 * depending on the nestable property
 */
type InstanceSection = {
    type: 'INSTANCE';
    /** The guid of the instance layer */
    guid: string;
    /** The guid of the backing component */
    symbolId: string;
};

/**
 * Represents a slot that will be rendered as a clickable label
 * linking to the slot layer in the design
 */
type SlotSection = {
    type: 'SLOT';
    /** The guid of the slot layer */
    guid: string;
};

/** Represents an error that will be displayed in the Code Connect panel */
type ErrorSection = {
    type: 'ERROR';
    message: string;
    errorObject?: ResultError;
};

/** The possible sections that can appear in the Code Connect panel */
type ResultSection = CodeSection | InstanceSection | SlotSection | ErrorSection;

Результаты шаблона¶

Эти типы определяют структуру результатов выполнения шаблона:

/** The result of executing a template, returned by executeTemplate() */
type SectionsResult = {
    result: 'SUCCESS';
    data: {
        type: 'SECTIONS';
        sections: ResultSection[];
        language: string;
        metadata?: {
            __props: Record<string, any>;
            [key: string]: any;
        };
    };
};

/** A list of rendered sections, including nested lists created with map() */
type ResultSectionList = Array<ResultSection | ResultSectionList>;

/** Values allowed in a nested template interpolation list */
type TemplateArgValueList = Array<
    | ResultSection
    | TemplateStringResult
    | TemplateArgValueList
    | null
    | undefined
>;

/** The possible values that can be used in template strings */
type TemplateArgValueKind =
    | string
    | number
    | boolean
    | TemplateStringResult
    | TemplateArgValueList
    | null
    | undefined;

type TemplateStringResult = SectionsResult['data'];

Интерфейс Metadata¶

Этот интерфейс определяет, как компоненты отображаются в панели Code Connect:

/** Metadata that can be included in template exports */
interface Metadata {
    /**
     * Controls how nested instances are rendered in the Code Connect panel:
     * - true: The instance's code will be rendered inline within its parent
     * - false: The instance will be shown as a clickable pill that expands when clicked
     *
     * For example:
     * - Set to true for small components like icons that make sense inline
     * - Set to false for complex components that should be viewed separately
     */
    nestable?: boolean;

    /** Props which can be consumed in a parent instance */
    props?: Record<string, any>;
}

Интерфейс Selector Options¶

Этот интерфейс предоставляет дополнительный контроль над методами поиска слоёв:

/** Options for finding layers */
interface SelectorOptions {
    /** List of parent layer names that matches the layer hierarchy */
    path?: string[];
    /** Whether to search through nested instances */
    traverseInstances?: boolean;
}

Типы ошибок¶

Эти типы представляют различные ошибки, которые могут возникнуть при выполнении шаблона:

/** Error when a property is not found */
type PropertyNotFoundErrorObject = {
    type: 'PROPERTY_NOT_FOUND';
    propertyName: string;
};

/** Error when a child layer is not found */
type ChildLayerNotFoundErrorObject = {
    type: 'CHILD_LAYER_NOT_FOUND';
    layerName: string;
};

/** Error when a property type doesn't match expected type */
type PropertyTypeMismatchErrorObject = {
    type: 'PROPERTY_TYPE_MISMATCH';
    propertyName: string;
    expectedType: string;
};

/** Error during template execution */
type TemplateExecutionErrorObject = {
    type: 'TEMPLATE_EXECUTION_ERROR';
};

/** All possible error types */
type ResultError =
    | PropertyNotFoundErrorObject
    | PropertyTypeMismatchErrorObject
    | ChildLayerNotFoundErrorObject
    | TemplateExecutionErrorObject;

Пакетные (batch) файлы¶

Batch-файлы позволяют связать множество компонентов Figma с кодом, используя один общий шаблон. Это рекомендуемый подход, когда у вас большое количество компонентов с одинаковой структурой; наиболее распространённый пример — библиотеки иконок, где сотни или тысячи иконок используют идентичные паттерны кода, но каждая сопоставляется с отдельным узлом Figma.

Без batch-файлов для каждого компонента потребовался бы собственный файл .figma.ts. Batch-файлы сводят это к двум файлам: шаблону (.figma.batch.ts), описывающему структуру кода, и JSON-файлу (.figma.batch.json), в котором перечислены все компоненты с их URL в Figma и любыми пользовательскими данными.

Структура файлов¶

Пакетная интеграция состоит из двух файлов:

Файл	Назначение
`*.figma.batch.ts`	Шаблон, описывающий фрагмент кода
`*.figma.batch.json`	Список компонентов с URL в Figma и пользовательскими данными

Написание batch-шаблона¶

Batch-шаблон структурирован как обычный файл шаблона, с двумя отличиями:

В начале нет комментариев с метаданными (// url=, // source=, // component=). Эти значения задаются в JSON-файле.
Данные для каждого компонента доступны через figma.batch, а не захардкожены.

icons.figma.batch.ts

import figma from 'figma';

const instance = figma.selectedInstance;

const size = instance.getEnum('Size', {
    Small: '16px',
    Medium: '24px',
    Large: '32px',
});

export default {
    example: figma.code`
    <${figma.batch.name} size={${size}} />
  `,
    imports: [`import ${figma.batch.name} from "${figma.batch.importPath}"`],
    id: figma.batch.id,
};

`figma.batch`¶

figma.batch даёт шаблону доступ к данным, определённым в JSON-файле для каждого компонента. Три поля имеют особое значение и соответствуют комментариям с метаданными в обычных файлах шаблонов:

Поле	Обязательное	Заменяет
`url`	Да	`// url=`
`source`	Нет	`// source=`
`component`	Нет	`// component=`

Любые дополнительные поля, которые вы определяете в JSON-файле, например name, id или importPath в примере выше, также доступны в figma.batch. Это позволяет шаблону ссылаться на значения для каждого компонента без захардкоживания, например:

figma.code`<MyComponent ${figma.batch.myCustomField} />`;

Полный тип figma.batch:

figma.batch: {
  url: string
  source?: string
  component?: string
  [key: string]: any
}

Написание JSON-файла¶

JSON-файл определяет, какие компоненты входят в пакет и какие данные каждый из них передаёт в шаблон.

Один шаблон (сокращённый формат)¶

Когда все компоненты используют один шаблон, применяйте сокращённый формат с templateFile и массивом components:

icons.figma.batch.json

{
    "templateFile": "./icons.figma.batch.ts",
    "components": [
        {
            "url": "https://www.figma.com/design/ABC/File?node-id=1-1",
            "name": "Icon24Arrow",
            "id": "icon-arrow",
            "importPath": "@company/icons/arrow",
            "source": "./src/icons/Icon24Arrow.tsx"
        },
        {
            "url": "https://www.figma.com/design/ABC/File?node-id=1-2",
            "name": "Icon24Check",
            "id": "icon-check",
            "importPath": "@company/icons/check",
            "source": "./src/icons/Icon24Check.tsx"
        }
    ]
}

Каждая запись в components должна содержать url. Все остальные поля передаются в шаблон как свойства объекта batch.

Несколько шаблонов¶

Если batch-файл охватывает компоненты с разными шаблонами, используйте массив на верхнем уровне:

design-system.figma.batch.json

[
    {
        "templateFile": "./icons.figma.batch.ts",
        "components": [
            {
                "url": "https://www.figma.com/design/ABC/File?node-id=1-1",
                "name": "Icon24Arrow",
                "id": "icon-arrow",
                "importPath": "@company/icons/arrow"
            }
        ]
    },
    {
        "templateFile": "./buttons.figma.batch.ts",
        "components": [
            {
                "url": "https://www.figma.com/design/ABC/File?node-id=2-1",
                "name": "PrimaryButton",
                "id": "button-primary",
                "importPath": "@company/buttons/primary"
            }
        ]
    }
]

Настройка¶

Обнаружение¶

CLI обнаруживает batch-файлы через тот же механизм include/exclude, что и все остальные файлы Code Connect. Glob-паттерны по умолчанию уже включают **/*.figma.batch.json, поэтому batch-файлы работают из коробки в проектах без пользовательского include в figma.config.json.

Если в проекте задан пользовательский список include, добавьте glob для batch-файлов явно:

figma.config.json

{
    "codeConnect": {
        "include": ["**/*.figma.ts", "**/*.figma.batch.json"],
        "label": "React",
        "language": "jsx"
    }
}

Файлы шаблонов (.figma.batch.ts), на которые ссылается templateFile, не обязаны присутствовать в include. Они читаются по требованию, когда CLI обрабатывает JSON-файл.

Публикация¶

После подготовки файлов публикуйте их так же, как любые другие файлы Code Connect:

npx figma connect publish

Каждая запись в массиве components публикуется как отдельный документ Code Connect. Снятие с публикации также работает автоматически: каждый компонент удаляется индивидуально по URL узла Figma.

Полный пример¶

Ниже приведён полный пример подключения библиотеки иконок, где каждая иконка поддерживает вариант Size и импортируется из уникального для этой иконки пути пакета.

icons.figma.batch.ts

import figma from 'figma';

const instance = figma.selectedInstance;

const size = instance.getEnum('Size', {
    Small: '16px',
    Medium: '24px',
    Large: '32px',
});

const iconSnippet = figma.code`
  <${figma.batch.name} size={${size}} />
`;

const importsList = figma.batch.withOutline
    ? figma.batch.name
    : [figma.batch.name, 'IconOutline'].join(', ');

export default {
    example: figma.batch.withOutline
        ? figma.code`
    <IconOutline>${iconSnippet}</IconOutline>
  `
        : iconSnippet,
    imports: [`import { ${importsList} } from "${figma.batch.importPath}"`],
    id: figma.batch.id,
    metadata: {
        nestable: true,
    },
};

icons.figma.batch.json

{
    "templateFile": "./icons.figma.batch.ts",
    "components": [
        {
            "url": "https://www.figma.com/design/XYZ/Icons?node-id=10-1",
            "name": "ArrowIcon",
            "id": "icon-arrow",
            "withOutline": false,
            "importPath": "@acme/icons",
            "source": "./src/icons/ArrowIcon.tsx"
        },
        {
            "url": "https://www.figma.com/design/XYZ/Icons?node-id=10-2",
            "name": "CheckIcon",
            "id": "icon-check",
            "withOutline": true,
            "importPath": "@acme/icons",
            "source": "./src/icons/CheckIcon.tsx"
        },
        {
            "url": "https://www.figma.com/design/XYZ/Icons?node-id=10-3",
            "name": "CloseIcon",
            "id": "icon-close",
            "withOutline": true,
            "importPath": "@acme/icons",
            "source": "./src/icons/CloseIcon.tsx"
        }
    ]
}

См. справочник Template API для полного API, доступного внутри batch-шаблона.

Миграция с парсеров на файлы шаблонов¶

Информация

Ранее Code Connect требовал фреймворк-специфичные парсеры для React, iOS, Android и Web Components. Мы представили новый Template API, который убрал зависимость от фреймворков и позволяет пользователям гибче управлять отображением фрагментов кода в Figma. В дальнейшем новым пользователям следует выбирать этот формат шаблонов, а существующим — следовать приведённому ниже руководству по миграции. После 17 августа 2026 года мы перестанем обновлять и активно поддерживать устаревшие парсеры.

В этом руководстве описаны изменения в том, как пользователям следует писать файлы Code Connect, и как выполнить миграцию на формат файлов шаблонов.

Code Connect больше не поддерживает фреймворк-специфичные парсеры¶

Ранее Code Connect основывался на раннем проектном решении: рассматривать файл Code Connect как строку, а не выполнять его. Это делало возможной проверку типов и инструменты IDE, но также вводило жёсткие ограничения, с которыми было сложно работать.

Поскольку файлы Code Connect не выполнялись как код внутри Figma, условная логика — тернарные операторы и switch — попадала в вывод дословно, а не вычислялась при выборе экземпляра. Например, базовые операции со строками также были недоступны в Code Connect. Хотя мы улучшили исходный API Code Connect для поддержки таких случаев, оставалось много пограничных ситуаций вокруг того, какой код считался допустимым в Code Connect.

Новый Template API и файлы шаблонов работают иначе. Ваш шаблон — это функция, которая выполняется и возвращает строку, то есть вы пишете его так же, как любой другой код — с условиями, интерполяцией строк и произвольно сложной логикой. Этот формат также сделал данные Figma доступными как входные параметры. По сути, всё, что является допустимым JavaScript или TypeScript, допустимо в шаблоне. Этот подход также означает, что Code Connect работает одинаково независимо от фреймворка, на котором построена ваша дизайн-система.

В результате получается настройка, которую проще освоить, в которой легче разобраться и которая мощнее того, что позволяли парсеры. Путь миграции спроектирован как максимально малозатратный, а вывод в Figma будет идентичен тому, что у вас есть сейчас.

Зачем выполнять миграцию¶

Мы в целом рекомендуем всем пользователям мигрировать на файлы шаблонов, поскольку их проще писать и поддерживать, чем Code Connect на основе парсеров. Если вы сейчас поддерживаете файлы Code Connect или планируете писать новые, особенно стоит сначала мигрировать на файлы шаблонов. Файлы шаблонов также будут получать обновления и поддержку со временем, например при несовместимостях или проблемах безопасности. Команда migrate, описанная ниже, предназначена для детерминированного преобразования ваших файлов и является самым быстрым способом миграции Code Connect.

Хотя мы рекомендуем мигрировать до 17 августа 2026 года, парсеры останутся доступны через старые версии Code Connect CLI, поэтому вы также можете мигрировать позже.

Миграция файлов Code Connect с помощью команды migrate¶

Мы понимаем, что многие пользователи потратили значительное время на создание документации Code Connect. Для помощи Code Connect CLI теперь предлагает команду миграции для детерминированного преобразования существующих файлов Code Connect в новый формат файлов шаблонов. Команда сначала разбирает весь проект в поисках объектов Code Connect, затем сохраняет эти объекты как файлы шаблонов (.figma.ts). Хотя новые файлы отличаются по формату от исходных файлов Code Connect, вывод в Figma и в MCP будет тем же. Когда результат вас устроит, вы можете опубликовать их в Figma и удалить старые файлы Code Connect.

Совет

Если в вашей организации не разрешён TypeScript и нужен вывод на JavaScript, передайте флаг --javascript при запуске инструмента миграции.

npx figma connect migrate [options]

Опции:

--outDir <dir> — записать файлы шаблонов в указанную директорию вместо размещения рядом с исходными файлами
--javascript — выводить файлы .figma.js вместо .figma.ts по умолчанию
--delete — удалить исходные файлы Code Connect после успешной миграции
--include-props — сохранить блоки метаданных __props в результате миграции. По умолчанию они удаляются, поскольку являются деталью реализации файлов на основе парсеров и не нужны в файлах шаблонов. Передайте этот флаг, если используете модификаторы React .getProps() или .render(), либо если у вас есть другие файлы шаблонов, читающие executeTemplate().metadata.__props из мигрированных компонентов.

Мигрированные файлы¶

Важно рассматривать результат миграции как отправную точку, а не готовый к продакшену Code Connect. Файлы будут отображаться корректно, но обычно есть возможности упростить их, например: удалить ненужные вспомогательные функции, очистить избыточные props и реструктурировать логику вариантов. См. разделы ниже для наиболее распространённых областей проверки.

Мигрированные файлы шаблонов используют figma.helpers для корректного отображения кода. Если вы точно знаете, как должен выглядеть ваш код, может быть проще удалить часть из них. Например, если вы отображаете обязательный prop в React, который всегда имеет известный тип, то этот код:

1	figma.code`<Counter${figma.helpers.react.renderProp('count', count)} />`

Можно упростить до:

1	figma.code`<Counter count={${count}} />`

Ограничения вариантов¶

Компоненты, использовавшие ограничения вариантов в устаревшем CLI (несколько вызовов figma.connect, указывающих на один URL Figma с разными объектами variant), мигрируются в один файл со структурой ветвления if/else-if/else. Например:

// Migration output
let template;
if (figma.selectedInstance.getPropertyValue('Has Label') === 'true') {
    template = {
        example: figma.code`<InputField label={${label}} />`,
        imports: ['import { InputField } from "./InputField"'],
        id: 'input-field',
    };
} else {
    template = {
        example: figma.code`<Input />`,
        imports: ['import { Input } from "./Input"'],
        id: 'input',
    };
}

export default template;

Эта структура работает, но многословна и требует больше ручной проверки, чем остальной результат миграции. В большинстве случаев её можно упростить с помощью getBoolean(), getEnum() или стандартной условной логики:

// Cleaned up
const hasLabel = figma.selectedInstance.getBoolean('Has Label');

export default {
    example: hasLabel
        ? figma.code`<InputField label={${label}} />`
        : figma.code`<Input />`,
    imports: hasLabel
        ? ['import { InputField } from "./InputField"']
        : ['import { Input } from "./Input"'],
    id: 'input',
};

При проверке мигрированных файлов с вариантами обратите особое внимание на:

Условия с getPropertyValue(): это прямой перевод исходных ограничений вариантов, и их обычно можно заменить типизированными методами вроде getBoolean() или getEnum().
Один компонент Figma, сопоставленный с несколькими компонентами кода: когда разные значения свойств должны отображать совершенно разные компоненты (как в примере выше), упрощённая версия часто использует тернарный оператор или ранний return вместо полного блока if/else.
Несколько свойств вариантов, объединённых через AND: миграция генерирует условия getPropertyValue('A') === 'x' && getPropertyValue('B') === 'y'. Их часто можно упростить или свернуть с помощью getEnum() и объекта сопоставления.

Тестирование в Figma¶

Для проверки этих изменений в Figma потребуется настроить figma.config.json. Мы рекомендуем задать label временным значением, чтобы легко публиковать и снимать с публикации, не затрагивая существующий Code Connect, и ограничить include только новыми файлами. Подробнее об этих значениях см. Настройка проекта.

{
    "include": ["**/*.figma.ts"],
    "label": "TEST",
    "language": "jsx"
}

Затем можно опубликовать под временной меткой для проверки в Figma:

npx figma connect publish --config <your figma.config.json path>

Когда закончите, можно удалить их из Figma с помощью unpublish:

npx figma connect unpublish --config <your figma.config.json path>

¶

Использование MCP skill для создания файлов шаблонов¶

Если вы используете плагин Figma с одобренным MCP Client, можно воспользоваться встроенным skill Code Connect для создания файлов шаблонов по URL Figma. Агент изучит свойства компонента, найдёт соответствующий компонент кода в вашем проекте и напишет файл .figma.ts за вас.

Предварительные требования¶

Claude Code с установленным плагином Figma
Компонент Figma, опубликованный в библиотеке команды
Тарифный план Figma Organization или Enterprise

Использование¶

Вставьте URL компонента Figma в Claude Code и попросите создать шаблон Code Connect:

1	`Create a Code Connect template for https://www.figma.com/design/abc123/MyDS?node-id=42-100`

Альтернативно можно вызвать skill напрямую:

1	`/figma-code-connect (url: https://www.figma.com/design/abc123/MyDS?node-id=42-100)`

Claude:

Определит опубликованный компонент по этому URL
Получит определения его свойств из Figma
Найдёт соответствующий компонент в вашей кодовой базе
Подтвердит совпадение с вами перед записью
Создаст файл .figma.ts рядом с существующими файлами Code Connect

Проверка результата¶

Напоминаем: рассматривайте сгенерированный файл как отправную точку. Стоит проверить, например, что сопоставление между свойствами Figma и свойствами вашего кода имеет смысл. Подробности о формате шаблона и API см. в Написание файлов шаблонов.

Публикация¶

Когда файл вас устроит, опубликуйте его в Figma:

npx figma connect publish

Завершение¶

После полной миграции файлов Code Connect в шаблоны можно удалить оставшиеся файлы Code Connect на основе парсеров (например, файлы *.figma.tsx при использовании парсера React).

Также можно удалить из figma.config.json поля, специфичные для парсеров:

parser
importPaths (только React)
paths (только React)
imports (только React)

Справочник CLI¶

Code Connect CLI (@figma/code-connect) — интерфейс командной строки для публикации и управления подключениями Code Connect из терминала или CI/CD-пайплайнов.

Использование¶

npx figma connect [command] [options]

Команды¶

Команда	Описание
`npx figma connect publish`	Публикация файлов Code Connect в Figma
`npx figma connect unpublish`	Удаление опубликованных подключений Code Connect
`npx figma connect parse`	Разбор файлов Code Connect и вывод в формате JSON
`npx figma connect create`	Генерация шаблонного файла Code Connect
`npx figma connect migrate`	Миграция файлов Code Connect на основе парсеров в файлы шаблонов
`npx figma connect preview`	Предпросмотр отображения фрагментов Code Connect на панели Inspect в Figma

Глобальные опции¶

Опция	Описание
`-V, --version`	Вывод номера версии
`-v, --verbose`	Подробное логирование для отладки
`-t, --token <token>`	Токен доступа Figma. При отсутствии используется переменная окружения `FIGMA_ACCESS_TOKEN`.
`-h, --help`	Отображение справки по команде

figma connect publish¶

Поиск файлов Code Connect и их публикация в Figma.

Использование¶

npx figma connect publish [options]

Опции¶

Опция	Описание
`-r, --dir <dir>`	Директория с проектом Code Connect (по умолчанию — текущая рабочая директория)
`-f, --file <file>`	Путь к одному файлу Code Connect для публикации
`-c, --config <path>`	Путь к файлу конфигурации figma
`--exit-on-unreadable-files`	Завершить работу, если какие-либо файлы Code Connect не удаётся разобрать. Рекомендуется для CI/CD.
`--dry-run`	Тестовая публикация без фактической публикации
`--skip-validation`	Пропустить валидацию документов Code Connect
`-l, --label <label>`	Метка для применения к опубликованным файлам
`-b, --batch-size <batch_size>`	Размер пакета (количество документов) при загрузке
`--force`	Перезаписать существующие сопоставления Code Connect, созданные в UI, если они конфликтуют с публикуемыми файлами
`-h, --help`	Отображение справки по команде

Описание¶

Находит файлы Code Connect в указанной директории, проверяет их через API Figma и публикует. Опубликованные подключения отображаются в Dev Mode для связанных компонентов Figma.

Примеры¶

Публикация всех файлов Code Connect в текущей директории:

npx figma connect publish

Публикация из указанной директории:

npx figma connect publish --dir src/components

Публикация одного файла:

npx figma connect publish --file src/components/Button.figma.ts

Пробный запуск для просмотра того, что будет опубликовано:

npx figma connect publish --dry-run

Публикация с меткой:

npx figma connect publish --label "React"

Принудительная перезапись сопоставлений, созданных в UI:

npx figma connect publish --force

figma connect unpublish¶

Удаление опубликованных подключений Code Connect из Figma.

Использование¶

npx figma connect unpublish [options]

Опции¶

Опция	Описание
`-r, --dir <dir>`	Директория с проектом Code Connect (по умолчанию — текущая рабочая директория)
`-f, --file <file>`	Путь к одному файлу Code Connect для снятия с публикации
`-c, --config <path>`	Путь к файлу конфигурации figma
`--exit-on-unreadable-files`	Завершить работу, если какие-либо файлы Code Connect не удаётся разобрать. Рекомендуется для CI/CD.
`--dry-run`	Тестовое снятие с публикации без фактического снятия
`--node <link_to_node>`	Указать узел Figma для снятия с публикации
`-l, --label <label>`	Метка для снятия с публикации
`-h, --help`	Отображение справки по команде

Описание¶

Сканирует файлы Code Connect и удаляет их опубликованные подключения из Figma. Можно снять с публикации все подключения в директории или указать конкретную комбинацию узла и метки.

При использовании --node опция --label обязательна.

Примеры¶

Снятие с публикации всех файлов Code Connect в текущей директории:

npx figma connect unpublish

Снятие с публикации подключений из указанной директории:

npx figma connect unpublish --dir src/components

Снятие с публикации конкретного узла по URL:

npx figma connect unpublish --node "https://figma.com/file/abc123/..." --label "React"

Пробный запуск для просмотра того, что будет снято с публикации:

npx figma connect unpublish --dry-run

figma connect parse¶

Разбор файлов Code Connect и вывод в формате JSON.

Использование¶

npx figma connect parse [options]

Опции¶

Опция	Описание
`-r, --dir <dir>`	Директория с проектом Code Connect (по умолчанию — текущая рабочая директория)
`-f, --file <file>`	Путь к одному файлу Code Connect для обработки
`--outFile <file>`	Указать файл для записи JSON-вывода
`-c, --config <path>`	Путь к файлу конфигурации figma
`--exit-on-unreadable-files`	Завершить работу, если какие-либо файлы Code Connect не удаётся разобрать. Рекомендуется для CI/CD.
`--dry-run`	Тестовый разбор без формирования вывода
`-l, --label <label>`	Метка для применения к разобранным файлам
`-h, --help`	Отображение справки по команде

Описание¶

Находит файлы Code Connect в указанной директории, разбирает их в JSON-представление и выводит результат. По умолчанию JSON записывается в stdout. Используйте --outFile для записи в файл.

Полезно для отладки настройки Code Connect или интеграции с другими инструментами.

Примеры¶

Разбор всех файлов Code Connect и вывод JSON в stdout:

npx figma connect parse

Разбор с записью в файл:

npx figma connect parse --outFile output.json

Разбор одного файла:

npx figma connect parse --file src/components/Button.figma.ts

Разбор с меткой:

npx figma connect parse --label "React"

figma connect create¶

Генерация шаблонного файла Code Connect для компонента Figma, заполненного значениями свойств, готовыми к использованию в коде. Пример вывода:

// url=https://www.figma.com/file/1234abcd/My-File?node-id=123
import figma from 'figma';

/**
 * NEXT STEPS:
 * - Replace the `example` with the actual code snippet you want to show
 *   (e.g. figma.code`<Button label="${propertyValue}" />`)
 * - Update the `imports` array with any lines of code that should be displayed
 *   at the top (e.g. imports: ['import { Button } from "./Button"'])
 */

const label = figma.selectedInstance.getString('Label');
const hasIcon = figma.selectedInstance.getBoolean('Has Icon');

export default {
    example: figma.code``,
    imports: [],
    id: 'Button',
    metadata: {
        nestable: true,
    },
};

Использование¶

npx figma connect create <figma-node-url> [options]

Аргументы¶

Аргумент	Описание
`<figma-node-url>`	URL узла компонента Figma, для которого генерируется файл Code Connect

Опции¶

Опция	Описание
`--outDir <dir>`	Указать директорию для вывода сгенерированного шаблона Code Connect
`-c, --config <path>`	Путь к файлу конфигурации figma
`-h, --help`	Отображение справки по команде

Описание¶

Получает информацию о компоненте через API Figma для указанного URL узла и генерирует шаблонный файл Code Connect .figma.ts в текущей директории (или в --outDir, если указано). Сгенерированный файл включает:

Объявления аксессоров свойств для каждого свойства компонента (например, getBoolean, getString, getEnum)
Объект export default с полями-заглушками example, imports и id
Встроенные комментарии со следующими шагами для завершения шаблона

Файл именуется по компоненту (например, MyComponent.figma.ts). Если файл уже существует, команда завершается с ошибкой.

Примеры¶

Генерация файла Code Connect для компонента:

npx figma connect create "https://www.figma.com/file/1234abcd/Test-File?node-id=1-39"

Генерация в указанную директорию вывода:

npx figma connect create "https://www.figma.com/file/1234abcd/Test-File?node-id=1-39" --outDir src/components

figma connect preview¶

Предпросмотр отображения фрагментов Code Connect на панели Inspect в Figma без публикации.

Использование¶

npx figma connect preview [files...] [options]

Аргументы¶

Аргумент	Описание
`[files...]`	Файлы Code Connect для предпросмотра (например, `Button.figma.tsx`). Оставьте пустым для предпросмотра всех файлов.

Опции¶

Опция	Описание
`-r, --dir <dir>`	Директория с проектом Code Connect (по умолчанию — текущая рабочая директория)
`-c, --config <path>`	Путь к файлу конфигурации figma
`--output <format>`	Формат вывода: `table` (по умолчанию) или `json`
`-h, --help`	Отображение справки по команде

Описание¶

Разбирает указанные файлы Code Connect (или все файлы Code Connect в директории, если файлы не указаны), отображает каждый фрагмент так, как он будет выглядеть в Dev Mode, и сообщает результат. Для фрагментов на языках, поддерживаемых Prettier (например, TypeScript, JavaScript, JSX/TSX), отображаемый вывод также проверяется через Prettier для выявления синтаксических ошибок до публикации; фрагменты на других языках возвращаются как есть.

Используйте для локальной итерации над шаблоном: измените .figma.ts или файл шаблона, выполните npx figma connect preview и увидьте точно то, что покажет Figma, без публикации.

Примеры¶

Предпросмотр всех файлов Code Connect в текущей директории:

npx figma connect preview

Предпросмотр конкретного файла:

npx figma connect preview src/components/Button.figma.ts

Предпросмотр нескольких файлов:

npx figma connect preview src/components/Button.figma.ts src/components/Input.figma.ts

Вывод в формате JSON (удобно для передачи в другие инструменты):

npx figma connect preview --output json

figma connect migrate¶

Миграция существующих файлов Code Connect на основе парсеров в файлы шаблонов.

Использование¶

npx figma connect migrate [options]

Опции¶

Опция	Описание
`-r, --dir <dir>`	Директория с проектом Code Connect (по умолчанию — текущая рабочая директория)
`-f, --file <file...>`	Один или несколько файлов Code Connect для миграции. При отсутствии мигрируются все файлы проекта.
`--outDir <dir>`	Записать мигрированные файлы шаблонов в указанную директорию вместо размещения рядом с исходными файлами
`-c, --config <path>`	Путь к файлу конфигурации figma
`--javascript`	Выводить файлы `.figma.js` вместо `.figma.ts` по умолчанию
`--delete`	Удалить исходные файлы Code Connect после успешной миграции
`--batch <mode>`	Режим пакетной миграции: `auto`, `all` или `none`. По умолчанию `auto` — обрабатывает файлы с 10 и более подключениями Code Connect.
`--include-props`	Сохранить блоки метаданных `__props` в результате миграции. Передайте этот флаг, если используете модификаторы React `.getProps()` или `.render()`, либо если другие файлы шаблонов читают `executeTemplate().metadata.__props` из мигрированных компонентов.
`-h, --help`	Отображение справки по команде

Описание¶

По умолчанию команда миграции сканирует текущий проект Code Connect с учётом настроек include/exclude в figma.config.json и записывает файлы шаблонов .figma.ts.

Используйте --file для миграции одного или нескольких конкретных файлов из выбранного проекта. Для миграции папки или поддерева ограничьте include/exclude в figma.config.json.

Файлы с 10 и более подключениями Code Connect автоматически рассматриваются для вывода в batch-файлы. Если пакетная обработка небезопасна, команда возвращается к обычным файлам шаблонов. Используйте --batch all для попытки пакетной обработки каждого выбранного исходного файла или --batch none для всегда записывать обычные файлы шаблонов.

Полное пошаговое руководство по запуску миграции, проверке результата и тестированию в Figma см. в руководстве по миграции.

Примеры¶

Миграция текущего проекта Code Connect в указанное расположение:

npx figma connect migrate --outDir src/migrated

Миграция конкретных файлов:

npx figma connect migrate --file src/components/Button.figma.tsx src/components/Input.figma.tsx

Принудительная пакетная обработка конкретного файла, если возможно:

npx figma connect migrate --file src/icons.figmadoc.tsx --batch all

Подключение React-компонентов¶

Предупреждение

Парсеры для конкретных фреймворков больше не будут получать обновления и поддержку с 17 августа 2026 года. Файлы шаблонов станут единственным активно поддерживаемым способом использования Code Connect.

Подробнее о миграции Code Connect на основе парсеров к файлам шаблонов см. в руководстве по миграции: Миграция с парсеров на файлы шаблонов

Это руководство поможет вам связать React- (или React Native-) компоненты с компонентами Figma с помощью Code Connect. Code Connect для React работает как самостоятельная реализация и как интеграция с существующими файлами Storybook, что позволяет легко поддерживать обе системы параллельно.

Информация

Важно: файлы Code Connect не выполняются. Хотя они пишутся с использованием реальных компонентов из вашей кодовой базы, CLI Code Connect по сути обрабатывает фрагменты кода как строки. Это означает, например, что вы можете использовать хуки без необходимости мокать данные.

Однако это также означает, что логические операторы, такие как тернарные выражения или условия, будут выводиться в примере кода дословно, а не выполняться для отображения результата. Например, вы не можете динамически создавать вызовы figma.connect в цикле for.

Если из-за этого ограничения API вам не удаётся реализовать нужное поведение, мы будем рады получить ваш отзыв.

Динамические фрагменты кода¶

Если вы прошли Начало работы с Code Connect, у вас уже должен быть подключённый фрагмент кода, видимый в Dev Mode при инспектировании экземпляров этого компонента. Однако фрагмент кода пока не отражает весь дизайн целиком.

Чтобы подключённый фрагмент кода точно соответствовал дизайну, нужно использовать сопоставление пропсов. Это позволяет связать конкретные пропсы в дизайне с пропсами в коде. В большинстве случаев пропсы в дизайне и в коде не совпадают 1:1, поэтому необходимо настроить сопоставление, чтобы в Dev Mode отображался правильный код.

Ниже — простой пример для кнопки со свойствами label, disabled и type.

import figma from '@figma/code-connect/react';

figma.connect(Button, 'https://...', {
    props: {
        label: figma.string('Text Content'),
        disabled: figma.boolean('Disabled'),
        type: figma.enum('Type', {
            Primary: 'primary',
            Secondary: 'secondary',
        }),
    },
    example: ({ disabled, label, type }) => {
        return (
            <Button disabled={disabled} type={type}>
                {label}
            </Button>
        );
    },
});

Импорт `figma`¶

Импорт figma содержит вспомогательные функции для сопоставления различных свойств из дизайна с кодом. Они работают как для простых сопоставлений, когда в Figma и в коде отличается только именование, так и для более сложных, когда отличается тип. См. справочник ниже со всеми вспомогательными функциями Code Connect и способами их использования для связи Figma и кода.

`figma.connect`¶

У figma.connect() есть две сигнатуры для подключения компонентов.

// connect a component in code to a Figma component
figma.connect(Button, 'https://...');

// connect a Figma component to a native element
figma.connect('https://...');

Второй вариант полезен, если вы хотите отрендерить HTML-тег вместо React-компонента.

Первый аргумент используется для определения расположения компонента в коде, чтобы сгенерировать оператор импорта. Он не нужен, если вы хотите отрендерить, например, тег button. Например:

figma.connect('https://...', {
    example: () => <button>click me</button>,
});

Строки¶

Строки — самый простой тип значений для сопоставления из Figma в код. Вызовите figma.string с именем пропа Figma, на который нужно сослаться. Это удобно для подписей кнопок, заголовков, подсказок и т. п.

figma.string('Title');

Логические значения¶

Логические значения работают аналогично строкам. Однако Code Connect также предоставляет вспомогательные функции для сопоставления логических значений в Figma с более сложными типами в коде. Например, вы можете сопоставить логическое значение Figma с наличием определённого дочернего слоя в коде. Помимо сопоставления логических пропсов, figma.boolean можно использовать для сопоставления логических вариантов в Figma. Логический вариант — это вариант с двумя опциями: «Yes»/«No», «True»/«False» или «On»/«Off». Для figma.boolean эти значения нормализуются в true и false.

// simple mapping of boolean from figma to code
figma.boolean('Has Icon');

// map a boolean value to one of two options of any type
figma.boolean('Has Icon', {
    true: <Icon />,
    false: <Spacer />,
});

В некоторых случаях нужно отрендерить определённый проп только если он соответствует какому-то значению в Figma. Это можно сделать, передав частичный объект сопоставления или установив значение в undefined.

// Don't render the prop if 'Has label' in figma is `false`
figma.boolean('Has label', {
    true: figma.string('Label'),
    false: undefined,
});

Перечисления¶

Варианты (или перечисления) в Figma часто используются для управления внешним видом компонентов, которым нужны более сложные опции, чем простой логический переключатель. Свойства вариантов в Figma всегда являются строками, но их можно сопоставить с любым типом в коде. Первый параметр — имя варианта в Figma, второй — объект сопоставления значений. Ключи в этом объекте должны соответствовать различным опциям этого варианта в Figma, а значение — тому, что вы хотите вывести вместо них.

// maps the 'Options' variant in Figma to enum values in code
figma.enum('Options', {
    'Option 1': Option.first,
    'Option 2': Option.second,
});

// maps the 'Options' variant in Figma to sub-component values in code
figma.enum('Options', {
    'Option 1': <Icon />,
    'Option 2': <IconButton />,
});

// result is true for disabled variants otherwise undefined
figma.enum('Variant', { Disabled: true });

// enums mappings can be used to show a component based on a Figma variant
figma.connect(Modal, 'https://...', {
    props: {
        cancelButton: figma.enum('Type', {
            Cancellable: <CancelButton />,
        }),
        // ...
    },
    example: ({ cancelButton }) => {
        return (
            <Modal>
                <Title>Title</Title>
                <Content>Some content</Content>
                {cancelButton}
            </Modal>
        );
    },
});

Объекты сопоставления для figma.enum, а также figma.boolean, допускают вложенные ссылки, что полезно, если нужно условно отрендерить вложенный экземпляр.

// maps the 'Options' variant in Figma to enum values in code
figma.enum('Type', {
    WithIcon: figma.instance('Icon'),
    WithoutIcon: undefined,
});

В отличие от figma.boolean, значения для figma.enum не нормализуются. В объект сопоставления всегда нужно передавать точные литеральные значения.

// These two are equivalent for a variant with the options "Yes" and "No"
disabled: figma.enum("Boolean Variant", {
  Yes: // ...
  No: // ...
})
disabled: figma.boolean("Boolean Variant", {
  true: // ...
  false: // ...
})

Слоты¶

Примечание

Примечание: для использования слотов необходимо установить последнюю версию CLI Code Connect.

Слоты — это составные подобласти внутри экземпляров компонентов. В Figma слот — это дочерний фрейм компонента с произвольным редактированием содержимого. С помощью figma.slot() можно сопоставить свойство слота из Figma с вашим кодом.

// map a slot property from Figma into your code example
figma.slot('Content');

Возвращаемое значение figma.slot представляет содержимое слота и может использоваться в примере как обычный JSX-дочерний элемент — то есть его можно отрендерить в любом месте внутри компонента.

figma.connect(Card, 'https://...', {
    props: {
        title: figma.string('Title'),
        content: figma.slot('Content'),
    },
    example: ({ title, content }) => (
        <Card>
            <Title>{title}</Title>
            <Content>{content}</Content>
        </Card>
    ),
});

В Dev Mode слот отображается как кликабельная метка с именем свойства слота. Клик по метке выбирает слой слота в дизайне.

Чтобы отрендерить код для экземпляров компонентов, размещённых непосредственно в слоте, используйте свойство connectedInstances:

figma.connect(ActionBar, 'https://...', {
    props: {
        actions: figma.slot('Actions').connectedInstances,
    },
    example: ({ actions }) => <ActionBar>{actions}</ActionBar>,
});

Отображаются только экземпляры с собственными определениями Code Connect. Остальное содержимое слота — текст, слои и экземпляры, вложенные в другой экземпляр, — опускается. Используйте значение слота без connectedInstances, если слот может содержать произвольное содержимое, которое должно оставаться представленным кликабельной меткой.

Примечание

Примечание: в отличие от подмены экземпляров, слоты могут содержать любой тип дочернего содержимого (текст, слои, компоненты). По умолчанию Code Connect не обходит дочерние элементы слота для генерации кода; он отображает ссылку на сам слот.

Экземпляры¶

«Экземпляры» (instances) — термин Figma для вложенных ссылок на компоненты. Например, если Button содержит Icon как вложенный компонент, Icon называется экземпляром. В Figma экземпляры могут быть свойствами — входными параметрами компонента (аналогично render props в коде). Подобно тому как мы сопоставляем логические значения, перечисления и строки из Figma с кодом, можно сопоставлять и свойства экземпляров.

Чтобы свойства экземпляров были максимально полезны с Code Connect, рекомендуем реализовать Code Connect для всех распространённых компонентов, которые вы ожидаете использовать в качестве значений данного свойства. Dev Mode автоматически подставляет в пример подключённого фрагмента кода ссылаемого компонента код экземпляра, соответствующий свойствам.

Рассмотрим следующий пример:

// maps an instance-swap property from Figma
figma.instance('PropName');

Возвращаемое значение figma.instance — JSX-компонент, и его можно использовать в примере так же, как типичный проп JSX-компонента в вашей кодовой базе.

figma.connect(Button, 'https://...', {
    props: {
        icon: figma.instance('Icon'),
    },
    example: ({ icon }) => {
        return <Button icon={icon}>Instance prop Example</Button>;
    },
});

Затем нужен отдельный вызов figma.connect, связывающий компонент Icon с вложенным компонентом Figma. Подключайте базовый компонент этого экземпляра, а не сам экземпляр.

figma.connect(Icon32Add, 'https://...');

Дочерние экземпляры¶

Часто у компонентов в Figma есть дочерние экземпляры, не привязанные к свойству подмены экземпляра. Аналогично figma.instance, фрагменты кода для таких вложенных экземпляров можно отрендерить с помощью figma.children. Эта вспомогательная функция принимает имя слоя экземпляра внутри родительского компонента, а не имя пропа Figma.

Для иллюстрации рассмотрим иерархию слоёв в компоненте и в экземпляре этого компонента:

Button(Component);
Icon(Instance);

В предыдущем примере «Icon» — исходное имя слоя и значение, которое нужно передать в figma.children().

Button(Instance);
RenamedIcon(Instance);

В предыдущем примере слой экземпляра был переименован. Переименование слоя не нарушит сопоставление, поскольку в этом случае мы не используем имя слоя.

Примечание

Примечание: вложенный экземпляр также должен быть подключён отдельно.

Имена слоёв могут различаться между вариантами в наборе компонентов. Чтобы компонент (Button) мог отрендерить вложенный экземпляр (Icon) для любого из этих вариантов, используйте подстановочный вариант figma.children("*") или убедитесь, что имя слоя, представляющего экземпляр (Icon), одинаково во всех вариантах набора компонентов (Button).

// map one child instance with the layer name "Tab"
figma.children('Tab');

// map multiple child instances by their layer names to a single prop
figma.children(['Tab 1', 'Tab 2']);

Подстановочное совпадение¶

figma.children() можно использовать с одним символом подстановки *, чтобы частично совпадать по именам или отрендерить любой вложенный дочерний элемент. Подстановочные символы нельзя использовать с аргументом-массивом. Совпадения чувствительны к регистру.

// map any (all) child instances
figma.children('*');

// map any child instances that starts with "Icon"
figma.children('Icon*');

Вложенные свойства¶

Если не нужно подключать дочерний компонент, а вместо этого сопоставить его свойства на уровне родителя, используйте figma.nestedProps(). Эта вспомогательная функция принимает имя слоя в качестве первого параметра и объект сопоставления — в качестве второго. Эти пропсы затем можно ссылаться в функции example. nestedProps всегда выбирает один экземпляр и не может сопоставлять несколько дочерних элементов.

// map the properties of a nested instance named "Button Shape"
figma.connect(Button, "https://...", {
  props: {
    buttonShape: figma.nestedProps('Button Shape', {
      size: figma.enum({ ... }),
    })
  },
  example: ({ buttonShape }) => <Button size={buttonShape.size} />
}

Распространённый паттерн — использовать nestedProps для доступа к условно скрытому слою. Это достигается сочетанием nestedProps с boolean и передачей резервного объекта в случае false.

figma.connect(Button, "https://...", {
  props: {
    childProps: figma.boolean("showChild", {
      true: figma.nestedProps('Child', {
        label: figma.string("Label")
      },
      false: { label: undefined }
    })
  },
  example: ({ childProps }) => <Button label={childProps.label} />
}

Содержимое текста¶

Распространённый паттерн для дизайн-систем в Figma — не использовать пропсы для текста, а полагаться на переопределение текстового содержимого в экземплярах. figma.textContent() позволяет выбрать дочерний текстовый слой и отрендерить его содержимое. Принимает один параметр — имя слоя в исходном компоненте.

figma.connect(Button, "https://...", {
  props: {
    label: figma.textContent("Text Layer")
  },
  example: ({ label }) => <Button>{label}</Button>
}

className¶

Для сопоставления свойств Figma со строкой className используйте вспомогательную функцию figma.className. Она принимает массив строк и возвращает объединённую строку. Вместе с ней можно использовать любую другую вспомогательную функцию, возвращающую строку (или undefined). Значения undefined и пустые строки отфильтровываются из результата.

figma.connect("https://...", {
  props: {
    className: figma.className([
      'btn-base',
      figma.enum("Size", { Large: 'btn-large' }),
      figma.boolean("Disabled", { true: 'btn-disabled', false: '' }),
    ])
  },
  example: ({ className }) => <Button className={className} />
}

В Dev Mode этот фрагмент отображается так:

<Button className="btn-base btn-large btn-disabled" />

Ограничения вариантов¶

Иногда один компонент в Figma представлен несколькими компонентами в коде. Например, в дизайн-системе Figma может быть одна Button со свойством type для переключения между вариантами primary, secondary и danger. В коде это может быть представлено тремя разными компонентами: PrimaryButton, SecondaryButton и DangerButton.

Для моделирования такого поведения в Code Connect используйте ограничения вариантов. Они позволяют предоставлять совершенно разные примеры кода для вариантов одного компонента Figma. Ключи и значения должны соответственно соответствовать имени варианта (или свойства) в Figma и его опциям.

figma.connect(PrimaryButton, 'https://...', {
    variant: { Type: 'Primary' },
    example: () => <PrimaryButton />,
});

figma.connect(SecondaryButton, 'https://...', {
    variant: { Type: 'Secondary' },
    example: () => <SecondaryButton />,
});

figma.connect(DangerButton, 'https://...', {
    variant: { Type: 'Danger' },
    example: () => <DangerButton />,
});

Это также работает для свойств Figma, которые не являются вариантами, например логических пропсов.

figma.connect(IconButton, 'https://...', {
    variant: { 'Has Icon': true },
    example: () => <IconButton />,
});

В некоторых случаях может понадобиться сопоставить компонент в коде с комбинацией вариантов в Figma.

figma.connect(DangerButton, 'https://...', {
    variant: { Type: 'Danger', Disabled: true },
    example: () => <DangerButton />,
});

Подключение иконок¶

Иконки можно настраивать по-разному в Figma и в коде. Рекомендуем использовать свойства подмены экземпляра (instance-swap) в Figma для иконок, чтобы получать доступ к вложенной иконке Code Connect через стабильный ID свойства подмены экземпляра.

Информация

Важно: в дизайн-системах обычно много иконок. Генерацию документов Code Connect можно автоматизировать скриптом, который добавляет их в новый файл, например icons.figma.tsx. Мы предоставляем пример скрипта как отправную точку.

Иконки как JSX-элементы¶

Если иконки передаются в коде как JSX-элементы, Code Connect используется так же, как при создании компонентов.

// icon
figma.connect("my-icon-url", {
  example: () => <IconHeart />
})

// parent
figma.connect("my-button-url, {
  props: {
    icon: figma.instance("InstanceSwapPropName")
  },
  example: ({ icon }) => <Button>{icon}</Button>
})

// renders in Dev Mode
<Button><IconHeart/></Button>

Иконки как React-компоненты¶

Если иконки передаются как React-компоненты, в файле Code Connect иконки можно вернуть React-компонент вместо JSX-элемента.

// icon
figma.connect("my-icon-url", {
  example: () => IconHeart
})

// parent
figma.connect("my-button-url, {
  props: {
    Icon: figma.instance<React.FunctionComponent>("InstanceSwapPropName")
  },
  example: ({ Icon }) => <Button Icon={Icon} />
})

// renders in Dev Mode
<Button Icon={IconHeart} />

Иконки как строки¶

Часто вместо передачи компонентов для иконок используют ID. В этом случае файлы Code Connect для иконок должны просто возвращать эту строку. У figma.instance есть параметр type, который используется для сопоставления с тем, что возвращает вложенный шаблон.

// icon
figma.connect("my-icon-url", {
  example: () => "icon-heart"
})

// parent
figma.connect("my-button-url, {
  props: {
    iconId: figma.instance<string>("InstanceSwapPropName")
  },
  example: ({ iconId }) => <Button iconId={iconId} />
})

// renders in Dev Mode
<Button iconId="icon-heart" />

Доступ к пропсам иконки в родительском компоненте¶

Если иконки рендерятся по-разному в зависимости от родителя, или если вы используете строки для иконок, но всё же хотите сопоставлять свойства компонентов иконок, используйте getProps или render, доступные в возвращаемом значении figma.instance(). Функция example самой иконки определяет, как иконка отображается при клике в Figma, но это можно «переопределить» через эти дополнительные вспомогательные функции.

getProps даёт доступ к пропсам дочернего элемента (например, иконки) из родителя, чтобы использовать их в родительском компоненте. Обратите внимание на статический проп iconId: "my-icon" — любые пользовательские/статические пропсы, подобные этому, будут включены в объект, возвращаемый из getProps.

// icon
figma.connect("my-icon-url", {
  props: {
    iconId: "my-icon",
    size: figma.enum("Size", {
      'large': 'large',
      'small': 'small'
    })
  }
  example: ({ size }) => <MyIcon size={size}/>
})

// parent
figma.connect("icon-button-url", {
  props: {
    iconProps: figma.instance("InstanceSwapPropName").getProps<{iconId: string, size: "small" | "large"}>()
  },
  example: ({ iconProps }) => <IconButton iconId={iconProps.iconId} iconSize={iconProps.size} />
})

// renders in Dev Mode
<IconButton iconId="my-icon" size="small" />

render позволяет условно отрендерить вложенные подключённые компоненты. В аргумент передаются разрешённые пропсы вложенного компонента. Это полезно, если нужно динамически отрендерить разные JSX-элементы на основе логического пропа, например.

// icon
figma.connect("my-icon-url", {
  props: {
    iconId: "my-icon",
    size: figma.enum("Size", {
      'large': 'large',
      'small': 'small'
    })
  }
  example: ({ size }) => <MyIcon size={size}/>
})

// parent
figma.connect("icon-button-url", {
  props: {
    icon: figma.boolean("Show icon", {
      true: figma.instance("InstanceSwapPropName").render<{iconId: string, size: "small" | "large"}>(props => <ButtonIcon id={props.iconId} size={props.size}/>),
    }
  },
  example: ({ icon }) => <Button icon={icon}/>
})

// renders in Dev Mode
<Button icon={<ButtonIcon id="my-icon" size="small" />} />

Подключение Web-компонентов¶

Предупреждение

Парсеры для конкретных фреймворков больше не будут получать обновления и поддержку с 17 августа 2026 года. Файлы шаблонов станут единственным активно поддерживаемым способом использования Code Connect.

См. руководство по миграции для получения дополнительной информации и инструкций по переходу с Code Connect на основе парсеров: Миграция с парсеров на файлы шаблонов

Это руководство поможет вам подключить HTML-компоненты к компонентам Figma с помощью Code Connect. Это позволяет документировать Web Components, Angular, Vue и любые другие фреймворки, использующие синтаксис HTML. См. раздел примеры для примеров использования Code Connect с различными HTML-фреймворками.

Информация

Важно: файлы Code Connect не выполняются. Хотя они пишутся с использованием реальных компонентов из вашей кодовой базы, CLI Code Connect по сути обрабатывает фрагменты кода как строки. Это означает, что, например, вы можете использовать хуки без необходимости мокировать данные.

Однако это также означает, что логические операторы, такие как тернарные операторы или условия, будут выводиться в примере кода дословно, а не выполняться для отображения результата. Вы не можете динамически создавать вызовы figma.connect в цикле for, например.

Если из-за этого ограничения API вы не можете реализовать то, что вам нужно, мы будем рады получить ваш отзыв.

Динамические фрагменты кода¶

Если вы прошли Начало работы с Code Connect, у вас должен быть подключённый фрагмент кода, видимый в Dev Mode при инспектировании экземпляров этого компонента. Однако фрагмент кода ещё не отражает весь дизайн полностью.

Чтобы подключённый фрагмент кода точно соответствовал дизайну, необходимо использовать сопоставление пропсов. Это позволяет связать конкретные пропсы в дизайне с пропсами в коде. В большинстве случаев пропсы в дизайне и коде не совпадают 1:1, поэтому необходимо настроить сопоставление, чтобы в Dev Mode отображался правильный код.

Вот простой пример для кнопки со свойствами label, disabled и type.

import figma, { html } from '@figma/code-connect/html';

figma.connect('https://...', {
    props: {
        label: figma.string('Text Content'),
        disabled: figma.boolean('Disabled'),
        type: figma.enum('Type', {
            Primary: 'primary',
            Secondary: 'secondary',
        }),
    },
    example: ({ disabled, label, type }) =>
        html`<ds-button disabled=${disabled} type=${type}>
            ${label}
        </ds-button>`,
});

Свойства Figma можно вставлять в пример Code Connect с помощью интерполяции шаблонных строк, например ${disabled}. Для HTML-атрибутов Code Connect использует тип свойства Figma для корректного рендеринга, поэтому disabled=${disabled} отобразит либо disabled, либо ничего, так как это булево значение; тогда как type=${type} отобразит type="primary", так как это строка.

Импорт `figma`¶

Импорт figma содержит вспомогательные функции для сопоставления различных свойств из дизайна в код. Они работают как для простых сопоставлений, где различается только именование между Figma и кодом, так и для более сложных сопоставлений, где различается тип. См. справочник ниже для всех доступных вспомогательных функций и способов их использования для подключения компонентов Figma и кода с помощью Code Connect.

Строки¶

Строки — самый простой тип значений для сопоставления из Figma в код. Достаточно вызвать figma.string с именем пропса Figma, на который нужно ссылаться, в качестве параметра. Это полезно для таких элементов, как метки кнопок, заголовки, всплывающие подсказки.

figma.string('Title');

Булевы значения¶

Булевы значения работают аналогично строкам. Однако Code Connect также предоставляет вспомогательные функции для сопоставления булевых значений в Figma с более сложными типами в коде. Например, вы можете сопоставить булево значение Figma с наличием определённого вложенного слоя в коде. Помимо сопоставления булевых пропсов, figma.boolean можно использовать для сопоставления булевых вариантов в Figma. Булевый вариант — это вариант с двумя опциями: «Yes»/«No», «True»/«False» или «On»/«Off». Для figma.boolean эти значения нормализуются в true и false.

// simple mapping of boolean from figma to code
figma.boolean('Has Icon');

// map a boolean value to one of two options of any type
figma.boolean('Has Icon', {
    true: html`<ds-icon></ds-icon>`,
    false: html`<ds-spacer></ds-spacer>`,
});

В некоторых случаях нужно отображать определённый проп только если он соответствует какому-то значению в Figma. Это можно сделать либо передав частичный объект сопоставления, либо установив значение в undefined.

// Don't render the prop if 'Has label' in figma is `false`
figma.boolean('Has label', {
    true: figma.string('Label'),
    false: undefined,
});

Перечисления¶

Варианты (или перечисления) в Figma обычно используются для управления внешним видом компонентов, которым нужны более сложные опции, чем простой булевый переключатель. Свойства вариантов в Figma всегда являются строками, но их можно сопоставить с любым типом в коде. Первый параметр — имя варианта в Figma, второй — объект сопоставления значений. Ключи в этом объекте должны соответствовать различным опциям этого варианта в Figma, а значение — тому, что вы хотите вывести вместо них.

// maps the 'Options' variant in Figma to enum values in code
figma.enum('Options', {
  'Option 1': Option.first,
  'Option 2': Option.second,
})

// maps the 'Options' variant in Figma to sub-component values in code
figma.enum('Options', {
  'Option 1': html`<ds-icon></ds-icon>`,
  'Option 2': html`<ds-icon-button></ds-icon-button>`,
})

// result is true for disabled variants otherwise undefined
figma.enum('Variant', { Disabled: true })

// enums mappings can be used to show a component based on a Figma variant
figma.connect('https://...', {
  props: {
    cancelButton: figma.enum('Type', {
      Cancellable: html`<ds-cancel-button></ds-cancel-button>`
    }),
    // ...
  },
  example: ({ cancelButton }) => html`\
<ds-modal>
  <ds-modal-title>Title</ds-modal-title>
  <ds-modal-content>Some content</ds-modal-content>
  ${cancelButton}
</ds-modal>`
  },
})

Объекты сопоставления для figma.enum, а также figma.boolean, допускают вложенные ссылки, что полезно, если нужно условно отобразить вложенный экземпляр, например.

// maps the 'Options' variant in Figma to enum values in code
figma.enum('Type', {
    WithIcon: figma.instance('Icon'),
    WithoutIcon: undefined,
});

В отличие от figma.boolean, значения не нормализуются для figma.enum. Всегда нужно передавать в объект сопоставления точные литеральные значения.

// These two are equivalent for a variant with the options "Yes" and "No"
disabled: figma.enum("Boolean Variant", {
  Yes: // ...
  No: // ...
})
disabled: figma.boolean("Boolean Variant", {
  true: // ...
  false: // ...
})

Слоты¶

Примечание

Примечание: для использования слотов необходимо установить последнюю версию CLI Code Connect.

Слоты — это компонуемые подобласти внутри экземпляров компонентов. В Figma слот — это дочерний фрейм компонента с возможностью свободного редактирования содержимого. Вы можете использовать figma.slot() для сопоставления свойства слота из Figma с вашим кодом.

// map a slot property from Figma into your code example
figma.slot('Content');

Возвращаемое значение figma.slot представляет содержимое слота и может использоваться в примере как дочерний элемент, то есть его можно отобразить в любом месте внутри компонента.

figma.connect('https://...', {
    props: {
        title: figma.string('Title'),
        content: figma.slot('Content'),
    },
    example: ({ title, content }) =>
        html`<ds-modal>
            <ds-modal-title>${title}</ds-modal-title>
            <ds-modal-content>${content}</ds-modal-content>
        </ds-modal>`,
});

В Dev Mode слот отображается как кликабельная метка с именем свойства слота. При клике на метку выбирается слой слота в дизайне.

Чтобы отобразить код для экземпляров компонентов, размещённых непосредственно в слоте, используйте свойство connectedInstances:

figma.connect('https://...', {
    props: {
        actions: figma.slot('Actions').connectedInstances,
    },
    example: ({ actions }) => html`<ds-action-bar>${actions}</ds-action-bar>`,
});

Отображаются только экземпляры с собственными определениями Code Connect. Остальное содержимое слота, включая текст, слои и экземпляры, вложенные в другой экземпляр, опускается. Используйте значение слота без connectedInstances, когда слот может содержать произвольное содержимое, которое должно оставаться представленным кликабельной меткой.

Примечание

Примечание: в отличие от замены экземпляров, слоты могут содержать любой тип дочернего содержимого (текст, слои, компоненты). По умолчанию Code Connect не обходит дочерние элементы слота для генерации кода; он отображает ссылку на сам слот.

Экземпляры¶

«Экземпляры» (Instances) — термин Figma для вложенных ссылок на компоненты. Например, в случае Button, содержащего Icon как вложенный компонент, Icon называется экземпляром. В Figma экземпляры могут быть свойствами, то есть входными параметрами компонента (аналогично render props в коде). Подобно тому, как мы сопоставляем булевы значения, перечисления и строки из Figma в код, мы также можем сопоставлять их со свойствами экземпляров.

Чтобы свойства экземпляров были максимально полезны с Code Connect, мы рекомендуем реализовать Code Connect для всех распространённых компонентов, которые вы ожидаете использовать в качестве значений для данного свойства. Dev Mode автоматически заполняет пример подключённого фрагмента кода ссылаемого компонента кодом экземпляра, соответствующим свойствам.

Рассмотрим следующий пример:

// maps an instance-swap property from Figma
figma.instance('PropName');

Возвращаемое значение figma.instance — это шаблонный литерал с тегом html, который можно использовать в примере как дочерний элемент.

figma.connect('https://...', {
    props: {
        icon: figma.instance('Icon'),
    },
    example: ({ icon }) =>
        html`<ds-button
            ><div slot="icon">${icon}</div>
            Instance prop Example</ds-button
        >`,
});

Затем у вас должен быть отдельный вызов figma.connect, который подключает компонент Icon к вложенному компоненту Figma. Убедитесь, что вы подключаете базовый компонент этого экземпляра, а не сам экземпляр.

figma.connect('https://...', {
    example: () => html`<ds-icon icon="add"></ds-icon>`,
});

Дочерние экземпляры¶

Часто у компонентов в Figma есть дочерние экземпляры, не привязанные к свойству замены экземпляра. Аналогично figma.instance, мы можем отобразить фрагменты кода для этих вложенных экземпляров с помощью figma.children. Эта вспомогательная функция принимает имя слоя экземпляра внутри родительского компонента в качестве параметра, а не имя пропса Figma.

Для иллюстрации рассмотрим иерархию слоёв в компоненте и экземпляре этого компонента:

Button(Component);
Icon(Instance);

В предыдущем примере «Icon» — исходное имя слоя и значение, которое нужно передать в figma.children().

Button(Instance);
RenamedIcon(Instance);

В предыдущем примере слой экземпляра был переименован. Переименование слоя не нарушит сопоставление, поскольку в данном случае мы не используем имя слоя.

Примечание

Примечание: вложенный экземпляр также должен быть подключён отдельно.

Имена слоёв могут различаться между вариантами в наборе компонентов. Чтобы компонент (Button) мог отображать вложенный экземпляр (Icon) для любого из этих вариантов, необходимо либо использовать опцию с подстановочным символом figma.children("*"), либо убедиться, что имя слоя, представляющего экземпляр (Icon), одинаково во всех вариантах набора компонентов (Button).

// map one child instance with the layer name "Tab"
figma.children('Tab');

// map multiple child instances by their layer names to a single prop
figma.children(['Tab 1', 'Tab 2']);

Сопоставление с подстановочным символом¶

figma.children() можно использовать с одним символом подстановки «*» для частичного сопоставления имён или для отображения любого вложенного дочернего элемента. Подстановочные символы нельзя использовать с аргументом-массивом. Сопоставления чувствительны к регистру.

// map any (all) child instances
figma.children('*');

// map any child instances that starts with "Icon"
figma.children('Icon*');

Вложенные свойства¶

Когда вы не хотите подключать дочерний компонент, а вместо этого хотите сопоставить его свойства на уровне родителя, можно использовать figma.nestedProps(). Эта вспомогательная функция принимает имя слоя в качестве первого параметра и объект сопоставления в качестве второго. Эти пропсы затем можно ссылать в функции example. nestedProps всегда выбирает один экземпляр и не может использоваться для сопоставления нескольких дочерних элементов.

// map the properties of a nested instance named "Button Shape"
figma.connect("https://...", {
  props: {
    buttonShape: figma.nestedProps('Button Shape', {
      size: figma.enum({ ... }),
    })
  },
  example: ({ buttonShape }) => html`<ds-button size=${buttonShape.size}></ds-button>`
}

Текстовое содержимое¶

Распространённый паттерн для дизайн-систем в Figma — не использовать пропсы для текстов, а полагаться на переопределение текстового содержимого экземплярами. figma.textContent() позволяет выбрать дочерний текстовый слой и отобразить его содержимое. Принимает один параметр — имя слоя в исходном компоненте.

figma.connect("https://...", {
  props: {
    label: figma.textContent("Text Layer")
  },
  example: ({ label }) => html`<ds-button>${label}</ds-button>`
}

className¶

Для сопоставления свойств Figma со строкой className можно использовать вспомогательную функцию figma.className. Она принимает массив строк и возвращает объединённую строку. Любая другая вспомогательная функция, возвращающая строку (или undefined), может использоваться вместе с ней. Значения undefined или пустые строки отфильтровываются из результата.

figma.connect("https://...", {
  props: {
    className: figma.className([
      'btn-base',
      figma.enum("Size", { Large: 'btn-large' }),
      figma.boolean("Disabled", { true: 'btn-disabled', false: '' }),
    ])
  },
  example: ({ className }) => html`<button class=${className}></button>`
}

В Dev Mode этот фрагмент отображается как:

<button class="btn-base btn-large btn-disabled"></button>

Ограничения вариантов¶

Иногда один компонент в Figma представлен несколькими компонентами в коде. Например, у вас может быть один Button в дизайн-системе Figma со свойством type для переключения между вариантами primary, secondary и danger. Однако в коде это может быть представлено тремя разными компонентами: <ds-button-primary>, <ds-button-secondary> и <ds-button-danger>.

Чтобы смоделировать такое поведение с Code Connect, используйте ограничения вариантов. Ограничения вариантов позволяют предоставлять совершенно разные примеры кода для разных вариантов одного компонента Figma. Используемые ключи и значения должны соответствовать имени варианта (или свойства) в Figma и его опциям соответственно.

figma.connect('https://...', {
    variant: { Type: 'Primary' },
    example: () => html`<ds-button-primary></ds-button-primary>`,
});

figma.connect('https://...', {
    variant: { Type: 'Secondary' },
    example: () => html`<ds-button-secondary></ds-button-secondary>`,
});

figma.connect('https://...', {
    variant: { Type: 'Danger' },
    example: () => html`<ds-button-danger></ds-button-danger>`,
});

Это также работает для свойств Figma, которые не являются вариантами, например булевых пропсов.

figma.connect('https://...', {
    variant: { 'Has Icon': true },
    example: () => html`<ds-icon-button></ds-icon-button>`,
});

В некоторых случаях может потребоваться сопоставить компонент кода с комбинацией вариантов в Figma.

figma.connect('https://...', {
    variant: { Type: 'Danger', Disabled: true },
    example: () => html`<ds-button-danger></ds-button-danger>`,
});

Примеры¶

Code Connect HTML поддерживает любую допустимую HTML-разметку, поэтому помимо документирования простого HTML и Web Components, его можно использовать для документирования HTML-фреймворков, таких как Angular и Vue. Любой сопутствующий JavaScript/TypeScript код должен быть заключён в тег <script>.

Проекты Angular и Vue определяются автоматически по их наличию в package.json, и метка по умолчанию для ваших примеров устанавливается соответствующим образом (см. документацию по label для получения дополнительной информации).

Пример Web Components¶

import figma, { html } from '@figma/code-connect/html';

figma.connect('https://...', {
    props: {
        text: figma.string('Text'),
        disabled: figma.boolean('Disabled'),
        size: figma.enum('Size', {
            small: 'sm',
            large: 'lg',
        }),
    },
    example: (props) =>
        html`<ds-button disabled=${props.disabled} size=${props.size}>
                ${props.text}
            </ds-button>

            <script>
                document
                    .querySelector('ds-button')
                    .addEventListener('click', () => {
                        alert('You clicked ${props.text}');
                    });
            </script>`,
    imports: [
        '<script type="module" src="https://my.domain/js/ds-button.min.js">',
    ],
});

Пример Angular¶

import figma, { html } from '@figma/code-connect/html';

figma.connect('https://...', {
    props: {
        text: figma.string('Text'),
        disabled: figma.boolean('Disabled'),
        size: figma.enum('Size', {
            small: 'sm',
            large: 'lg',
        }),
    },
    example: (props) =>
        html`<button
                dsButton
                disabled=${props.disabled}
                size=${props.size}
                (onClick)="onClick($event)"
            >
                ${props.text}
            </button>

            <script>
                export class Example {
                  public onClick() {
                    alert("You clicked ${props.text}");
                  }
                }
            </script>`,
    imports: ["import { DsButton } from '@ds-angular/button'"],
});

Пример Vue¶

import figma, { html } from '@figma/code-connect/html';

figma.connect('https://...', {
    props: {
        text: figma.string('Text'),
        disabled: figma.boolean('Disabled'),
        size: figma.enum('Size', {
            small: 'sm',
            large: 'lg',
        }),
    },
    example: (props) =>
        html`<script setup>
                function onClick() {
                    alert('You clicked ${props.text}');
                }
            </script>

            <ds-button
                disabled=${props.disabled}
                size=${props.size}
                @click="onClick"
            >
                ${props.text}
            </ds-button>`,
    imports: ["import { DsButton } from '@ds-vue/button'"],
});

Пример Lit¶

Поскольку пример кода записывается в шаблонной строке, необходимо экранировать любые символы $, которые вы хотите отобразить дословно в примере, иначе они будут интерпретированы как заполнители.

import figma, { html } from '@figma/code-connect/html';

figma.connect('https://...', {
    props: {
        text: figma.string('Text'),
        disabled: figma.boolean('Disabled'),
    },
    example: (props) =>
        html`<ds-button
            disabled=${props.disabled}
            size=${props.size}
            ?litSyntaxExample="\${booleanVar}"
        >
            ${props.text}
        </ds-button>`,
    imports: ["import '@ds-lit/button'"],
});

Подключение иконок¶

Иконки можно настраивать множеством различных способов в Figma и коде. Мы рекомендуем использовать свойства замены экземпляра (instance-swap props) в Figma для иконок, чтобы иметь доступ к вложенной иконке Code Connect через стабильный ID свойства замены экземпляра.

Информация

Важно: в дизайн-системах обычно много иконок. Можно автоматизировать генерацию документов Code Connect с помощью скрипта, который добавляет их в новый файл. Например, файл icons.figma.ts. Мы предоставляем пример скрипта в качестве отправной точки.

Иконки как строки¶

Часто вместо передачи компонентов для иконок используются ID. В этом случае файлы Code Connect для иконок должны просто возвращать эту строку. figma.instance принимает параметр type, который используется для сопоставления с тем, что возвращает вложенный шаблон. Затем можно иметь универсальный компонент иконки, который потребляет ID иконки внутреннего экземпляра.

// Icon ID
figma.connect("my-icon-url", {
  example: () => "icon-heart"
})

// Icon component
figma.connect("my-icon-component-url, {
  props: {
    iconId: figma.instance<string>("InstanceSwapPropName")
  },
  example: ({ iconId }) => html`<ds-icon iconId=${iconId} />`
})

// renders in Dev Mode
<ds-icon iconId="icon-heart" />

Или, как в другом распространённом сценарии, потреблять ID напрямую в других компонентах дизайн-системы, например в кнопке.

// Icon ID
figma.connect("my-icon-url", {
  example: () => "icon-heart"
})

// Button component
figma.connect("my-button-url, {
  props: {
    iconId: figma.instance<string>("InstanceSwapPropName")
  },
  example: ({ iconId }) => html`<ds-button iconId=${iconId} />`
})

// renders in Dev Mode
<ds-icon iconId="icon-heart" />

Интеграция со Storybook¶

Предупреждение

Парсеры, специфичные для фреймворков, больше не будут получать обновления и поддержку с 17 августа 2026 года. Файлы шаблонов останутся единственным активно поддерживаемым способом использования Code Connect.

Подробнее о миграции Code Connect на основе парсеров см. в руководстве по миграции: Миграция с парсеров на файлы шаблонов

Информация

Важно: интеграция со Storybook доступна только для компонентов на React.

Используйте интеграцию Storybook с Code Connect, чтобы удобно поддерживать оба инструмента параллельно. Синтаксис этой интеграции немного отличается от варианта для React, чтобы соответствовать API Storybook.

Чтобы определить документацию Code Connect через Storybook, добавьте в объект конфигурации истории блок parameters, ссылающийся на компонент Figma.

export default {
    component: Button,
    parameters: {
        design: {
            type: 'figma',
            url: 'https://...',
            examples: [ButtonExample],
        },
    },
};

// Existing story
export function ButtonExample() {
    return <Button disabled />;
}

Этот синтаксис расширяет существующую интеграцию Storybook, предлагаемую Figma, поэтому вы автоматически получите все её преимущества, в том числе превью компонента Figma, встроенное в документацию Storybook.

Динамические фрагменты кода¶

При базовой настройке, описанной выше, при проверке экземпляров компонента в Dev Mode должен отображаться подключённый фрагмент кода. Однако фрагмент кода пока не отражает весь дизайн целиком.

Ниже простой пример для кнопки со свойствами label, disabled и type.

import figma from "@figma/code-connect"

export default {
  component: Button,
  parameters: {
    design: {
      type: 'figma',
      url: 'https://...',
      examples: [ButtonExample],
      props: {
        label: figma.string('Text Content'),
        disabled: figma.boolean('Disabled'),
        type: figma.enum('Type', {
          Primary: ButtonType.Primary,
          Secondary: ButtonType.Secondary
        },
      },
    },
    argTypes: {
      label: { control: 'string' },
      disabled: { control: 'boolean' },
      type: {
        control: {
          type: 'select',
          options: [ButtonType.Primary, ButtonType.Secondary]
        }
      }
    },
    args: {
      label: 'Hello world',
      disabled: false,
      type: ButtonType.Primary
    }
  }
}

export function ButtonExample({ label, disabled, type }) {
  return <Button disabled={disabled} type={type}>{ label }</Button>
}

Также можно использовать разные примеры с разными именами свойств, указав их в массиве examples.

export default {
    component: Button,
    parameters: {
        design: {
            type: 'figma',
            url: 'https://...',
            examples: [
                { example: Button1 },
                {
                    example: Button2,
                    props: { text: figma.string('Text Content') }, // overrides the default props (`props: { label... }`)
                },
            ],
            props: {
                label: figma.string('Text Content'),
            },
        },
    },
};

export function Button1({ label }) {
    return <Button>{label}</Button>;
}

export function Button2({ text }) {
    return <Button>{text}</Button>;
}

Поле imports позволяет указать операторы импорта, необходимые для использования компонента.

export default {
    component: Button,
    parameters: {
        design: {
            type: 'figma',
            url: 'https://...',
            imports: ['import { Button } from "./Button"'],
            examples: [ButtonExample],
        },
    },
};

export function ButtonExample() {
    return <Button />;
}

Ограничения вариантов¶

Иногда один компонент в Figma представлен в коде несколькими компонентами. Например, в дизайн-системе Figma может быть одна кнопка Button со свойством type для переключения между вариантами primary, secondary и danger. В коде это может быть три разных компонента: PrimaryButton, SecondaryButton и DangerButton.

Чтобы смоделировать такое поведение в Code Connect, используйте ограничения вариантов (variant restrictions). Они позволяют предоставлять полностью разные образцы кода для вариантов одного компонента Figma. Ключи и значения должны соответствовать имени варианта (или свойства) в Figma и его опциям соответственно.

export default {
    component: Button,
    parameters: {
        design: {
            type: 'figma',
            url: 'https://...',
            examples: [
                { example: PrimaryButtonStory, variant: { Type: 'Primary' } },
                {
                    example: SecondaryButtonStory,
                    variant: { Type: 'Secondary' },
                },
                { example: DangerButtonStory, variant: { Type: 'Danger' } },
            ],
        },
    },
};

export function PrimaryButtonStory() {
    return <PrimaryButton />;
}

export function SecondaryButtonStory() {
    return <SecondaryButton />;
}

export function DangerButtonStory() {
    return <DangerButton />;
}

Непрерывная интеграция (CI)¶

Проще всего начать работу с Code Connect через локальный CLI. Однако после настройки первых подключённых компонентов можно интегрировать Code Connect в среду CI/CD, чтобы упростить сопровождение и гарантировать актуальность связей компонентов. С помощью GitHub Actions можно указать, что новые файлы нужно опубликовать при слиянии любого PR в ветку main. Рекомендуем запускать это только для pull request'ов, связанных с Code Connect, чтобы минимизировать влияние на остальные PR.

on:
    push:
        paths:
            - src/components/**/*.figma.tsx
        branches:
            - main

jobs:
    code-connect:
        name: Code Connect
        runs-on: ubuntu-latest
        steps:
            - run: npx figma connect publish --exit-on-unreadable-files
              env:
                  FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}

Аутентификация в CI¶

CLI аутентифицируется с помощью токена, переданного через флаг --token или переменную окружения FIGMA_ACCESS_TOKEN. Храните токен как секрет в провайдере CI, а не коммитьте его в репозиторий.

Для CI мы рекомендуем Plan Access Token (PLANT) вместо Personal Access Token (PAT):

PLANT принадлежат плану (Org+) и управляются администраторами, поэтому продолжают работать, когда человек, создавший их, покидает команду.
Для PLANT можно задать срок действия до одного года и обновить их до истечения, что снижает частоту ротации по сравнению с максимумом в 90 дней у PAT.
PLANT для Figma CLI используют фиксированный набор областей Figma CLI вместо наследования прав пользователя, ограничивая учётные данные поддерживаемыми рабочими процессами CLI и ресурсами в рамках плана.

Администратор может создать токен на вкладке Figma CLI в developer hub. Токен используется так же, как PAT: передайте его через FIGMA_ACCESS_TOKEN (или --token); других изменений в пайплайне не требуется. Подробности см. в документации Plan Access Tokens.

Пользовательские парсеры¶

Информация

Важно: поддержка пользовательских парсеров для Code Connect находится в режиме предварительного просмотра, и API в этот период может измениться. Поделитесь обратной связью, создав GitHub issue.

Обзор¶

Пользовательские парсеры позволяют добавить поддержку языков, для которых Code Connect не поддерживается нативно.

Команды¶

Общие сведения о доступных командах CLI см. в документации. При использовании пользовательского парсера команды CLI взаимодействуют с указанной командой парсера, чтобы запросить соответствующие документы Code Connect (для publish и parse) или создать файлы Code Connect (для create).

Команды Publish и Parse¶

При использовании пользовательского парсера команды publish и parse обрабатывают все файлы, указанные в поле includes, и исключают файлы из поля excludes в figma.config.json. Затем выполняется parserCommand из конфигурации с передачей объекта типа ParseRequestPayload через stdin. parserCommand разбирает файлы и генерирует документы Code Connect, включая код шаблона с использованием Template API, после чего выводит возвращаемый объект типа ParseResponsePayload через stdout. Если была выбрана команда publish, результаты опубликуются в Figma.

npx figma connect publish --config figma.config.json --token <auth token>

Create (создание)¶

Команда create получает определение указанного компонента из Figma, затем вызывает parserCommand в figma.config.json, передавая через stdin объект типа CreateRequestPayload с данными о компонентах. Парсер создаёт соответствующие файлы Code Connect и возвращает объект типа CreateResponsePayload в stdout.

npx figma connect create "<url_to_node>" -config figma.config.json --token <auth token>

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

Пользовательские парсеры настраиваются в figma.config.json. Помимо общей конфигурации, для пользовательских парсеров требуются следующие поля:

parser: должно быть установлено в "custom"
parserCommand: полный путь или команда для вызова парсера, например ./tools/parser или node parser.js
includes: обязательное поле для пользовательских парсеров; указывает, какие файлы передаются бинарному файлу при выполнении parse или publish

Пример файла figma.config.json¶

{
  "codeConnect": {
    "parser": "custom",
    "parserCommand": "node ../parserDirectory/parser.js",
    "include": [
      "**/*.figma.test"
    ],
    "exclude": [
    ]
  }
}

Входные данные¶

Тип входных данных для запроса parse имеет следующую структуру:

export type ParseRequestPayload = {
    mode: 'PARSE';
    // An array of absolute paths for the parser to process, representing all
    // files matched by the include/exclude globs for this parser.
    paths: string[];
    // Config options passed into this parser (not all parsers) from the config.
    // Each parser's configuration is separate and can take any shape, though we
    // will recommend using the same naming for common concepts like "importPaths".
    config: Record<string, any>;
};

Тип входных данных для запроса create имеет следующую структуру:

export type CreateRequestPayload = {
    mode: 'CREATE';
    // Absolute destination directory for the created file. The parser is free to
    // write to a different directory if appropriate (e.g. it analyses your codebase
    // to identify where this component should go), but usually it should respect this.
    destinationDir: string;
    // Optional destination file name. If omitted, the parser can determine the
    // file name itself.
    destinationFile?: string;
    // The filepath of the code to be connected. If present, this is used instead of
    // component.normalizedName
    sourceFilepath?: string;
    // The export to use from sourceFilepath (TypeScript only)
    sourceExport?: string;
    // A mapping of how Figma props should map to code properties
    propMapping?: PropMapping;
    // Information about the Figma component. This matches the REST API (except the
    // figmaNodeUrl and normalizedName fields), which should make it easier to
    // implement and maintain as we can just pass it through
    component: {
        // The URL of the Figma component. This field is not in the REST API but
        // is added for convenience.
        figmaNodeUrl: string;
        // The ID of the Figma component
        id: string;
        // The name of the Figma component
        name: string;
        // The name of the Figma component, nomalized for use in code.
        // This field is not in the REST API but is added for convenience.
        normalizedName: string;
        // The type of the Figma component
        type: 'COMPONENT' | 'COMPONENT_SET';
        // Map of the Figma component's properties, keyed by property name
        componentPropertyDefinitions: Record<
            string,
            ComponentPropertyDefinition
        >;
    };
    // The configuration object for this parser.
    // Each parser's configuration is separate and can take any shape, though we
    // will recommend using the same naming for common concepts like "importPaths".
    config: Record<string, any>;
};

export type ComponentPropertyDefinition = {
    // The property type
    type: 'BOOLEAN' | 'INSTANCE_SWAP' | 'TEXT' | 'VARIANT';
    // The default value of this property
    defaultValue: boolean | string;
    // All possible values for this property. Only exists on VARIANT properties
    variantOptions?: string[];
};

Выходные данные¶

Ожидаемый тип выходных данных команды parse приведён ниже. Поле template — это Javascript, используемый для отображения фрагмента на панели Code Connect. Документация API доступна здесь.

export const ParseResponsePayload = {
  // Array of Code Connect docs parsed from the input files
  docs: {
    // The Figma node URL the doc links to e.g. https://www.figma.com/design/123/MyFile?node-id=1-1
    figmaNode: string,
    // Optional component name. This is only used for display purposes
    // so can be omitted if it's not relevant to the language/framework
    component?: string,
    // Variant restrictions keyed by Figma property name e.g. `{ 'With icon': true }`
    variant?: Record<string, string>,
    // Source path - a relative path to the file containing the component definition
    source: string,
    // Optional source location containing line number information.
    sourceLocation?: {
        // Optional line number to link to. This is only used if type === 'PATH',
        // to generate a link to the correct line
          line: number
        },
    // The JS template function to use for this doc
    template: string,
    templateData: {
      // Map of information describing the props used by the template. This is
      // used by the CLI to validate props before publishing.
      props: PropMapping,

      // Optional array of imports for this component. These are prepended
      // to the example code.
      imports?: string[],

      // Whether the example should be rendered inline if it's a nested instance
      nestable?: boolean,
    }),
    // The language to use for syntax highlighting
    // supported values can be found in the SyntaxHighlightLanguage type below
    language: SyntaxHighlightLanguage,
    // Label to be used for the example in the UI
    label: string,
  }[],
  // Any info, warning or error messages generated during parsing.
  messages: ParserExecutableMessages,
}

export const ParserExecutableMessages = {
  // DEBUG and INFO messages should be output to console by the CLI for the
  // user to read, according to the current log level setting.
  //
  // If any WARNING or ERROR messages are returned, the CLI can determine
  // whether it should proceed with publishing or not based on configuration
  // and the return code should be zero or non-zero as appropriate.
  level: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR',
  // Optional type of message which can be displayed highlighted in the output
  type?: string,
  message: string,
  // Optional source location which can be displayed in a standardised form
  sourceLocation?: {
      file: string,
      line?: number,
    },
}[]

export type PropMapping = Record<string, Intrinsic>

export type SyntaxHighlightLanguage =
  | 'typescript'
  | 'cpp'
  | 'ruby'
  | 'css'
  | 'javascript'
  | 'html'
  | 'json'
  | 'graphql'
  | 'python'
  | 'go'
  | 'sql'
  | 'swift'
  | 'kotlin'
  | 'rust'
  | 'bash'
  | 'xml'
  | 'plaintext'
  | 'jsx'
  | 'tsx'
  | 'dart'

Ожидаемый тип выходных данных команды create имеет следующую структуру:

export const CreateResponsePayload = {
  // A list of files created, which can be output to the console
  createdFiles: {
      // The absolute path of the created file
      filePath: string,
    }[],
  // Any info, warning or error messages generated during creation.
  messages: ParserExecutableMessages,
}

Пример реализации шаблона¶

Ниже приведён подробный пример реализации шаблона с использованием Template API:

const figma = require('figma');
const instance = figma.selectedInstance;

// Getting property values
const stringProp = instance.getString('String Prop');
const booleanProp = instance.getBoolean('Boolean Prop');
const enumProp = instance.getEnum('Enum Prop', {
    Option1: 'value1',
    Option2: 'value2',
});

// Finding layers
const textLayer = instance.findText('Label');
const childInstance = instance.findInstance('Icon');
const connectedInstance = instance.findConnectedInstance('button-123');

// Using selector options
const nestedText = instance.findText('Description', {
    path: ['Container', 'Content'],
    traverseInstances: true,
});

// Using selector functions
const allButtons = instance.findConnectedInstances(
    (node) => node.properties['type'] === 'button',
);

export default {
    example: figma.code`<Component
  label={${stringProp}}
  enabled={${booleanProp}}
  variant={${enumProp}}
  icon={${childInstance?.executeTemplate().example}}
/>`,
    id: 'example-id',
};

Источник: https://developers.figma.com/docs/code-connect/

Figma Code Connect — полный гайд¶

Code Connect CLI¶

Code Connect UI¶

Файлы шаблонов (рекомендуется)¶

Устаревшие API, специфичные для фреймворков¶

Публикация в Figma для упрощения передачи в разработку¶

Начало работы с Code Connect UI¶

Подключение компонентов из библиотеки дизайна¶

Подключение репозитория GitHub (необязательно)¶

Ручное подключение компонентов¶

Подключение компонентов из выбранного фрейма¶

Подключение одного компонента к нескольким фреймворкам¶

Добавление нескольких связей¶

Добавление пользовательских инструкций для генерации кода AI¶

Добавление инструкций для MCP¶

Превью AI-сгенерированных сниппетов кода¶

Подключение репозитория GitHub¶

Что даёт интеграция¶

Подключение файла библиотеки¶

Авторизация доступа¶

Подключение к репозиторию¶

Сравнение Code Connect UI и Code Connect CLI¶

Обзор¶

Сравнение возможностей¶

Начало работы с Code Connect CLI¶

Перед началом¶

Установка инструмента командной строки Code Connect¶

Конфиденциальность и Code Connect¶

Настройка проекта¶

Создание файлов шаблонов с помощью AI-агента¶

Создание первого файла шаблона вручную¶

Publish Code Connect files¶

Unpublish Code Connect files¶

Следующие шаги¶

Настройка проекта¶

Общие параметры конфигурации¶

include и exclude¶

parser¶

label¶

language¶

interactiveSetupFigmaFileUrl¶

documentUrlSubstitutions¶

defaultBranch¶

Конфигурация проекта для React¶

importPaths¶

paths¶

imports¶

Написание файлов шаблонов¶

Настройка¶

Формат файла шаблона¶

Метаданные в комментариях¶

Построение фрагмента¶

Доступ к свойствам инстанса¶

Работа с вложенными инстансами¶

Работа со слотами¶

Выбор между слотами и findConnectedInstances¶

Отображение фрагмента¶

Формат экспорта¶

Скрипт миграции¶

Мигрированные файлы¶

Проверка пакетной миграции¶

Ограничения вариантов¶

Тестирование в Figma¶

Справочник Template API¶

figma¶

Формат экспорта¶

figma.selectedInstance: InstanceHandle¶

figma.code¶

figma.batch¶

figma.helpers¶

React Helpers¶

renderProp(name: string, prop: any): string¶

renderChildren(prop: any): string | ResultSection[]¶

Хелперы типов значений¶

renderPropValue(prop: any): string | ResultSection[]¶

stringifyObject(obj: any): string¶

isReactComponentArray(prop: any): boolean¶

Объект InstanceHandle¶

Свойства¶

properties: Record<string, string | boolean | InstanceHandle>¶

`include` и `exclude`¶

`parser`¶

`label`¶

`language`¶

`interactiveSetupFigmaFileUrl`¶

`documentUrlSubstitutions`¶

`defaultBranch`¶

`importPaths`¶

`paths`¶

`imports`¶

Выбор между слотами и `findConnectedInstances`¶

`figma`¶

`figma.selectedInstance:` `InstanceHandle`¶

`figma.code`¶

`figma.batch`¶

`figma.helpers`¶

`renderProp(name: string, prop: any): string`¶

`renderChildren(prop: any): string | ResultSection[]`¶

`renderPropValue(prop: any): string | ResultSection[]`¶

`stringifyObject(obj: any): string`¶

`isReactComponentArray(prop: any): boolean`¶

Объект `InstanceHandle`¶

`properties: Record<string, string | boolean | InstanceHandle>`¶

`getBoolean(propName: string, options?: Record<string, any>): boolean | any`¶

`getString(propName: string): string`¶

`getEnum(propName: string, options: Record<string, any>): any`¶

`getSlot(propName: string):` `SlotResult` `| undefined`¶

`getInstanceSwap(propName: string):` `InstanceHandle`¶

`getPropertyValue(propName: string): string | boolean`¶

`executeTemplate(): { example: ResultSection[], metadata: Metadata }`¶

`hasCodeConnect(): boolean`¶

`codeConnectId(): string | null`¶

`findText(layerName: string, opts?: SelectorOptions):` `TextHandle` `| ErrorHandle`¶

`findInstance(layerName: string, opts?: SelectorOptions):` `InstanceHandle` `| ErrorHandle`¶

`findConnectedInstance(codeConnectId: string, opts?: SelectorOptions):` `InstanceHandle` `| ErrorHandle`¶

`findConnectedInstances(selectorFn: (node:` `InstanceHandle) => boolean, opts?: SelectorOptions):` `InstanceHandle[]`¶

`findLayers(selectorFn: (node:` `InstanceHandle` `|` `TextHandle) => boolean, opts?: SelectorOptions): (InstanceHandle` `|` `TextHandle` `| ErrorHandle)[]`¶

Объект `TextHandle`¶

`textContent: string`¶

Объект `SlotResult`¶

`connectedInstances:` `InstanceHandle[]`¶

`figma.batch`¶