Figma MCP + Claude Code: как AI читает твой файл и пишет код без потерь

Дизайнер передаёт Figma-файл разработчику. Через неделю смотрит на собранный экран и не узнаёт его. Отступы плывут, цвета почти те, но не те, иконки заменены на ближайшие из библиотеки, состояния кнопок собраны на глазок. Никто не виноват: разработчик честно смотрел в макет, дизайнер честно его нарисовал. Просто между ними — толстый слой ручной интерпретации.

Figma MCP пытается этот слой убрать. Идея простая: Claude Code (или другой агент) подключается к Figma напрямую через Model Context Protocol, читает структуру файла как данные, а не как картинку, и генерирует код по реальным токенам, а не по приблизительному «вижу синюю кнопку». На бумаге звучит как «дизайн → код в один клик». На практике это новый рабочий процесс, в котором ломаться есть чему — просто ломается оно теперь в других местах.

## Что вообще такое Figma MCP

MCP — это протокол, через который AI-агент получает доступ к внешнему источнику данных в структурированном виде. Не скриншот, не экспорт в PNG, не Dev Mode-ссылка для глаз — а дерево слоёв, компонентов, переменных, авто-лэйаута, со всеми именами и связями.

Для Claude Code это значит примерно следующее. Ты говоришь: «собери компонент карточки товара из фрейма Product Card на странице Catalog». Агент идёт в файл, находит нужный фрейм, видит, что внутри лежит инстанс компонента Button с вариантом primary/medium, токен цвета bg/surface/raised, отступы 12/16, типографика text/body/m. И генерирует JSX (или Vue, или SwiftUI) уже с этими именами — если в проекте подключены те же токены.

Ключевой сдвиг здесь не «AI пишет код». AI и так пишет код. Сдвиг в том, что AI больше не угадывает дизайн — он его читает.

## Почему это важно прямо сейчас

Раньше связка «Figma → код» держалась на двух костылях: Dev Mode для людей и плагины-генераторы для машин. Оба упирались в одно: они работали с визуальным результатом, а не с намерением.

• Dev Mode показывает CSS, но не знает, что этот padding — токен space/16, а не магическое число.
• Плагины-генераторы выдают div-суп, в котором нельзя найти ни компонент из вашей системы, ни ваш <Button>.
• LLM по скриншоту галлюцинирует имена классов и придумывает hex-коды, близкие к настоящим.

MCP-связка решает не «как нарисовать кнопку», а «как переиспользовать уже существующую кнопку из кодовой базы под имена из дизайн-системы». Это уже не про скорость прототипа. Это про то, что фронтенд и дизайн перестают расходиться.

И поэтому тема не про «потрогать новую игрушку». Команды, у которых дизайн-система живёт в двух параллельных вселенных — токены в Figma и переменные в коде — получают шанс свести их в одну. Те, у кого не живёт нигде, получат через MCP зеркало: агент очень быстро покажет, что система существует только на словах.

## Когда это реально помогает, а когда нет

MCP-агент — не универсальный конвертер макетов. У него есть зона, где он окупается мгновенно, и зона, где он создаёт больше работы, чем экономит.

### Где работает хорошо

• Сборка типовых экранов из готовых компонентов: списки, формы, карточки, настройки.
• Перенос экрана с одного брейкпоинта на другой, когда дизайнер сделал десктоп, а мобайл нужен «по логике».
• Обновление существующего кода под изменения в дизайне: поменялись отступы, токен, вариант — агент находит места и правит.
• Генерация Storybook-историй и состояний компонента по вариантам из Figma.

### Где ломается

• Кастомная анимация и сложные интеракции — в файле их нет как данных, агент додумает.
• Экраны, нарисованные «фрилансерски»: фреймы без авто-лэйаута, цвета хексами, текст оверрайдами поверх инстансов. Агент честно перенесёт этот хаос в код.
• Бизнес-логика и состояния данных: loading, empty, error — если их нет в макете, их не будет и в коде.
• Доступность: контрасты, фокус, ARIA — MCP не аудитор, он переводчик.

Правило большого пальца: чем дисциплинированнее файл в Figma, тем полезнее MCP. На грязном файле агент превращается в усилитель грязи.

### Чеклист готовности файла к MCP

• Все цвета, типографика и отступы — через переменные/токены, без хардкода.
• Компоненты собраны как компоненты, а не как группы слоёв.
• Авто-лэйаут везде, где есть структура; ручное позиционирование — только для иллюстраций.
• Имена слоёв и фреймов читаются: CardProduct, а не Frame 482.
• Варианты компонента покрывают реальные состояния, а не только «как на главной».
• Иконки — из единой библиотеки, с осмысленными именами.

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

## Рабочий процесс: от макета до пул-реквеста

