figma-bridge-mcp

Локальный MCP-сервер, который позволяет ИИ-ассистентам просматривать, создавать и обновлять дизайны в Figma Desktop. Он подключается через небольшой плагин разработки Figma и предоставляет узконаправленные инструменты для скриншотов, дизайн-спецификаций, рендеринга JSX, токенов, ассетов, компонентов, FigJam и Figma Slides.

Всё работает на 127.0.0.1. Не требуется Figma Personal Access Token. Никакого облака. Никакого бинарного патчинга приложения Figma.

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

Требования: Node.js 18 или новее, Figma Desktop и MCP-клиент, который умеет запускать локальные stdio-серверы.

Codex, Claude Code и Cursor: MCP и навыки в одном пакете

Figma Bridge поставляется с тремя узконаправленными общими навыками и тонкими плагин-адаптерами для всех трёх клиентов:

• figma-bridge-design-to-code — точная реализация Figma в целевом стеке;

• figma-bridge-code-to-figma — семантические, компонентизированные экраны из кода;

• figma-bridge-component-library — токены, стили, компоненты, варианты и свойства.

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

Для Codex добавьте этот репозиторий как маркетплейс и установите пакет:

codex plugin marketplace add KaiUweHella/figma-bridge-mcp
codex plugin add figma-bridge-mcp@figma-bridge

Это маркетплейс репозитория, размещённый на GitHub, а не заявка в универсальный каталог плагинов OpenAI. Каталог следует за репозиторием, а каждая выпущенная запись плагина закрепляет точный Git-тег v<version> и запускает соответствующую версию npm-рантайма. Поэтому main и @latest не могут незаметно перенести установленный пакет навыков на другой контракт сервера.

Для Claude Code добавьте этот репозиторий как маркетплейс и установите пакет:

claude plugin marketplace add KaiUweHella/figma-bridge-mcp
claude plugin install figma-bridge-mcp@figma-bridge

Маркетплейс Claude использует тот же закреплённый GitHub-релиз и общее дерево навыков. Соответствующий npm-пакет должен быть опубликован до того, как пользователи установят этот релиз, поскольку плагин запускает свой локальный stdio-сервер через npx.

Для Cursor Teams или Enterprise импортируйте этот GitHub-репозиторий в командный маркетплейс и установите Figma Bridge из раздела Customize. Отдельные пользователи и контрибьюторы могут использовать тот же GitHub-исходник без центрального листинга Cursor: клонируйте помеченный релиз, подключите этот чекаут к Cursor и перезагрузите окно:

mkdir -p ~/.cursor/plugins/local
ln -s /absolute/path/to/figma-bridge-mcp ~/.cursor/plugins/local/figma-bridge-mcp

Cursor обнаруживает корневой манифест Agent Plugin и загружает и навык, и MCP-сервер.

Клиенты без поддержки плагинов или Agent Skill продолжают использовать обычную конфигурацию сервера ниже. Они по-прежнему получают компактный обязательный рабочий процесс через инструкции MCP, вызываемые пользователем MCP-промпты design-to-code, code-to-figma и create-figma-component, а также figma_reference {name:"workflow"}.

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

1. Добавьте MCP-сервер (запасной вариант только с MCP)

Используйте это, когда полная установка плагина недоступна или вам нужны только MCP-инструменты без встроенного навыка. Настройка через npx не требует клонирования или сборки. Для Claude Code:

claude mcp add figma-bridge -- npx -y figma-bridge-mcp@latest

Для другого MCP-клиента добавьте эквивалентную конфигурацию сервера:

{
  "mcpServers": {
    "figma-bridge": {
      "command": "npx",
      "args": ["-y", "figma-bridge-mcp@latest"]
    }
  }
}

Перезапустите MCP-клиент, если он не обнаружит сервер сразу. Здесь намеренно нет блока env: мост создаёт свои локальные учётные данные во время сопряжения.

git clone https://github.com/KaiUweHella/figma-bridge-mcp.git
cd figma-bridge-mcp
npm install

{
  "mcpServers": {
    "figma-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/figma-bridge-mcp/src/server.js"]
    }
  }
}

2. Сопрягите Figma Desktop один раз

1. Попросите вашего ИИ-ассистента подключиться к Figma или вызовите figma_connect напрямую. Он запустит локальный мост и вернёт ключ доступа и путь к манифесту плагина.

2. В Figma Desktop: Plugins → Development → Import plugin from manifest… и выберите ~/.figma-bridge-mcp/plugin/manifest.json (путь, возвращённый figma_connect).

3. Откройте Plugins → Development → Figma Bridge, вставьте ключ доступа и нажмите Save & connect.

4. Когда плагин покажет Connected (authenticated), ассистент сможет работать с этим файлом Figma. Сопряжение запоминается; в следующих сессиях просто снова откройте плагин в нужном файле.

Figma Dev Mode требует отдельных адаптеров, потому что Figma не поддерживает объединение существующей цели редактора FigJam с dev в одном манифесте:

• Импортируйте ~/.figma-bridge-mcp/plugin/manifest.dev.json для Figma Bridge Dev Mode. Он поддерживает аутентифицированный MCP-мост подключённым для выделения, инспекции, спецификаций и экспорта. Dev Mode доступен только для чтения, поэтому рендеринг и правки холста по-прежнему требуют переключения файла в режим Design и открытия обычного плагина Figma Bridge там.

3. Используйте его с Figma

Выберите фрейм или слой в Figma и опишите желаемый результат. Например:

• «Проверь мой текущий выбор и объясни его раскладку.»

• «Создай карточку настроек рядом с выбранным фреймом.»

• «Экспортируй токены и ассеты выбранного экрана в этот проект.»

• «Реализуй выбранный фрейм, затем сравни результат с Figma.»

Ассистент может читать текущее выделение, делать скриншоты и спецификации, рендерить JSX, экспортировать ассеты или применять точечные правки. Держите плагин Figma Bridge открытым в каждом документе, к которому ассистент должен иметь доступ. Если подключено более одного документа, передайте URL Figma или ключ файла, чтобы цель была однозначной.

Related MCP server: tellfigma

Как это работает

MCP client ──stdio──▶ figma-bridge-mcp (src/)
                        │
                    MCP tool adapters ─▶ Capability Catalog ─▶ CommandPlan
                                                                  │
                                          ┌───────────────────────┴──────────┐
                                  Command Application Modules   generic CLI adapter
                                             │            │
                                      Design Capture      │
                                      Asset Policy        │
                                             └──────┬─────┘
                                      Daemon Client Module
                                             │  HTTP: signed requests
                                             ▼
                                  local daemon :3456–3460
                                             │  WS: challenge/response
                                             ▼
                                  Figma Bridge plugin in Figma Desktop

• Движок находится в engine/. Он начинался как форк figma-ds-cli v2.1.0 и ушёл далеко вперёд (см. атрибуцию). Режим «Yolo mode» из Chrome-DevTools, патчивший бинарник приложения Figma, был полностью удалён; к нему нет ни одного пути в коде.

• Специализированные MCP-чтения (figma_spec, figma_inspect, figma_screenshot) выполняются напрямую через Command Application Modules, возвращающие значения. MCP и CLI — тонкие адаптеры поверх одних и тех же реализаций; обобщённый figma_run остаётся намеренно широким CLI-адаптером дочерних процессов. Один Daemon Client Module отвечает за подпись, таймауты и ошибки транспорта для обоих путей.

• Design Capture Module один раз обходит явный узел и локально проецирует структуру, стиль и форматы вывода без потерь из тех же фактов. Capture повторно используется только после того, как дешёвый зонд ревизии подтвердит, что аутентифицированное подключение плагина и ревизия документа Figma не изменились. Отсутствие или нестабильность метаданных ревизии отключает повторное использование; вызовы выделения и именованных секций остаются некэшируемыми в этом первом Slice.

• Capture различают авторский Figma Auto Layout/Grid, помеченную Figma эвристику inferredAutoLayout и геометрический запасной вариант. Они также сохраняют семантические/запасные метаданные Code-to-Figma отдельно от более поздних нативных аннотаций Figma, а также полные контракты компонентов и режимов переменных.

• Design Link Registry присваивает компоненту, экрану или фрейму один устойчивый, принадлежащий репозиторию идентификатор Design Entity. figma-bridge.json хранит переносимые ссылки code/Storybook/Figma; данные плагина Figma хранят только тот же id и вид. Такая двойная привязка позволяет будущим агентам находить точный существующий компонент с любой стороны, не помещая пути репозитория в документ Figma.

• Работающий только в режиме отчёта Round-trip Planner сравнивает текущий код и текущее нормализованное поддерево Figma с явным Accepted Design Baseline. Project Design Context проецирует этот статус, ссылки на сущности и точные следующие чтения через один внутрипроцессный Command Application. Когда существуют семантические пути, изменённые поддеревья сообщаются с их текущими идентификаторами узлов; сами маркеры плагинов никогда не считаются визуальными изменениями.

• Design Contract превращает полный Design Capture одной связанной Design Entity в детерминированный шлюз репозитория. Запустите figma_run ["contract", "capture","ui.button"] один раз и просмотрите JSON; затем figma_run ["contract","check","ui.button"] сообщает о каноническом расхождении и отдельно проверяет матрицы вариантов, минимальные уровни привязки токенов, геометрические допуски и переходы прототипов. Изменчивые дескрипторы Figma игнорируются, а capture с ограничением глубины отклоняются.

• Единый Capability Catalog преобразует каждую команду Figma, поступающую через MCP, в неизменяемый план до того, как любой из адаптеров выполнения запустит её. Этот план является единственным источником для экспозиции, эффектов Figma/workspace/shared-state, потребности в цели, подтверждения, нормализованных путей, повторов, таймаута, допустимых кодов выхода и идентичности фоновых заданий. Неизвестные команды по умолчанию получают denied/write/no-retry.

• Один неизменяемый Figma Target Context разрешает явный fileKey, вставленный URL Figma или неявное нацеливание на одно окно один раз на команду, а затем сопровождает планирование, аудит, идентичность задания и выполнение демона. Один общий Asset Policy классифицирует заливки изображениями, векторную графику и векторные кластеры как для проекций Design Capture, так и для экспорта.

• Валидаторы протокола времени выполнения отклоняют некорректные HTTP-полезные нагрузки выполнения и фреймы плагинов на границе транспорта. TypeScript проверяет JavaScript-швы (включая плагин Figma), а детерминированные контекст, полезная нагрузка и бюджеты медианной и хвостовой задержки выявляют архитектурные регрессии в CI, не рассматривая кратковременные паузы планирования общего раннера как устойчивую регрессию.

• Демон передаёт команды плагину Figma через WebSocket на localhost. Его защищают два барьера:

  • HTTP-маршруты (/health, /exec) требуют подпись HMAC для каждого запроса, ключом которой служит токен сессии — файл с правами 0600; сам токен никогда не передаётся по сети.

  • WebSocket плагина (/plugin) требует ключ доступа: список разрешённых Origin/Host плюс взаимное рукопожатие с вызовом-ответом, в котором ключ всегда является только HMAC-секретом и тоже никогда не передаётся по сети. Это закрывает пробел в апстриме, где любой локальный процесс мог подключиться к сокету плагина и выполнить код в вашем документе Figma, — и обратный пробел, где любой отвечающий на локальном порту процесс мог управлять честным плагином.

Идентификаторы узлов принимаются в любой форме, доступной пользователю: 12:34, URL-форма 12-34 или полный URL Figma (чей ключ файла проверяется на соответствие файлам, которые у вас открыты — см. Несколько файлов одновременно).

Команды на запись можно защитить явным confirm:true, установив FIGMA_WRITE_CONFIRM=1 в окружении сервера. Защита работает на уровне подкоманд: чтение, например node tree или component list, проходит свободно, мутации вроде node delete, combos или tokens spacing требуют подтверждения.

Родные экземпляры JSX требуют постоянной идентичности в реестре (entity плюс опубликованный key или локальный id). Их редактируемые переопределения используют реальную структуру Figma компонента:

<Instance entity="ui.card" key="..."
  prop:Selected="true"
  text:Title="New title"
  fill:StatusDot="var:status/healthy|#22c55e"
  swap:LeadingIcon="ui.icon.leaf" />

prop: разрешает определение свойства компонента; text: и fill: разрешают одного именованного потомка. Значения swap: и значения свойства INSTANCE_SWAP — это идентификаторы Design Entity, разрешаемые из figma-bridge.json; отображаемые имена компонентов намеренно не принимаются в качестве идентификатора замены. Отсутствующие, неоднозначные или несвязанные цели останавливают предварительную проверку до создания первого узла холста.

Размеры и типографика принимают ту же форму var:name|fallback. Родной исполнитель связывает ширину, высоту и ограничения min/max, а также семейство/стиль шрифта, вес, размер, межстрочный интервал, межбуквенный интервал, межабзацный интервал и отступ абзаца. Семейство/стиль используют переменные STRING; остальные поля типографики и размеров — переменные FLOAT. Отсутствие связанного шрифта останавливает предварительную проверку с сообщением «установите или выберите другой шрифт» вместо молчаливой замены. Именованные текстовые стили также согласовываются до создания холста: явный style="Typography/Eyebrow" повторно используется только при полном совпадении типографики; конфликтующий стиль с тем же именем останавливает, в остальных случаях точная типографика повторно используется или создаётся под детерминированным именем Typography/Generated/.... Обратное чтение метрики float32 в Figma нормализуется для стабильного сравнения, и семейственно-специфичные начертания, такие как DM Sans/Manrope SemiBold и ExtraBold, пробуются перед любым запасным семейством. Успешные родные рендеры возвращают счётчики textStyleReport и variableReport — ссылки, уникальные повторно используемые переменные, созданные переменные и связанные свойства. Ошибки предварительной проверки с неоднозначностью или неподдерживаемостью включают соответствующие нулевые/ненулевые счётчики и не оставляют после себя новых созданных переменных или узлов холста.

<Text> также сохраняет редактируемый встроенный форматированный текст. Вложенная разметка <strong>/<b>, <em>/<i>, <u>, <Span ...> и <a href="..."> становится родными диапазонами Figma; HTML-сущности декодируются перед расчётом смещений в UTF-16. Пробеги Span поддерживают font, fontStyle, weight, italic, size, color, letterSpacing, underline/decoration и безопасные ссылки:

<Text font="Inter" size="14">
  Hello <strong>bold <em>and italic</em></strong>
  <Span color="#ef4444" size="18">red</Span>
  <a href="https://example.com">link</a>
</Text>

Окно плагина

Окно плагина Figma Bridge — это не только индикатор подключения:

• Активность — каждая команда, выполняемая агентом, в реальном времени, с длительностью и статусом ok/ошибка; записи выделены. В свёрнутой строке отображается счётчик (12 ok · 1 failed); в строке заголовка — подключённый порт и задержка кругового обхода.

• Приостановить агента — аварийный выключатель: пока приостановлен, плагин отклоняет все входящие команды агента с явной ошибкой.

• Сохранить версию — записывает помеченную запись в историю версий Figma (Figma Bridge — <timestamp>) как ручную точку восстановления перед тем, как дать агенту волю. API восстановления для плагинов нет: откат выполняется через панель истории версий Figma.

• Чтение выделения — что бы ни выбрал пользователь, автоматически (с устранением дребезга) передаётся агенту и отображается как «Агент видит: …», так что пользователь всегда видит, что вернёт figma_selection. Выберите фрейм, скажите «построй это» — копировать идентификатор узла не нужно.

• Настройка — ключ доступа и опциональный REST-токен, всегда доступны, независимо от того, подключён ли мост.

Рабочий процесс «дизайн → код»

Дизайн — это полная спецификация; инструментарий делает его копирование проще, чем интерпретацию. Соберите экран из Figma за шесть шагов:

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

1. figma_screenshot на целевом фрейме, затем прочитайте сохранённый PNG — это визуальный эталон. Никогда не стройте только по дереву узлов.

2. figma_spec с phase: "structure" — постройте каркас разметки: реальные текстовые символы, разрешённые имена иконок/компонентов (экземпляры раскрываются, поэтому отображаются переопределения и настоящие имена главных компонентов), иерархия и направление flex. Копируйте тексты и иконки дословно. Маркер layout:inferred (Figma heuristic — verify) не является авторским Auto Layout; проверьте иерархию, прежде чем считать его контрактом компонента.

3. Экспорт токенов (figma_run с ["export","css"] или ["export","dtcg"]) и подключите их как CSS-переменные / тему. В выводе указан исходный Figma-файл — проверьте, что это тот файл, который вы строите.