Голая связка «MCP подключён, агент ходит в Figma» сама по себе ничего не даёт. Полезно она работает только внутри понятного цикла: дизайнер готовит фрейм, разработчик (или сам дизайнер) формулирует запрос, агент собирает код, человек ревьюит результат и возвращает правки в дизайн или в код. Без любого из этих шагов получается либо красивый мусор, либо бесконечная переписка с агентом.

### Шаг 1. Подготовка фрейма как «контракта»

Фрейм, который вы отдаёте агенту, — это техническое задание. Если в нём нет имён, токенов и состояний, ТЗ считается отсутствующим.

• Назовите фрейм так, как будет называться компонент в коде: OrderSummary, а не Order summary / final v3.
• Соберите внутри все состояния, которые нужны: default, hover, disabled, loading, empty, error. Что не нарисовано — того в коде не будет.
• Уберите из фрейма «черновые» слои: скрытые варианты, заметки, старые версии. Агент видит всё, включая то, что вы давно забыли спрятать.
• Проверьте, что инстансы компонентов — именно инстансы, а не разобранные копии.

### Шаг 2. Формулировка запроса

Запрос к агенту — это не «сделай красиво». Это короткое, плотное описание границ задачи.

Хороший шаблон выглядит примерно так: «Собери компонент X из фрейма Y на странице Z. Используй существующие компоненты из src/components/ui. Токены бери из src/styles/tokens.ts. Не трогай роутинг и состояния — только верстка и пропсы.»

Чем уже область, тем чище результат. «Собери весь экран чекаута» почти всегда хуже, чем три отдельных запроса по секциям.

### Шаг 3. Ревью результата

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

1. Подтянулись ли реальные токены и компоненты системы, или агент завёл новые.
2. Совпадает ли структура с фреймом: вложенность, авто-лэйаут, направления.
3. Названия пропсов и вариантов — близкие к тем, что приняты в кодовой базе.
4. Что агент додумал: классы, утилиты, обёртки, которых не было ни в дизайне, ни в проекте.

Последний пункт — самый коварный. Агенты любят добавлять «полезное»: лишние div-обёртки, ARIA-атрибуты наугад, неиспользуемые состояния. Это и есть тот самый шум, ради борьбы с которым всё затевалось.

## Диагностика: почему агент выдал не то

Когда результат явно мимо, проблема почти всегда в одном из четырёх мест. Сначала проверяйте файл, потом запрос, потом конфиг MCP, и только в последнюю очередь — модель.

### Симптом: вместо токенов — хексы и магические числа

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

### Симптом: компоненты из библиотеки игнорируются

Два частых корня. Либо в проекте не подключён список доступных компонентов (агент о них не знает), либо в Figma инстанс был разобран (detached) и агент видит набор слоёв, а не компонент. Проверьте оба.

### Симптом: «всё похоже, но не так»

Структура верстки выглядит нормально, но отступы плывут, а флекс ведёт себя странно. Почти всегда это отсутствующий или сломанный авто-лэйаут во фрейме. Агент попытался восстановить геометрию по координатам — и угадал не везде.

### Симптом: агент придумывает пропсы и варианты

Это значит, что варианты компонента в Figma либо не покрывают нужный кейс, либо названы так, что из них нельзя вывести смысл (Variant 2, state-new). Нормализуйте имена вариантов под те, что приняты в коде: size, tone, state.

## Анти-паттерны, которые ломают всё

• Просить агента «починить дизайн на лету»: добавить состояние, которого нет в макете. Состояния — это решение, а не верстка, их принимает человек.
• Генерировать сразу целый экран и коммитить без ревью. На третий раз вы найдёте в проекте три разных Button и два набора токенов.
• Держать в одном файле и продуктовые экраны, и исследовательские черновики без разделения. Агент рано или поздно вытащит черновик.
• Использовать MCP как замену дизайн-системе. Если системы нет, агент не создаст её за вас — он лишь зафиксирует её отсутствие в коде.
• Прятать от агента кодовую базу «чтобы не запутался». Наоборот: чем больше он видит существующие компоненты и токены, тем меньше выдумывает.

## Как дизайнеру встроить это в свою работу

MCP — это не «инструмент разработчика», к которому дизайнер не имеет отношения. Наоборот: качество того, что выдаёт агент, на 80% зависит от файла, который сделал дизайнер. Поэтому встраивать связку имеет смысл прежде всего в дизайнерскую рутину.

### В ежедневной работе над макетом

• Перед тем как отдать фрейм в разработку, прогоните его через агента сами. Не ради кода, а ради проверки: что агент не понял — то не поймёт и человек.
• Используйте генерацию как зеркало дизайн-системы. Если для одной кнопки агент достал три разных компонента — у вас в системе три разных кнопки, просто вы их не замечали.
• Сравнивайте сгенерированный JSX со своим фреймом по структуре. Расхождение почти всегда указывает на неаккуратный авто-лэйаут.