4. Экспорт ресурсов (figma_run с ["export","assets","<nodeId>","-o","/abs/path/src/assets"]) — каждая ссылка → assets/… в спецификации указывает на файл, который записывается этой командой. Передавайте абсолютный путь; большие экспорты продолжают работу в фоне («still RUNNING») — повторно вызовите ту же команду для опроса. assets.json объединяется между запусками, а байт-идентичные ресурсы дедуплицируются. Каждая запись содержит данные о размещении (x/y смещения, путь к родительскому элементу parent, parentId, absolutePosition, overhang), поэтому манифест сам позиционирует оверлей — перекрёстная ссылка на спецификацию не нужна. Сводка экспорта явно перечисляет абсолютно позиционированные и выступающие файлы: именно их теряют сборки. Крупные PNG по умолчанию даунсемплятся до 2× их наибольшего использования в Figma (ретина-плотность), без апскейла и только когда закодированный файл становится меньше. Соотношение сторон, размещение в манифесте и CSS-обрезка остаются неизменными; передайте --raster-scale 0, чтобы сохранить исходные байты PNG.

5. figma_spec с phase: "style" — примените размеры, отступы, паддинги, выравнивание, fill/hug-размеры, заливки, включая градиенты (→ var(name) обозначает привязку к дизайн-токену), радиусы, тени, типографику, opacity, clip (overflow hidden) и abs-позиционирование. Декоративные векторы отображаются как строки vector art → assets/… с размещением — размещайте экспортированные SVG, никогда не аппроксимируйте их в CSS.

   Структурированный YAML/JSON дополнительно сохраняет точные определения свойств компонентов и их значения (включая INSTANCE_SWAP и SLOT), ссылки на свойства, предпочтительные значения, прямые переопределения, открытые экземпляры и нарушения слотов. Привязки переменных включают идентификатор коллекции, авторские области видимости, явные/разрешённые режимы, codeSyntax.WEB и разрешённое значение; inferredVariables выводится отдельно как доказательство только для предложений.

   Для большого раздела сначала запросите depth:0. Это полный контракт для самого контейнера раздела (включая фон, границу, радиус и макет) без потомков. Затем запрашивайте идентификаторы дочерних узлов в ограниченных вызовах. Используйте dedup:true для повторяющихся карточек/списков; общие ссылки S<n> остаются без потерь и предотвращают исчерпание бюджета результата одинаковыми стилями экземпляров.

6. Верификация — сделайте скриншот вашей сборки и сравните с PNG из шага 1, затем выполните механическую проверку:

   figma_run ["verify-build", "/abs/path/to/project"]

   Она ищет в проекте по assets.json и перечисляет каждый экспортированный файл, который не используется в сборке — с размером, смещениями и родителем, так что размещение — один шаг, — плюс проверку border-image (CSS border-image игнорирует border-radius; градиентные обводки на скруглённых блоках требуют обёртки или маски). Код выхода 1, если файлы отсутствуют, поэтому работает и как CI-шлюз.

   Со скриншотом сборки также выполняется визуальная проверка:

   figma_run ["verify-build", "/abs/path/to/project", "--compare", "/abs/build.png"]

   Эталонный рендер загружается из Figma в реальном времени (--node <id>, по умолчанию: корень экспорта манифеста) или предоставляется офлайн через --design <png>. Оба изображения нормализуются до общей ширины и сравниваются по пикселям (устойчиво к сглаживанию); вывод сообщает общий процент различий, обнаружение несовпадения высоты (сборка слишком высокая/низкая = вставленный или удалённый блок), наихудшие различающиеся области в координатах узла-пикселя — то же пространство, которое используют спецификация и assets.json, — и записывает diff PNG (красный = различие, на затемнённом дизайне). По умолчанию информационно; --max-diff <pct> управляет кодом выхода.

Для больших экранов агенты уровня секции являются необязательной оптимизацией затраченного времени после того, как скриншот, карта структуры, токены и ресурсы зафиксированы. Используйте их только для значительных секций с несвязанными файлами компонентов/стилей; координатор сохраняет владение общей оболочкой, токенами, assets.json, интеграцией и финальным пиксельным diff. Параллельные агенты обычно потребляют больше суммарных токенов, потому что каждому нужен контекст проекта, поэтому используйте последовательную работу, когда стоимость токенов важнее реального времени.

Используйте существующий инструмент браузера или проектную обвязку для скриншота сборки. Не устанавливайте Playwright (или другую зависимость браузера) только для захвата без одобрения пользователя; если он уже присутствует, это допустимый механизм захвата, а не зависимость Figma Bridge.

Та же спецификация доступна как figma_run ["export", "code-spec", "<nodeId>"]. По умолчанию это читаемое дерево; передайте -f yaml или -f json для канонической модели.

Форматы структурированных спецификаций без потерь

figma_spec и export code-spec по умолчанию используют format:"tree" — краткое, ориентированное на агента представление, в нижнем колонтитуле которого указаны необходимые действия с ресурсами и точностью. Используйте yaml или форматированный json явно, когда потребителю нужна версионированная каноническая модель. Оба структурированных формата сериализуют одну и ту же модель; различается только синтаксис. Тесты на roundtrip требуют, чтобы каждое поле — текст, идентификаторы, происхождение макета, заливка, типографика, переменные с учётом режима, ресурсы, контракты компонентов, намерения Bridge, нативные аннотации, полнота захвата и проверки точности — выживало точно. Минифицированный JSON не предлагается: реальные тесты агентов показали, что одна огромная строка была существенно сложнее для обработки, несмотря на те же необработанные поля.

Поле capture модели явно сообщает запрошенную/фактическую глубину, полноту полезной нагрузки, политику скрытых узлов и то, отсекла ли запрошенная глубина потомков. Нет молчаливого усечения результата инструмента: если спецификация превышает настроенный бюджет вывода, вызов возвращает complete:false с рецептом повторной попытки по разделам и не возвращает вводящий в заблуждение частичный дизайн. depth:0 намеренно означает «только запрошенный узел» и является полным, а не деревом с усечённой глубиной.

Имена файлов IMAGE-fill привязаны к стабильному хешу изображения Figma, а не к локальному имени/пути слоя. Это гарантирует, что figma_spec, изолированные дочерние вызовы, экспорт ресурсов и assets.json используют одно и то же имя файла, даже если общие слои, такие как «Frame 64», достигаются через разные корни.

Для вызовов MCP «дизайн-в-код» по умолчанию используется dedup:false: каждый видимый слой сохраняет свой собственный идентификатор, нативный Figma Inspect css{…}, факты о макете/заливке/токенах и полный текст. Смешанные многостилевые слои несут свои индивидуальные стилизованные диапазоны. Нижний колонтитул согласует количество живых видимых слоёв с явными строками, внутренностями SVG, внутренностями компонентов и вспомогательными элементами, не участвующими в рендеринге. Проекция стиля отклоняется, когда ограничения глубины или неучтённый слой вынуждают угадывать; разделите её по идентификаторам узлов из карты структуры. Устанавливайте dedup:true только для компактного обзора с использованием общих ссылок на стили S<n> и повторений.

Для повторяющихся вызовов с явными узлами phase, format и дедупликация не запускают полный обход Figma заново. Кэш Design Capture в памяти ограничен 8 записями / 8 МиБ по умолчанию (DESIGN_CAPTURE_CACHE_ENTRIES и DESIGN_CAPTURE_CACHE_BYTES). Каждое попадание всё равно проверяет ревизию живого документа; TTL и stale-while-revalidate отсутствуют.

Память кода ↔ Figma-дизайна

Присвойте каждому важному компоненту, экрану или фрейму постоянный идентификатор Design Entity. Идентификатор описывает концепцию, а не текущее местоположение: используйте имена вроде ui.button, ui.account-card или screen.settings.

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

figma_run {args:["link","set","9:9","screen.settings","--kind","screen","--source","src/routes/settings.tsx","--export","SettingsScreen","--story","screens-settings--default"], confirm:true}

Это объединяет два небольших адаптера:

• figma-bridge.json — это зафиксированный, проверяемый реестр с путями кода относительно репозитория, а также опциональными дескрипторами Storybook и Figma.

• Figma хранит только {version,id,kind} в качестве данных плагина на узле. Он не содержит локального пути, учётных данных или машинно-зависимого состояния.

Используйте figma_run ["link","inspect","9:9"] для разрешения узла и figma_run ["link","list"] для просмотра памяти репозитория без чтения Figma. После связывания figma_selection и figma_spec автоматически раскрывают тот же идентификатор и цели кода/Storybook из реестра. Агенты должны повторно использовать или редактировать этот компонент кода вместо создания похожего. Повторение той же команды set безопасно и восстанавливает любую сторону после прерванной записи.

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

figma_run ["link","accept","screen.settings","--compare","/abs/build.png","--max-diff","5"]

Исходный код никогда не хранится в реестре. Начальный адаптер кода хеширует полный связанный файл вместе с его экспортной идентичностью; поэтому несвязанное редактирование в общем файле может консервативно сообщить об изменении кода, но реальное изменение никогда не скрывается. Адаптер Figma хеширует нормализованное связанное поддерево. Для узлов «Код-в-Figma» он также сохраняет каждый уникальный figmaBridge.semanticPath с хешем поддерева этого узла. Последующий link status может поэтому перечислить точные добавленные, удалённые или изменённые семантические пути и рекомендовать спецификации с областью действия узла. Изменение только семантического маркера не меняет визуальный отпечаток; дублирующиеся пути сообщаются как неоднозначные, а не угадываются.

figma_run ["link","status","screen.settings"]
figma_run ["link","context","screen.settings"]

link context — предпочтительная точка входа агента после установления связи. Он возвращает наименьшую релевантную проекцию: сущность, код/экспорт, корень Figma, историю Storybook, текущий план Round-trip, обнаруженные файлы DESIGN.md/токенов и точные следующие чтения. Он генерируется по запросу, а не сохраняется как ещё один файл памяти. link accept записывает только figma-bridge.json; он никогда не изменяет Figma или код. Для экранов он также сохраняет измеренный diff и SHA-256 хеши обоих сравниваемых изображений, поэтому структурный отпечаток не может подтвердить визуально неверный базис.

Обычные расположения DESIGN.md, design/DESIGN.md, tokens.json и design/tokens.json обнаруживаются автоматически. Настройте пользовательские пути относительно репозитория один раз при необходимости:

figma_run ["link","configure","--design-doc","docs/product-design.md","--tokens","src/theme/tokens.json"]

Зафиксируйте figma-bridge.json. Не помещайте в него секреты, абсолютные пути или сгенерированные учётные данные. Схема и правила конфликтов описаны в docs/adr/0007-dual-anchor-design-entities.md, с решениями по базису и контексту в ADR-0008 и ADR-0009.

Проверенные стратегии границ CSS ↔ Figma

Семантический «Код-в-Figma» использует стабильные идентификаторы политик, а не молчаливые визуальные замены: minmax.native-grid, space-around.equal-slots, border.single-paint-native, sticky.metadata-only, filters.layer-stack, masks.vector-mask, font.named-faces и figma-effects.native. Полная матрица и её оставшиеся жёсткие ограничения находятся в docs/css-figma-semantic-matrix.md.

Проверенные рискованные политики могут автоматически добавлять собственную аннотацию Figma на точно затронутом семантическом узле. Аннотация объясняет неподдерживаемый факт CSS, ссылается на соответствующие свойства Figma и дублируется в виде версионированных данных плагина figmaBridge.fallbackAnnotations для будущих агентов. Эквивалентные нативные преобразования остаются без аннотаций, чтобы избежать шума при проверке. Первая активная политика — border.single-paint-native: Figma получает первую явно заданную сторону CSS в качестве общего нативного обводки, сохраняет все четыре значения толщины сторон и отмечает strokes плюс strokeWeight. Нативные рендеры сообщают, сколько запасных аннотаций было добавлено, дедублицировано или не поддержано.

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

Оси вариативных шрифтов захватываются, но структурный шлюз спрашивает, следует ли установить требуемый шрифт или использовать доступное именованное начертание перед рендерингом. Нативное стекло Figma остается редактируемым нативным эффектом со всеми сохраненными параметрами эффекта; оно не обрабатывается молча как CSS backdrop-filter, потому что экспорт CSS из Figma не раскрывает эти параметры стекла.

Зеркалирование Storybook

Компоненты Figma несут стабильный ключ публикации (переживает публикацию библиотеки; идентификаторы узлов локальны для файла). Теперь ключ передается через figma_spec (каноническая структурированная модель + трейлер дерева "Используемые наборы компонентов"), figma_selection, component list, figma_inspect и DESIGN.md.

Чтобы связать их с зеркалом кода:

figma_run ["map", "storybook", "http://localhost:6006"]

Это сопоставляет компоненты файла с индексом Storybook по нормализованному имени и записывает figma-map.json в ваш проект: ключ Figma ↔ идентификатор истории / путь импорта, с confidence для каждого совпадения плюс оба списка несовпавших. Редактируйте записи вручную и установите "matchedBy": "manual", чтобы закрепить их — закрепленные записи переживают повторные запуски. Когда файл существует, figma_selection и figma_spec автоматически аннотируют компоненты с ↔ story <id> (<importPath>).

figma-map.json остается адаптером для чтения устаревших данных, поэтому существующие сопоставления продолжают работать. Новые долговечные ссылки должны находиться в figma-bridge.json; link set никогда не копирует в него устаревшие строки. Перенесите компонент при следующем касании, назначив его реальный идентификатор Design Entity и передав его историю через --story. Удалите устаревший файл только после того, как link list покажет все необходимые вам сопоставления.

Принесите свою собственную дизайн-систему

Этот проект не поставляется с никакой дизайн-системой — ни shadcn, ни пресета Tailwind, ни набора иконок. Это сделано намеренно: встроенная система — это чужое мнение, перенесенное в ваш файл. Вместо этого он предлагает способ сделать вашу систему понятной для агента одной командой:

figma_run ["kit", "init", "./my-app", "--storybook", "http://localhost:6006"]

Четыре чтения, один отчет:

Завершается он перечислением того, чего еще не хватает — неотображенный Storybook, компоненты без истории, команда tokens sync, которая поддерживает их синхронизацию, — потому что настройка, в которой молча отсутствует сопоставление, выглядит завершенной, пока агенту это не понадобится.

DESIGN.md — это то, что агент должен прочитать в первую очередь; tokens.json — то, к чему он привязывается.

Несколько файлов одновременно

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

• Одно окно — ничего не меняется. Команды направляются туда.

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

  figma_status                                        # lists every connected window
  figma_run {args: ["canvas","info"], fileKey: "GY5SasBJ…"}
  figma_spec {nodeId: "12:34", fileKey: "GY5SasBJ…"}

  figma_render, figma_selection, figma_inspect, figma_screenshot и figma_spec принимают один и тот же параметр fileKey. Полный URL узла Figma также автоматически предоставляет свой ключ файла. Без цели figma_selection сообщает, какие файлы открыты, вместо того чтобы угадывать. В CLI движка флаг — --figma-file, а не --file: eval и spec уже используют -f, --file для локального пути.

Намеренно отсутствует опция "все файлы". Каждая запись именует один файл, поэтому ошибочная команда не может распространиться по библиотеке. Два окна с одним и тем же файлом неразличимы для маршрутизации, поэтому более новое окно берет управление на себя, а старому сообщается, что оно потеряло мост. Записи аудита содержат ключ файла, поэтому figma_history остается читаемым, когда задействовано несколько файлов.

Доступ к файлам, которые вы не открывали, выходит за рамки: REST API Figma не может записывать содержимое документа, поэтому массовое переименование в тридцати библиотечных файлах — это не то, что этот инструмент может честно предложить.

FigJam

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

figma_run ["jam", "sticky", "Ship the handshake", "--color", "green"]
figma_run ["jam", "stickies", "[\"Discovery\",\"Build\",\"Ship\"]", "--columns", "3"]
figma_run ["jam", "shape", "Decide?", "--type", "DIAMOND"]
figma_run ["jam", "connector", "1:2", "3:4", "--text", "yes"]
figma_run ["jam", "table", "3", "4", "--data", "[[\"Step\",\"Owner\"],[\"Handshake\",\"Alex\"]]"]
figma_run ["jam", "board"]      # read everything back, with connectors
figma_run ["jam", "arrange"]    # arrange only the current selection
figma_run ["jam", "arrange", "--ids", "1:2,3:4"]
figma_run ["jam", "arrange", "--all"] # explicit: whole page

Новые узлы размещаются справа от того, что уже есть на доске, если только вы не передадите --at x,y, чтобы агент, добавляющий что-то на заполненную доску, не складывал все в начале координат. Каждая команда сначала проверяет figma.editorType и сообщает "это файл figma, а не доска FigJam", а не выдает ошибку из-за неопределенного API. figma_status сообщает, к какому редактору привязан мост.