### Вопросы для ревью макета перед MCP

• Если бы я был агентом и видел только этот фрейм — понял бы я, что это за экран?
• Все ли значения здесь — ссылки на токены, а не локальные стили?
• Все ли состояния, которые нужны продукту, действительно нарисованы?
• Имена слоёв и вариантов — можно ли по ним догадаться, как это назвать в коде?
• Что в этом файле не должно попасть в продакшн — и убрано ли оно?

### Короткий итог сегмента

MCP не делает плохие файлы хорошими и не заменяет дизайн-систему. Он делает прозрачным то, что было размазано между Figma и кодом: где у вас порядок, а где договорённости только на словах. Дизайнер, который относится к фрейму как к контракту, получает на выходе предсказуемый код. Дизайнер, который относится к фрейму как к картинке, получает предсказуемый хаос — просто теперь сгенерированный быстрее.

## Продвинутые сценарии: где MCP реально вытягивает

Базовый кейс «фрейм → JSX» — это только вход. Связка начинает окупать себя там, где раньше уходили дни на синхронизацию дизайна и кода.

### Сценарий 1: миграция компонента через все экраны

В системе появилась новая версия Input — с другим состоянием ошибки и другой иконкой. В Figma это переключилось одним свойством компонента. В коде — нет: где-то старая разметка, где-то кастомные обёртки, где-то вообще копипаст.

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

### Сценарий 2: подъём дизайн-токенов из кода

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

На выходе — список «здесь должна быть переменная color.surface.muted, а стоит #F4F5F7». Дальше это правится в Figma руками, но видимость проблемы появилась.

### Сценарий 3: разбор макета от внешней команды

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

Не для того, чтобы сразу генерировать. Для того, чтобы понять, что вообще принесли.

### Сценарий 4: документация по факту

Агент умеет описывать то, что видит. Если в команде нет ресурса вести storybook руками, можно поставить его на роль документатора: по компоненту в Figma собрать список вариантов, состояний, примеров использования, и сложить рядом с кодом. Это не заменит вдумчивые гайдлайны, но закроет базовый слой «что вообще есть в системе».

## Как встроить это в командный процесс

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

### Минимальные правила в команде

• Сгенерированный код проходит то же ревью, что и написанный руками. Никаких «ну это же из Figma, должно быть ок».
• Источник истины фиксируется один раз и явно: либо Figma, либо код. Не «как получится».
• Названия компонентов и пропсов синхронизируются в обе стороны. Если в коде переименовали — в Figma тоже, и наоборот.
• Большие генерации (целые экраны) идут отдельным PR, а не подмешиваются к фиче.
• Если агент полез в чужую часть кодовой базы — это стоп-сигнал, а не «он сам разберётся».

### Роли вокруг связки

Полезно проговорить, кто за что отвечает, даже если команда маленькая.

• Дизайнер держит чистоту файла: токены, авто-лэйаут, имена, варианты.
• Фронтенд держит чистоту кода: какие компоненты считаются каноничными, какие пропсы существуют.
• Дизайн-системщик (если он есть) держит соответствие между этими двумя мирами.
• Агент — это четвёртый участник, у которого нет права голоса, но есть право задавать вопросы через расхождения, которые он подсвечивает.

## Как проверять качество результата

Самая частая ошибка — оценивать сгенерированный код по принципу «выглядит как макет — значит, ок». Это поверхностный слой. Под ним есть ещё три, и каждый ломается по-своему.

### Четыре слоя проверки

1. Визуальный. Совпадает ли пиксельно с фреймом на нужных брейкпоинтах. Самое простое и самое обманчивое: на этом слое баги маскируются.
2. Структурный. Использованы ли реальные компоненты из системы, а не свежесобранные дубликаты. Совпадают ли имена пропсов с принятыми в коде.
3. Семантический. Кнопка — это button, ссылка — a, заголовок — h2, а не три div со стилями. Это то, что почти всегда улетает первым.
4. Поведенческий. Состояния (hover, focus, disabled, loading, error) не нарисованы в Figma бесплатно — они должны быть либо в макете, либо проговорены в задаче. Если их нет, агент их додумает, и это станет багом в проде.

### Чеклист перед мерджем

• Нет ли в diff новых хексов и пиксельных значений, которым уже есть токен.
• Нет ли дубликата существующего компонента под новым именем.
• Состояния интерактивных элементов покрыты — не только default.
• Доступность не просела: контраст, фокус, семантика, alt-тексты.
• Адаптив проверен руками, а не «агент сказал, что работает».

## Как объяснить решение команде