jam arrange намеренно ограничен выделением. Агенты могут передавать точные идентификаторы узлов, не изменяя выделение пользователя; перестановка всей страницы требует видимого флага --all. Разделы и соединители этой командой никогда не перемещаются. Публичный интерфейс был протестирован в Figma Desktop 10 августа 2026 года. Сопровождающие хранят подробную информацию о командах и результатах за пределами публичного репозитория.

Figma Slides (бета)

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

figma_run ["slides", "inspect"]
figma_run ["slides", "create", "Agenda", "--row", "0", "--col", "1"]
figma_run ["slides", "duplicate", "Agenda", "--label", "Agenda alternative"]
figma_run ["slides", "move", "Agenda alternative", "1", "0"]
figma_run ["slides", "transition", "Agenda", "DISSOLVE", "--duration", "0.4"]
figma_run ["slides", "skip", "Appendix", "on"]
figma_run ["slides", "delete", "1:42"]

Figma перенумеровывает собственные имена слайдов всякий раз, когда изменяется сетка холста. Поэтому необязательный аргумент для create и --label для duplicate сохраняют долговечную метку моста в данных плагина; inspect сообщает как собственное name, так и стабильную label. Ссылки разрешаются по идентификатору, точному собственному имени или метке, затем по уникальной подстроке. Неоднозначность является ошибкой, удаление всегда требует явной ссылки, а дублирование/перемещение отказываются от несуществующей целевой строки, а не принимают резервное размещение Figma. Каждая операция проверяет figma.editorType === "slides" перед тем, как коснуться API, предназначенного только для слайдов. Открытые кандидаты и критерии выхода из бета-версии находятся в docs/slides-roadmap.md; принятие редактором проверяется сопровождающими отдельно от публичного репозитория.

Синхронизация токенов (двусторонняя)

tokens import только создает, поэтому значение, отредактированное в коде, никогда не достигает существующей переменной Figma, а значение, отредактированное в Figma, никогда не достигает кода. tokens sync замыкает этот цикл:

figma_run ["tokens", "sync", "src/tokens.json"]              # plan only
figma_run ["tokens", "sync", "src/tokens.json", "--apply"]   # write it

Поверхность импорта шире, чем поверхность синхронизации. Одноразовый import принимает конфигурацию Tailwind v3, Tailwind v4/CSS, индексы Storybook, JSON DTCG/W3C и совместимые с DTCG формы токенов, экспортируемые Style Dictionary и Tokens Studio. Эта совместимость не включает семантику тем Tokens Studio или произвольные препроцессоры; метаданные, такие как $themes, игнорируются, в то время как наборы токенов и псевдонимы читаются.

Новые переменные FLOAT в явных пространствах имен spacing/* или space/* ограничены только потребителями GAP Figma. Переменные radius/* и radii/* ограничены только CORNER_RADIUS. Вывод намеренно точен для пространства имен: имена, такие как spacingFactor, оставляются в области видимости Figma по умолчанию, и рендеринг молча не изменяет области видимости существующих пользовательских или библиотечных переменных. Другие новые переменные COLOR, FLOAT или STRING отображают ТРЕБУЕТСЯ ОПРЕДЕЛЕНИЕ ОБЛАСТИ ВИДИМОСТИ только с совместимыми вариантами Figma. Агент должен спросить перед их сужением; проверьте каталог с помощью figma_reference {name:"variable-scopes"} и примените ответ с помощью figma_run ["var","update","<name>","--collection", "<collection>","--scopes","TEXT_FILL,STROKE_COLOR"].

Безопасная трехсторонняя синхронизация принимает только токены дизайна DTCG / W3C (.json, то, что выдает export dtcg) и CSS-кастомные свойства (.css, то, что выдает export css). Переменные Sass $variables не являются CSS-кастомными свойствами, и .scss отклоняется, а не частично анализируется. Обратите внимание, что export dtcg записывает все локальные переменные в один файл, в то время как синхронизация нацелена на одну коллекцию — передайте --collection соответствующим образом. Если большинство имен в файле уже находятся в другой коллекции, синхронизация сообщит об этом, вместо того чтобы предлагать их дублировать. Конфигурации Tailwind являются только источником импорта — их парсер группирует значения по цвету/интервалу/радиусу и не может обеспечить обратное преобразование, поэтому синхронизация отклоняет их по имени, а не молча отбрасывает токены, которые она не поняла.

Зачем нужен файл блокировки. Двусторонняя синхронизация без памяти не может отличить "код изменился" от "Figma изменилась" — она видит только, что они различаются, и какое бы направление она ни выбрала, оно уничтожает работу другой стороны. figma-tokens.lock.json записывает состояние на момент последней успешной синхронизации, поэтому каждое решение является трехсторонним сравнением:

Конфликты останавливают весь запуск. Разрешите их, отредактировав одну сторону, или решите все сразу с помощью --ours (побеждает файл кода) / --theirs (побеждает Figma, и в Figma ничего не записывается).

Удаления требуют --prune, и даже в этом случае затрагивают только переменные, созданные самой синхронизацией — переменная, которую она никогда не отслеживала, сообщается как неотслеживаемая и оставляется в покое.

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

Без --apply команда завершается с кодом 1, если ожидают изменения, поэтому она работает как CI-проверка "синхронизирована ли Figma с репозиторием?".

Привязка и переключение коллекции, которой следует дизайн

tokens sync записывает значения токенов. Две смежные вещи, которые он намеренно не делает:

figma_run ["node", "bind", "12:34", "radius", "radius/lg", "--collection", "TARGET_COLLECTION"]
figma_run ["tokens", "rebind", "TARGET_COLLECTION", "--node", "12:34"]            # plan
figma_run ["tokens", "rebind", "TARGET_COLLECTION", "--node", "12:34", "--apply"] # write

node bind прикрепляет переменную к свойству существующего узла — fill, stroke, radius, gap, padding (или одна сторона), opacity, stroke-width, width, height. Его аналог для чтения — node bindings. Передайте --batch с массивом JSON, чтобы привязать множество свойств или узлов за один вызов.

Имя переменной, которое не является уникальным, отклоняется, а не угадывается — в этом файле есть radius/lg в двух коллекциях, и ответ называет обе, чтобы --collection мог решить. Тип переменной сначала проверяется на соответствие свойству, так что COLOR для radius завершается ошибкой с предложением, а не стеком вызовов плагина.

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

figma_run ["font", "bind", "12:36", "fontWeight", "type/weight", "--collection", "Typography"]
figma_run ["font", "bind", "12:36", "line-height", "type/line-height", "--start", "0", "--end", "12"]
figma_run ["font", "unbind", "12:36", "lineHeight", "--start", "0", "--end", "12"]

Связываемые поля: fontFamily, fontSize, fontStyle, fontWeight, letterSpacing, lineHeight, paragraphSpacing и paragraphIndent; допускается также написание в kebab-case. Существующие шрифты — а для связей family/style/weight соответствующие доступные стили семейства — загружаются до изменения связи. Имена переменных отклоняются при неоднозначности, а STRING vs FLOAT проверяется перед вызовом Figma. Числовая привязка fontWeight по-прежнему не является универсальным задавателем вариативных осей шрифта: Figma выбирает допустимый вес для активного шрифта.

tokens rebind — это переключение темы: он обходит поддерево и перенаправляет каждую привязку на одноимённую переменную в целевой коллекции. Создайте карточку против SOURCE_COLLECTION, запустите rebind с TARGET_COLLECTION, и та же карточка будет следовать значениям целевой коллекции — без перепроектирования. По умолчанию работает в режиме планирования; --apply выполняет запись. Токены, не имеющие аналога в целевой коллекции, перечисляются и остаются указанными туда, где были, так что частичная тема — это отчёт, а не наполовину сломанный дизайн.

node set изменяет свойства уже существующих узлов: fill, stroke, strokeWidth, radius, opacity, x, y, width/height, name, visible — по одному узлу или сразу многим через --batch, что важно, потому что пакетная форма — это один round-trip:

figma_run ["node", "set", "12:34", "--name", "Card", "--radius", "12"]
figma_run ["node", "set", "--batch", "[{\"node\":\"12:35\",\"fill\":\"var:sage/50\",\"name\":\"Badge\"}]"]

Цвет принимает hex или var:<name>. Различие не косметическое: hex заморожен, а ссылка var: остаётся связанной, так что позже tokens rebind всё ещё может её переместить.

Локальные стили, метаданные переменных и режимы

Локальные примитивы дизайн-системы, для которых раньше требовалась ручная работа в UI, теперь имеют первоклассные команды Figma. Они используют живой Plugin API, а не REST:

figma_run ["style", "list", "--type", "TEXT"]
figma_run ["style", "show", "Heading/H1"]
figma_run ["style", "create", "PAINT", "Brand/Primary", "--properties", "{\"paints\":[{\"type\":\"SOLID\",\"color\":{\"r\":0.1,\"g\":0.3,\"b\":0.9}}]}"]
figma_run ["style", "apply", "Brand/Primary", "12:34,12:35", "--field", "fill"]
figma_run ["style", "consumers", "Brand/Primary"]
figma_run ["style", "publish-status", "Brand/Primary"]
figma_run ["style", "bind-font", "Body", "fontSize", "--variable", "type/size/body"]
figma_run ["style", "unbind-font", "Body", "fontSize"]

style охватывает локальные стили PAINT, TEXT, EFFECT и GRID. update принимает те же типоспецифичные JSON-свойства, что и create; apply проверяет тип стиля на соответствие fill, stroke, text, effect или grid. Поиск по имени отклоняет неоднозначность. Потребители получаются из getStyleConsumersAsync(), а статус публикации — одно из значений Figma: UNPUBLISHED, CURRENT или CHANGED.

Переменные предоставляют операции с метаданными и режимами, которые не относятся к синхронизации файлов токенов:

figma_run ["var", "show", "space/md", "--collection", "Primitives"]
figma_run ["var", "update", "space/md", "--description", "Medium spacing", "--scopes", "GAP"]
figma_run ["var", "set-value", "space/md", "12", "--mode", "Light"]
figma_run ["var", "set-value", "space/card", "--alias", "space/md", "--mode", "Light"]
figma_run ["var", "code-syntax", "space/md", "WEB", "var(--space-md)"]
figma_run ["var", "resolve", "space/md", "12:34"]
figma_run ["col", "mode-add", "Primitives", "Dark"]
figma_run ["col", "mode-rename", "Primitives", "Dark", "Dim"]
figma_run ["col", "extend", "Primitives", "Brand"]

var show возвращает значения по режимам, области видимости, синтаксис кода, метаданные коллекции и статус публикации. var resolve намеренно требует узел- потребитель, потому что псевдонимы могут разрешаться по-разному в зависимости от выбранных режимов этого узла. show, update, mode-add, mode-rename, mode-remove и publish-status для коллекции следуют той же политике поиска по ID/точному имени/уникальной подстроке. Ограничения Figma на количество режимов остаются под контролем Figma и отображаются как ошибки. Расширения коллекций используют VariableCollection.extend() для локальных коллекций и extendLibraryCollectionByKeyAsync() для опубликованных ключей. Figma ограничивает эту возможность корпоративными тарифами; CLI сообщает об ошибке тарифа Figma без изменений. Привязки текстовых стилей поддерживают именно те поля типографики, которые Figma позволяет связывать: семейство, начертание, вес, размер, межстрочный интервал, межбуквенный интервал и значения абзаца.

Включённые командные библиотеки

Обнаружение библиотек и импорт также остаются на аутентифицированном транспорте плагина:

figma_run ["library", "collections"]
figma_run ["library", "variables", "Acme/Primitives", "--type", "COLOR"]
figma_run ["library", "import-variable", "<published-variable-key>"]
figma_run ["library", "import-style", "<published-style-key>"]
figma_run ["library", "import-component", "<published-component-key>"]
figma_run ["library", "import-component-set", "<published-component-set-key>"]

collections и variables — это чтения. Четыре команды import-* материализуют опубликованные активы в текущем файле и поэтому являются записями в Каталоге возможностей. Figma предоставляет возможность обнаружения только для коллекций переменных и самих переменных. Опубликованные стили, компоненты и наборы компонентов можно импортировать, если их стабильный ключ уже известен, но Plugin API не может их перечислить.

Библиотеки должны быть включены для текущего файла в UI Figma, прежде чем library collections сможет их увидеть; Plugin API не может включить библиотеку. Поставляемый плагин уже объявляет необходимое разрешение teamlibrary. Поиск по имени использует ключ коллекции, точное имя коллекции, затем однозначную подстроку имени коллекции или библиотеки. Обнаружение библиотек имеет собственный тайм-аут Plugin API в 18 секунд до дедлайна Bridge, поэтому зависший запрос библиотеки Figma называет операцию и предлагает проверить, включена ли библиотека, вместо того чтобы вырождаться в общий тайм-аут выполнения.

Прототипы, измерения в режиме разработки и аннотации

Эти функции документов также в первую очередь используют Plugin API:

figma_run ["prototype", "inspect", "12:34"]
figma_run ["prototype", "add", "12:34", "--trigger", "click", "--navigate-to", "12:36"]
figma_run ["prototype", "set", "12:34", "--json", "[{\"trigger\":{\"type\":\"ON_CLICK\"},\"actions\":[{\"type\":\"BACK\"}]}]"]
figma_run ["measure", "add", "12:34:right", "12:36:left", "--offset", "16", "--text", "gap"]
figma_run ["annotate", "categories"]
figma_run ["annotate", "add", "Review spacing", "--node", "12:34", "--category", "Review", "--properties", "width,fontSize"]
figma_run ["annotate", "edit", "12:34", "0", "--text", "Resolved"]

prototype set --json — это форма без потерь для множественных действий Figma: SET_VARIABLE, SET_VARIABLE_MODE и условных блоков. Она записывает через setReactionsAsync(), так что поддерживаются манифесты динамических страниц. Запись измерений защищена для режима разработки Figma и использует собственные методы измерений PageNode. Индексы аннотаций начинаются с нуля; команды создания/редактирования/удаления пользовательских категорий доступны вместе с categories. Эти заметки для ручной проверки независимы от автоматических аннотаций граничных отказов семантического рендерера, которые создаются только при явно включённых политиках отображения с потерями и остаются машиночитаемыми через данные плагина.

Plugin API 2026: видео, шейдеры, сетки, слоты и Draw

Текущая официальная поверхность Plugin API представлена как команды Figma, а не вызовы REST:

figma_run ["export", "video", "12:34", "--format", "mp4", "--fps", "30", "-o", "/abs/demo.mp4"]
figma_run ["shader", "list"]
figma_run ["shader", "import", "<shader-id>"]
figma_run ["shader", "apply", "12:34", "<shader-id>", "--field", "fill", "--properties", "{\"definition-id\":0.8}"]
figma_run ["layout", "grid", "set", "12:34", "--rows", "2", "--columns", "3", "--row-gap", "12"]
figma_run ["layout", "grid", "auto-flow", "12:34", "--auto-tracks", "rows", "--positioning", "row_auto_flow"]
figma_run ["slot", "create", "12:37", "Content", "--settings", "{\"minChildren\":1,\"maxChildren\":3}"]
figma_run ["slot", "validate", "12:37"]
figma_run ["draw", "inspect", "12:38"]
figma_run ["draw", "text-path", "12:38", "--text", "Around the curve"]
figma_run ["draw", "stroke-profile", "12:38", "--preset", "TAPER"]
figma_run ["draw", "pattern", "12:38", "12:39", "--field", "fill"]

Экспорт видео разрешает выбранный потомок в его верхний анимированный кадр и принимает только зависящие от формата значения FPS Figma. Свойства шейдеров ключуются по ID определения, а не по отображаемому имени, и доступный шейдер должен быть импортирован до его применения. layout grid означает модель автоматической раскладки GRID; более старая команда верхнего уровня grid остаётся управлением направляющими раскладки. Слоты предоставляют GA SlotSettings, предпочтительные значения, сброс и нарушения лимитов; JSX <Slot> теперь использует ComponentNode.createSlot() и проверяет настроенные лимиты после рендеринга. Команды Draw охватывают текстовые пути, группы повторяющихся трансформаций, растянутые/разбросанные/динамические обводки, профили переменной ширины и асинхронные задатчики заливки/обводки паттернов. Запускайте соответствующие чтения inspect/validate перед записью при изменении незнакомого документа.

Поиск того, что нужно исправить

figma_run ["analyze", "lint", "--node", "12:34"]

Один проход для четырёх вещей, на которые обращает внимание проверка дизайн- системы: цвета, совпадающие с существующей переменной, но не привязанные к ней; слои, всё ещё носящие имя по умолчанию; текст без стиля; текст менее 12px. --fail-on-issues делает это шлюзом CI; --kind сужает; --json никогда не обрезает.

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

unbound token colour — 1
  12:35    Badge  fill is #8a9a8d, which is sage/400
    fix: node bind 12:35 fill "sage/400" --collection "Sprout Primitives"

analyze colors|typography|spacing по-прежнему дают полную перепись. Линтинг — это проход, который отвечает, нужно ли вообще что-то делать.

Вариативные шрифты и факты OpenType

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

figma_run ["font", "inspect", "12:36"]
figma_run ["font", "inspect", "12:36", "--start", "0", "--end", "12", "--all-open-type"]

font inspect возвращает стилизованные текстовые диапазоны с fontName, числовым только для чтения fontWeight, размером, включёнными тегами функций OpenType и разрешёнными привязками переменных типографики. --all-open-type также включает ложные значения функций. Результат явно называет ограничение API: сообщаемый fontWeight не является общим кортежем wght/wdth/opsz/пользовательских осей, а функции OpenType доступны только для чтения.

Когда точные значения осей известны из UI или другого шрифтового инструмента, сохраните их на текстовом узле как метаданные диапазона:

figma_run ["font", "remember-axes", "12:36", "wght=357,wdth=82", "--start", "0", "--end", "12"]
figma_run ["font", "axes", "12:36"]
figma_run ["font", "forget-axes", "12:36", "--start", "0", "--end", "12"]
figma_run ["font", "forget-axes", "12:36"]  # clear every stored range

remember-axes изменяет только метаданные плагина — никогда не шрифт или отображаемые глифы — и поэтому классифицируется как запись Каталогом возможностей. figma_spec несёт эти записи как axes-meta[start:end](tag=value,…), плюс сообщаемое Figma значение fw… и включённые теги ot(…), чтобы захват дизайна в код не отбрасывал молча задокументированное намерение.

Факты нативного Plugin API

Две команды чтения предоставляют собственные представления Figma без обращения к REST API:

figma_run ["node", "css", "12:34"]
figma_run ["node", "css", "12:34", "--json"]
figma_run ["export", "node-json", "12:34"]
figma_run ["export", "node-json", "12:34", "-o", "facts/card.json"]

node css вызывает getCSSAsync() и возвращает объявления, которые Figma предоставляет для своей панели Inspect. Это намеренно отделено от export css, который экспортирует пользовательские свойства токенов дизайна. export node-json использует exportAsync({format:"JSON_REST_V1"}): форма напоминает схему файла REST, но байты берутся из живого документа плагина и не требуют ни токена, ни сетевого запроса.

История версий и различия

Plugin API Figma может записать версию, но не прочитать её обратно, поэтому «что изменилось с утра» не имеет ответа от одного лишь моста. history предоставляет его без каких-либо учётных данных: записать структуру поддерева, записать её снова позже, сравнить две.

figma_run ["history", "save", "Before refactor", "--description", "Agent restore point"]
figma_run ["history", "snapshot", "--label", "before refactor"]
# … agent works …
figma_run ["history", "diff", "latest", "live"]

history save создаёт именованную запись напрямую через saveVersionHistoryAsync() и является записью Figma. snapshot, list и diff остаются локальными/только для чтения операциями Figma; чтение собственных исторических версий Figma по-прежнему требует дополнительного REST-дополнения.

Снимок хранит одну нормализованную запись на узел — геометрия, раскладка, заливки, типографика, ключи компонентов — плюс хеш содержимого и хеш поддерева, чтобы программа сравнения могла сообщить о нетронутом разделе, вместо того чтобы обходить его. Они хранятся в ~/.figma-bridge-mcp/snapshots/<fileKey>/, сжатые gzip, хранятся последние 20.

Ссылки: latest, previous, индекс из history list, имя файла или live для текущего документа. Отчёт разделяет добавленные, удалённые, заменённые, перемещённые и изменённые — это последнее различие — то, что важно на практике: агент, который удаляет фрейм и перерисовывает его, сохраняет путь имени, но получает новые ID узлов, и без обнаружения замены каждый перерендер будет восприниматься как сотня удалений. --changelog выводит markdown вместо этого; diff завершается с кодом 1, если что-то отличается, так что он также работает как шлюз CI.

Через MCP это параметр, а не тринадцатый инструмент:

figma_history {diff: {from: "latest", to: "live"}}
figma_history {diff: {from: "version:1234", to: "version:5678"}}   # REST add-on

Ссылки version: проходят через REST-слой и сравнивают то, что сохранили дизайнеры, используя ту же программу сравнения. Два источника нельзя смешивать в одном сравнении: REST-документ и снимок плагина предоставляют разные свойства, поэтому каждый узел выглядел бы изменённым — инструмент сообщает об этом, вместо того чтобы выдавать вводящий в заблуждение объём вывода.

Motion

Figma Motion (бета Config 2026) доступен через figma_run с ["motion", …]: треки ключевых кадров (add), полные спецификации из JSON (apply), именованные пресеты (preset), хореографированные смещения между узлами (stagger), встроенные стили анимации Figma (styles, style), длительность кадра (timeline), чтение (inspect) и удаление (clear).

Как и любая другая команда, она выполняется через мост плагина — отдельного транспорта для неё нет. styles и inspect — чтения; всё остальное, включая timeline (он читает или устанавливает в зависимости от аргументов), считается записью при FIGMA_WRITE_CONFIRM=1.

Motion разворачивается за бета-флагом Figma. Без доступа команды завершаются с именованной ошибкой MOTION_DISABLED, сообщающей, что нужно обновить Figma Desktop, а не с общей ошибкой API.

REST-дополнение (опционально)

Всё вышеперечисленное работает без учётных данных Figma. Три вещи, которые локальный мост плагина структурно не может достичь, находятся за REST API Figma и могут быть разблокированы с помощью персонального токена доступа:

Включение — токен никогда не покидает ваш компьютер:

1. Создайте персональный токен доступа в Figma (Настройки → Безопасность → Персональные токены доступа) с областями: Содержимое файла (чтение), Версии файлов (чтение), Комментарии (чтение и запись). Текущий пользователь (чтение) опционален — он нужен только для того, чтобы figma_status показывал ваш логин.

2. Откройте плагин Figma Bridge в Figma Desktop, подключитесь (поле появляется после аутентификации плагина) и разверните «REST токен (опционально)». Вставьте токен, нажмите Save token.

3. figma_status сообщает, что токен настроен, без отправки удаленного запроса. Выполните figma_status {validateRest:true}, когда захотите явно проверить валидность; он сообщит ваш логин или проверит доступ к файлу, если опциональная область Текущий пользователь отсутствует.

Токен передается из плагина через аутентифицированный localhost WebSocket демону, который сохраняет его в ~/.figma-bridge-mcp/rest-token (режим 0600). Он никогда не вводится в чат, не хранится в конфигурации вашего MCP-клиента, не возвращается никаким инструментом и не попадает в журнал аудита (REST-вызовы логируются только как метод + путь). Кнопка Clear token в плагине удаляет файл.

Альтернатива для CI/окружений без графического интерфейса: установите переменную окружения FIGMA_REST_TOKEN — она имеет приоритет над файлом.

Область действия: по умолчанию REST-вызовы нацелены на файл, который в данный момент открыт в Figma Desktop (плагин передает его ключ). Для других файлов требуется явный параметр fileKey (просто ключ или полный URL Figma). Обратите внимание, что сам PAT может читать любой файл, к которому имеет доступ учетная запись — поэтому сводите области к минимуму.

REST-клиент представляет собой закрытый внутренний белый список, а не универсальное средство для HTTP-запросов. Он разрешает проверку здоровья токена, списки версий, содержимое документов, привязанное к версии, комментарии и метаданные опубликованных компонентов в рамках всего файла. Запросы на получение текущего файла без указания версии, а также все конечные точки для узлов/CSS/экспорта/переменных/стилей/Dev-Resource отклоняются до того, как будет прочитан токен или выполнен сетевой запрос; эти операции должны использовать команды локального API плагина, описанные выше.

Модель безопасности

• API-токен Figma не требуется — Figma управляется через локальный плагин, никогда не через api.figma.com. REST-дополнение является строго опциональным: без токена этот код пути инертен, а с токеном он хранится в файле с режимом 0600 (или в вашей собственной переменной окружения), а не в конфигурации MCP-клиента.

• Без модификации бинарных файлов — Режимы Yolo/CDP удалены из vendored-движка.

• Команды, ограниченные возможностями — figma_run принимает только Команды, доступные в Каталоге Возможностей; connect не доступен, поэтому принудительно применяется только режим Safe-Mode. Тот же самый разрешенный план управляет шлюзом подтверждения записи, требованиями к цели и политикой повторных попыток, предотвращая расхождение адаптера.

• Нет оболочки — движок запускается с помощью execFile (shell:false).

• Двухуровневая аутентификация демона, никаких секретов в сети — подписанные HTTP-запросы (HMAC для каждого запроса по методу/пути/телу, с использованием ключа сессии, защита от повторного использования nonce) + взаимное подтверждение вызов-ответ на сокете плагина (белый список Origin/Host). Ни токен сессии, ни ключ доступа никогда не передаются ни в одном направлении — см. Рукопожатие.

• Плагин, заблокированный на localhost — plugin/manifest.json ограничивает networkAccess.allowedDomains до ws://127.0.0.1:3456–3460.

• Изолированное состояние — токен, pid, ключ и журнал аудита находятся в ~/.figma-bridge-mcp/, отдельно от любой установки вышестоящего figma-ds-cli.

• Журнал аудита — каждая выполненная команда добавляется в ~/.figma-bridge-mcp/audit.log (с id затронутых узлов, опциональными метками и записью о завершении, фиксирующей успех/неудачу — источник данных для figma_history). Ротируется при достижении 5 МБ; сохраняется одна предыдущая генерация (audit.log.1), которая все еще читается командой figma_history.

Резервный порт. Демон привязывается к первому свободному порту в диапазоне 3456–3460 и публикует его в ~/.figma-bridge-mcp/daemon-port; слои CLI/MCP определяют порт при каждом вызове (переменная DAEMON_PORT > файл порта > 3456), а плагин сканирует весь диапазон, поэтому внешний процесс, занявший порт 3456, больше не блокирует подключение. Проверка занятости — это неаутентифицированный зонд /health, а аутентифицированные запросы подписываются HMAC — занявший порт в диапазоне не видит ни токена сессии, ни чего-либо, что можно было бы воспроизвести (подписи привязывают временную метку, nonce, метод, путь и тело; демон отклоняет повторно использованные nonce). Сокет плагина безопасен на любом порту диапазона по той же причине: рукопожатие ниже не переносит секретов и привязывается к порту, на котором оно было выполнено. Явная установка DAEMON_PORT отключает резервный механизм; значения вне диапазона 3456–3460 не поддерживаются — манифест плагина обеспечивается Figma и не может до них добраться.

Рукопожатие

Сокет плагина выполняет взаимный вызов-ответ (протокол 2, engine/src/lib/plugin-handshake.js):

daemon → plugin   {type:'challenge', proto:2, nonce:<dNonce>, port:<bound>}
plugin → daemon   {type:'hello', proto:2, nonce:<pNonce>, version, proof}
daemon → plugin   {type:'hello-ack', proof, restTokenConfigured}

где proof = HMAC-SHA256(access key, transcript) по обоим nonce, привязанному порту и версии плагина — с разными ролевыми метками и порядком nonce для каждого направления, так что ни одно доказательство не может быть воспроизведено как другое. Отсюда следуют три свойства:

• Ключ никогда не передается по сети. Процесс, который занимает порт из диапазона до демона и записывает весь обмен, узнает один HMAC по nonce, которые он больше никогда не увидит. Это устраняет остаточный риск, описанный в более ранних версиях, где сырой ключ был первым кадром, отправленным плагином.

• Демон тоже доказывает свою личность. До протокола 2 плагин доверял любому, кто отвечал, и выполнял любой отправленный ему eval — для выдачи себя за демона вообще не требовался ключ. Панель теперь отказывается от любой команды до тех пор, пока подтверждение не будет проверено.

• Привязанный порт находится внутри транскрипта. Занявший порт 3456 процесс, который перенаправляет на реальный демон на порту 3457, заставляет плагин подписать 3456, в то время как демон проверяет 3457, поэтому ретрансляция рушится.

Отката к протоколу 1 нет. figma_connect обновляет установленные файлы плагина при каждом запуске, поэтому обновление происходит так: запустите figma_connect, затем закройте и снова откройте окно плагина — устаревшая панель получит именованную ошибку, сообщающую именно об этом, вместо молча более слабого рукопожатия.

Панель содержит свою собственную реализацию SHA-256/HMAC: пользовательский интерфейс плагина — это изолированный iframe с нулевым источником, где доступность WebCrypto не гарантируется нами, а молчаливый откат к чему-то более слабому — худший результат для аутентификационного рукопожатия. tests/plugin-handshake.test.js запускает этот поставляемый код против Node.js crypto, чтобы две реализации не могли разойтись.

Известные ограничения

• Figma Slides находится в бета-версии и намеренно ограничена. Проверка сетки, создание/дублирование/перемещение/удаление слайдов, состояние пропуска и переходы поддерживаются. Заметки докладчика, интерактивные опросы/встраивания, элементы управления презентацией и полноценный рабочий процесс создания контента — нет. Смотрите дорожную карту Slides для реализуемых кандидатов в сравнении с границами API плагина.

• Сетевые действия не на localhost немногочисленны и явны: api setup (однократное клонирование git зеркала документации Figma Plugin API для figma_reference; api gap вместо этого сравнивает с установленным официальным пакетом @figma/plugin-typings), получение индекса Storybook для import/map storybook (URL/каталог, который вы передаете), и — только если вы включили REST дополнение — вызовы api.figma.com. Ничто другое не работает с сетью — интеграции вышестоящего проекта с iconify/unsplash/remove.bg/screenshot-url были полностью удалены; <Icon> в JSX figma_render отображается как именованный плейсхолдер (настоящие иконки берутся из файла Figma через export assets).

• Один транспорт, никаких остатков CDP. Каждая команда достигает Figma одним и тем же способом: движок → демон → eval плагина. Клиент Chrome-DevTools вышестоящего проекта, его обход через оболочку figma-use, мастер установки с модификацией бинарных файлов init и зависимость figma-use — все удалено (~5600 строк удалено), поэтому нет второго пути выполнения, который мог бы обойти мост плагина.

Разработка

npm run check:contracts       # static JavaScript seam + plugin contracts
npm run check:architecture-latency # warmed latency budget in an idle process
npm run measure:architecture  # context, payload and local latency baselines
npm test                      # all contracts and regression suites

Текущий предметно-ориентированный язык находится в CONTEXT.md, принятые архитектурные решения — в docs/adr/, покрытие API — в docs/figma-plugin-api-coverage.md, а инструкции по релизу — в docs/releasing.md. Индекс публичной документации — docs/README.md.

Избегайте одновременного запуска вышестоящего figma-cli. Демон теперь использует резервный порт в диапазоне 3456–3460, когда порт 3456 занят, поэтому оба могут сосуществовать, но плагин сканирует весь диапазон, а два демона используют разные ключи доступа — какой из них плагин найдет первым, зависит от случая. Эта сборка изолирует свои собственные файлы токена/pid/порта в ~/.figma-bridge-mcp/.

Лицензия

figma-bridge-mcp распространяется под лицензией MIT. Он предоставляется «как есть», без каких-либо гарантий; точные условия гарантии и ответственности содержатся в самой лицензии. Уведомления об авторских правах и лицензиях третьих сторон сохранены в NOTICE и engine/LICENSE.

Вдохновение и атрибуция

Два проекта сформировали этот, каждый по-своему.

figma-cli (Sil Bormüller) — это тот проект, из которого происходит каталог engine/: он был включен в версию v2.1.0 в июле 2026 года и с тех пор разошелся — транспорт CDP и установщик с изменением бинарных файлов удалены, сокет плагина аутентифицирован, и большая часть того, что сейчас делает движок, была написана здесь. Четыре файла остались побайтово идентичными вышестоящему проекту. Вышестоящая лицензия MIT полностью сохранена в engine/LICENSE, а в NOTICE зафиксировано, что было изменено.

figma-console-mcp внесла идею, а не код: что мост Figma может быть действительно локальным — сокет плагина на интерфейсе обратной петли, без облачной ретрансляции, без модифицированного бинарного файла. Ничто здесь не является производным от его исходного кода; поверхности инструментов, транспорт и плагин не связаны между собой. Отличие этого проекта в том, что сокет также доказывает, кто находится на другом его конце.

Идентификация плагина. Манифесты для разработки используют идентификаторы, соответствующие продукту: figma-bridge-mcp и figma-bridge-mcp-dev. Figma привязывает clientStorage — где хранится сопряженный ключ доступа — к идентификатору плагина. Поэтому установкам, сделанным до версии 0.5.0, необходимо повторно импортировать манифест и один раз вставить существующий ключ доступа Bridge.