Связка Figma MCP + агент звучит технологично, и поэтому её легко продать неправильно — как «теперь верстать будет AI». Это плохая рамка: она ставит команду в позу обороны и обещает экономию, которой не будет.

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

И ещё одна честная формулировка для стейкхолдеров: MCP делает дизайн-систему обязательной, а не желательной. Раньше можно было жить с локальными стилями и «договорённостями на словах» — медленно, но можно. Теперь любая такая неаккуратность мгновенно превращается в плохой код. Это не минус инструмента, это его главное свойство: он не прощает того, что и так не стоило прощать.

### Короткий итог сегмента

Продвинутые сценарии MCP — это не «генерация быстрее», а видимость расхождений между макетом и кодом. Командный процесс вокруг связки важнее самой связки: без договора об источнике истины и без честного ревью агент просто разгоняет существующий хаос. Проверяйте результат по всем четырём слоям, а не по картинке. И продавайте команде не «AI пишет код», а «мы наконец видим, где наша дизайн-система течёт».

## Большой чеклист: запуск связки в команде

Если вы только заводите Figma MCP + Claude Code в рабочий процесс, проще пройтись по списку один раз, чем потом разгребать последствия по PR-ам.

### Перед первым запуском

• В Figma выделен один файл (или одна страница) как источник для агента. Не «все наши макеты», а конкретный канон.
• В этом файле прибраны слои: убраны скрытые остатки, переименованы Frame 247, склеены дубли компонентов.
• Токены вынесены в переменные Figma, а не «лежат в шапке файла как примеры».
• В коде понятно, где живёт дизайн-система: один пакет, один путь импорта, без двух параллельных наборов кнопок.
• Договорились, какой агент имеет право трогать какие папки. Папка дизайн-системы — обычно read-only для генерации.

### Перед каждой задачей

• Сформулирован сценарий, а не «свёрстай этот фрейм». Что за экран, какие состояния, какие данные, что считается успехом.
• Указано, какие компоненты из системы должны быть использованы. Если в системе их нет — это отдельный разговор, а не повод плодить новые.
• Решено заранее: это PR с фичей или PR с новой версткой. Не смешиваем.

### Перед мерджем

• Прошлись по diff глазами, а не «тесты зелёные — мержим».
• Никаких новых хексов, размеров шрифта в пикселях, магических отступов.
• Состояния hover/focus/disabled/loading/empty/error видны в коде, даже если в макете их не было.
• Локализация не сломалась: длинные строки не ломают вёрстку, RTL не разваливается (если он поддерживается).
• Доступность: фокус-стили, контраст, семантика, навигация с клавиатуры.

## Анти-паттерны, на которые легко наступить

Большая часть проблем со связкой — это не баги инструментов, а привычки команды, которые до MCP были терпимыми, а теперь начинают резать.

### «Агент же видит макет, зачем писать тз»

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

### Один гигантский PR на весь раздел

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

### Дизайн-система как «папка с примерами»

Если в Figma Button / Primary и Button / Primary 2 живут рядом, агент будет тыкать в оба, иногда в один PR. То же в коде: два набора кнопок означают два набора багов и стабильное расхождение с макетом.

### Молчаливые правки токенов

Дизайнер меняет основной радиус с 8 на 10 «по-тихому». Агент честно подхватывает новое значение и катит через половину компонентов. Никто не заметил решения, но все увидели последствия. Любая правка токена — это анонс в канале, а не личное дело файла.

### «Агент сам разберётся с легаси»

В старом коде свои конвенции, которые никто уже не помнит. Агент не реверсит вашу историю — он подгоняет под то, что видит сверху. В легаси-части лучше работать руками или с очень узким скоупом.

### Подмена ревью прогоном линтера

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

## Вопросы для ревью PR от агента

Полезно держать этот список открытым в соседней вкладке, пока смотрите diff.

• Этот компонент уже существует в системе под другим именем?
• Все ли значения берутся из токенов, или где-то проскочил литерал?
• Имена пропсов совпадают с принятыми в кодовой базе, или агент придумал свои?
• Семантика разметки соответствует роли элемента, или это div с onClick?
• Какие состояния не покрыты, и почему их нет в макете?
• Если убрать этот PR, что-то сломается в другом месте? Нет ли скрытой связи?
• Этот код можно будет поддерживать без агента, или мы только что наняли его в штат навсегда?

Последний вопрос самый неудобный и самый полезный. Если ответ — «без агента уже не разберёмся», значит, генерация ушла глубже, чем должна.

## Практический итог

Figma MCP + Claude Code — это не способ верстать быстрее, а способ сделать видимым то, что раньше пряталось между дизайнером и разработчиком. Чистый файл превращается в чистый код почти даром. Грязный — в грязный код, только теперь с такой скоростью, что чинить вы будете дольше, чем писали бы руками.

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