Що насправді бачить Claude, коли ви даєте йому Figma-файл

💡 Усі статті, обговорення, новини про AI — в одному місці. Приєднуйтесь до AI спільноти!

Дисклеймер: усе, що описано в цій статті, — мій особистий досвід роботи з Figma MCP і Claude Code. Я не претендую на те, що це єдиний правильний підхід — це те, що працює для мене і для проєктів, у яких я брала участь. Ваш контекст може відрізнятися, і це нормально.

Останні кілька місяців я багато експериментую з Claude Code і Figma MCP — і помітила одну річ, про яку поки що мало хто говорить.

Усі обговорюють, як AI пише код за макетом. Як він «дивиться» Figma і генерує React. Як прискорює розробку. Але майже ніхто не говорить про те, що між макетом і кодом тепер з’явився новий проміжний шар — те, що бачить агент. І саме дизайнер відповідає за те, наскільки чітко цей шар описаний.

Розкажу історію. Кілька місяців тому я передавала розробнику фрейм із простою картковою секцією — три product cards у grid. Усе виглядало нормально, компоненти з нашої бібліотеки, інстанси, токени. Розробник прогнав через Claude Code. На виході отримали рендер, який майже збігався візуально — але в коді кнопки всередині карток були намальовані з нуля, а не використовували наш <Button>. Шість додаткових <button> тегів зі своїми стилями. Поряд із компонентом, який вже існував у бібліотеці.

Це сталося не тому, що Claude поганий. А тому, що я не дала йому достатньо контексту, щоб зрозуміти, що він бачить.

Ця стаття — про те, як готувати компоненти на трьох рівнях вкладеності (атом → молекула → секція), щоб AI читав їх однозначно. Без здогадок, без перемальовування, без створення дублікатів.

Що насправді «бачить» агент

Перш ніж говорити про підготовку, треба зрозуміти, з чим взагалі працює AI, коли ви даєте йому Figma-файл.

Через Figma MCP агент отримує структурований контекст: ієрархію фреймів, імена шарів, властивості компонентів, прив’язки до variables, auto layout, описи. Якщо все це заповнено — він читає ваш макет як код, із семантикою.

Якщо ні — він дивиться на геометрію. Бачить прямокутник із текстом усередині та заокругленням 8px і думає: «о, це схоже на кнопку». Далі генерує власну кнопку з нуля, з власними стилями, які приблизно схожі на ваші. Не використовує ваш <Button> із бібліотеки, тому що для нього там нічого не написано про те, що це — Button.

Я для себе сформулювала так: агент читає не пікселі, а намір. Якщо наміру у файлі немає — він його вигадає.

Що саме отримує агент через MCP

Корисно подивитися на це більш предметно. З моєї практики, коли Claude Code робить виклик до Figma MCP, він повертає шість шарів інформації — і кожен із них напряму залежить від того, наскільки старанно дизайнер заповнив файл:

1. Code Connect snippets — якщо компонент змаплено на вашу кодову базу. Це найточніший рівень: агент отримує реальний код вашого компонента і знає, як його викликати. Без Code Connect цього шару просто немає.

2. Component description — намір дизайнера і нотатки про використання. Те саме, що ви заповнюєте в полі опису компонента у Figma.

3. Documentation links — посилання на зовнішню документацію, якщо ви їх додали в опис компонента.

4. Reference code — згенерований React+Tailwind код як орієнтир. Не для копіювання, а для референсу: це якість, яку агент може дати «з нуля», без вашої підказки. Зазвичай — недостатня.

5. Design tokens — типографіка і кольори як посилання на токени, а не як HEX-значення. Це працює лише якщо ви прив’язали стилі до variables.

6. Image assets — localhost URLs для іконок та зображень, які використовуються в макеті.

Що з цього випливає на практиці. Якщо у вашому компоненті заповнено лише ім’я та variants — агент має тільки шари 4–6: згенерований референсний код, можливо токени, можливо асети. Він буде «вгадувати» вашу кодову базу. Якщо ж заповнено все — від root description до Code Connect — агент працює з шаром 1, тобто практично з готовим кодом.

Різниця у точності генерації між цими двома сценаріями — приблизно як різниця між «схожою картинкою» і «тим самим компонентом».

Далі — три рівні підготовки. Від найпростішого до найскладнішого.

Рівень 1. Атомарний компонент: Button

Почнімо з кнопки. Здається, найпростіший випадок — але саме на ньому найчастіше ламається все інше, тому що Button потім використовується скрізь.

Що мінімально має бути заповнено в самому компоненті:

Ім’я компонента — точно таке, як у коді. Якщо в кодовій базі це Button, то і у Figma має бути Button. Не «кнопка primary», не «Btn / Main». Просто Button. Це звучить очевидно, але в файлах які потрапляють мені в роботу від клієнтів я постійно бачу розсинхрон.

Опис компонента (root description) — одне-два речення, що це таке і коли використовувати. Не «красива кнопка для CTA», а щось функціональне:

Primary action element. Used to trigger the main user action on a screen or within a component. One primary button per view. Use Secondary or Ghost variants for less critical actions.

Цей опис AI читає першим. Він задає всю рамку.

Documentation для значень variants. Тут є нюанс: Figma не дозволяє писати окремий опис для кожного значення variant property (типу primary, secondary, ghost) — у властивості може бути лише її назва і список значень. Тому стандартна практика, яку рекомендує і сама Figma, — додавати текстові шари на canvas поруч із component set, де ви розшифровуєте, що означає кожне значення:

• primary — головна дія на екрані
• secondary — альтернативна дія, рівень вище за tertiary
• ghost — для дій усередині щільних інтерфейсів, де primary був би занадто

Ці підписи лежать на canvas як звичайний текст — і агент через MCP бачить їх разом із компонентом. Те саме можна робити для boolean-властивостей (hasIcon, isLoading, isDisabled), описуючи сценарій кожної з них.

Опційно — у Figma можна додати description і до окремого варіанта компонента (вибрати конкретний варіант усередині component set і заповнити йому опис у правій панелі). Це теж читається агентом, але на практиці заповнюють рідко.

Layer descriptions усередині компонента. Це менш очевидна частина, але дуже корисна. Якщо всередині кнопки є слот для іконки, named layer Icon з описом «Optional leading icon. Inherits color from button label.» дає агенту чітке розуміння, що це не просто фігура, а слот.

Прив’язка до variables. Усі кольори, відступи, типографіка — через variables/tokens, ніяких хардкодів. Якщо колір #0D1B2A лежить як локальний стиль «темно-синій» — для агента це просто колір. Якщо це color/background/primary — це семантика, яку він проєктує на вашу кодову базу.

Як це виглядає на практиці: підготовлений Button агент розуміє за пару секунд. Він не пробує його перемалювати, не створює нових стилів. Він просто бачить — «ось компонент Button, ось його варіант primary, ось токени, ось code reference».

Окремо: бібліотека має бути запаблішена

Якщо ви ведете дизайн-систему в окремому Figma-файлі (як майже всі це роблять), а екрани/секції збираєте в інших файлах — бібліотека має бути запаблішена. Інакше в робочому файлі лежать не повноцінні інстанси з прив’язкою до бібліотеки, а локальні копії.

Для агента це принципово різні речі. Запаблішена бібліотека = інстанс знає свого «батька», агент бачить ланцюжок до оригінального компонента та його опису. Незапаблішена = агент бачить просто фрейм з якимись шарами, без зв’язку з нічим.

Якщо ж ви робите все в одному файлі — і компоненти, і секції — публікація не потрібна, але всі інші вимоги (опис, properties, токени) залишаються в силі.

Code Connect: для ідеальної точності

Code Connect — це міст між Figma-компонентом і конкретним шматком коду у вашій кодовій базі. Простими словами: ви явно говорите «оцей Button у Figma — це ось такий <Button> у коді, з такими props і такою сигнатурою».

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

Що змінюється, коли компонент заведено в Code Connect:

• агент перестає генерувати React-код з нуля і починає використовувати ваш справжній компонент із бібліотеки
• props у згенерованому коді точно збігаються з тими, що очікує ваш компонент
• маппінг variants → props стає однозначним (не «схожі назви», а ті самі)

Без Code Connect агент видає референсний React+Tailwind, який треба адаптовувати руками. З Code Connect — він викликає готовий компонент так, як це зробив би розробник вручну.

Я не вважаю, що Code Connect обов’язковий — без нього все одно можна працювати, особливо для невеликих систем. Але якщо ви хочете від агента ідеальної точності на рівні готового коду, без post-editing, — Code Connect рекомендується для кожного компонента дизайн-системи.

Неочевидна оптимізація: Text-компонент замість стилів

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

Стандартний підхід: ви створюєте text styles (Heading 1, Heading 2, Body, Caption тощо) і застосовуєте їх до текстових шарів напряму. Це робочий і правильний підхід для дизайну. Але коли агент читає такий макет, на кожен текстовий шар він окремо звертається до стилю, щоб дізнатися його параметри. Один шар — один запит. Велика секція з десятком текстових елементів — десятки запитів.

Альтернатива, яку я почала використовувати: завести окремий компонент Text. Простий, майже «тупий» — у ньому одна variant property style зі значеннями всіх ваших типографічних стилів: H1, H2, H3, Body, Body Small, Caption, Label і так далі. Усередині кожного варіанта — текстовий шар із застосованим відповідним стилем.

Тепер замість того, щоб ставити текст і призначати йому стиль зі списку, ви ставите інстанс компонента Text і вибираєте style=H1 через property panel.

Логічне питання: навіщо тоді взагалі потрібні text styles?

Стилі залишаються — це джерело правди. Компонент Text — це інтерфейс доступу до них. Агент при читанні макета бачить інстанс компонента з відомою property — і йому не треба окремо запитувати кожен стиль для кожного шару. Один компонент, відома структура, кешований опис. Менше токенів на ту саму інформацію.

На малих файлах різниця незначна. На великих — особливо коли ви даєте агенту цілу секцію або екран — це може скоротити обсяг контексту в кілька разів. А ще — це робить макет передбачуванішим: агент звертається до Text-компонента так само, як до Button, замість того щоб обробляти десятки сирих текстових шарів.

Рівень 2. Композитний компонент: Card

Тут починається найцікавіше. Бо саме на цьому рівні AI помиляється найчастіше — і саме сюди дизайнери найрідше доходять у документації.

Уявімо звичайну ProductCard: зображення зверху, заголовок, опис, кнопка дії знизу. Усередині неї лежить інстанс компонента Button.

Для агента критично важливо зрозуміти не «тут намальована кнопка», а «тут використано наш компонент Button у варіанті primary». Це різні речі — і генерують вони різний код.

Що має бути на рівні Card, щоб ця різниця була видима:

Опис самої картки — як з кнопкою, але на крок вище. Що це за патерн, де використовується, які в нього обмеження. Наприклад:

Content card for product entities. Always contains image, title, optional description, and one primary action. Used in product grids, search results, and recommendation sections. Max 3 lines for description before truncation.

Sub-component dependencies. Це поле, якого немає у Figma за замовчуванням, але яке я завжди додаю — або в опис картки, або в окрему канвас-секцію поряд з компонентом. Перелік: цей патерн залежить від Button, Image, Badge, Text. Якщо ви хоч раз працювали з агентом без цього поля — побачите різницю одразу.

State Matrix. Окремий блок поряд із компонентом, де перераховані всі його стани: default, hover, loading, empty, error. Не просто візуально, а текстом — що саме змінюється і чому. Я це роблю на сусідній canvas-секції, не всередині самого компонента, щоб не засмічувати property panel.

Ще одна реальна історія. Якось я просила агента згенерувати нову картку, схожу за структурою на існуючу. Опис картки був мінімальним — просто «картка з зображенням, заголовком і кнопкою». На виході агент створив усе з нуля: окрему кнопку, окреме зображення, окремий текстовий блок — жодного з компонентів моєї бібліотеки він не використав, хоча всі вони вже були готові. Після того як я додала в опис картки один рядок — «складається з компонентів Image, Heading, Body, Button» — генерація на тому ж промпті стала зовсім іншою. Агент почав збирати картку через інстанси існуючих компонентів. Один рядок тексту змінив усе.

Рівень 3. Секція: композиція з карток

Третій рівень — це коли картки складаються в секцію. Наприклад, FeaturesSection із трьох ProductCard. Або grid із десяти.

Тут уже не так важлива анатомія самого компонента — важлива логіка композиції. І ось тут більшість файлів повністю провалюється, тому що секції зазвичай не мають документації взагалі. Їх просто збирають з компонентів — і все.

Що допомагає AI розуміти секції:

Адаптивні варіанти секції як окремий компонент. Це підхід, який я виробила для себе. Замість того щоб описувати текстом, як секція адаптується («3 cards on desktop, 2 on tablet, 1 on mobile»), я роблю саму секцію компонентом і всередині нього закладаю різні layout-варіанти для різних брейкпоінтів. Наприклад: для екрана більше 1200px — картки виставлені горизонтально в ряд, для меншого — перебудовані вертикально. Кожен варіант — це окремий стан того самого компонента секції.

Що це дає агенту: він бачить не текстове пояснення «як має поводитися секція», а реальну структуру для кожного брейкпоінта. Йому не треба нічого інтерпретувати — він просто зчитує два готові layout-и і генерує відповідний код з media queries. Точність значно вища.

Anatomy. Перелік того, з чого секція складається на рівні структури: header (eyebrow + title + description), cards container, optional CTA.

Content rules. Скільки максимум карток допускається, що відбувається при недостатньому контенті, як секція себе поводить, якщо опис картки занадто довгий. Це особливо важливо, коли AI генерує код із заглушками — без content rules він наставить три однакові placeholder-и і скаже «готово».

Sub-component dependencies на рівні секції. Те саме, що для картки, але з урахуванням, що секція використовує не тільки ProductCard, а й, наприклад, SectionHeader, BackgroundContainer тощо.

Anatomy, Content rules і Sub-component dependencies я оформлюю окремою канвас-областю поряд із секцією — як супровідну документацію. Сама ж адаптивна логіка живе всередині компонента у вигляді окремих layout-варіантів для різних брейкпоінтів. Агент через MCP читає і структуру компонента, і документацію поряд із ним, якщо файл правильно організований.

Часті помилки, які я бачу

Окремий короткий блок про те, що я повторно зустрічаю в чужих файлах — і в своїх теж, чесно кажучи.

Імена компонентів не збігаються з кодом. У Figma — Button / Primary / Default, у коді — <PrimaryButton>. Або навпаки: у Figma CTA Button, у коді просто Button. Агент не знає, що це одне й те саме.

Локальні стилі замість variables. Дизайнер витягнув колір через піпетку, призначив локальним стилем — візуально все ок. Але це позбавляє агента семантики. Усі стилі мають бути через variables.

Detached instances всередині компонентів. Хтось колись відкріпив інстанс і відредагував. Зовні виглядає як інстанс, насправді — окремий шар. Агент бачить це як унікальний компонент і генерує під нього окремий код.

Незапаблішена бібліотека. Описано вище — без публікації інстанси в робочих файлах не зв’язані з оригіналами, і весь контекст компонента губиться.

Описи у форматі «красива», «сучасна», «акуратна». Це описи для портфоліо, не для агента. Йому потрібна функція, не естетика.

«Майже-інстанси». Це коли в макеті лежить елемент, який візуально точно повторює ваш компонент із бібліотеки — наприклад, кнопку, — але насправді це не інстанс, а намальована окремо група шарів (frame з текстом і фоном усередині). Зовні відрізнити неможливо. Для агента це не Button, а невідомий прямокутник, і він згенерує під нього окремий код. Перевіряти можна так: клік по елементу має показати в правій панелі або інстанс із посиланням на головний компонент, або плоский frame без зв’язків — у другому випадку це і є «майже-інстанс».

Variants без підписів на canvas. У вас є component set із кількома варіантами, але поряд із ним немає жодного тексту, який пояснює, чим вони відрізняються логічно. Агент здогадається, що це варіанти одного компонента, але не зрозуміє намір — коли який використовувати.

Секції без Behaviour. Найпоширеніше. Секція є, картки лежать, але як вона адаптується, що відбувається при різній кількості контенту — ніде не написано. Агент згенерує статичний grid, який зламається при першому реальному наповненні.

Окремо: коли є Storybook на іншому боці

У командах із розробленою кодовою базою Figma — це лише половина контракту. Друга половина — Storybook (або еквівалент). І тут з’являється новий рівень підготовки: синхронізація між Figma і Storybook.

Якщо у вашому Storybook компонент має props variant, size, hasIcon, isLoading — у Figma той самий компонент повинен мати точно ті самі властивості з тими самими назвами. Не «type» у Figma і «variant» у коді. Однакові імена, однакові значення.

Те саме з варіантами стилів. Якщо у Storybook є стани default, hover, pressed, disabled — усі чотири мають бути у Figma як окремі варіанти. Не три, не із синонімами. Точна відповідність.

Я для себе виробила робочий процес: коли роблю review нового компонента, дивлюсь поруч на Figma-специфікацію і Storybook-рендер, і записую всі розсинхрони у структурованому форматі — поточне значення проти очікуваного, у чому вплив. Це окрема дисципліна, але вона радикально покращує якість того, що згодом генерує агент. Бо коли агент бачить однакові імена з обох боків, він припиняє «вгадувати маппінг» і просто його використовує.

Ця тема заслуговує окремої статті — тут згадую її лише щоб зазначити: підготовка Figma — це необхідна умова, але не достатня, якщо у вас уже є кодова база.

Чек-лист перед тим, як передати файл розробнику з Claude Code

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

Для атомарного компонента (Button, Input, Badge тощо):

• ім’я збігається з кодом (без префіксів типу «UI / », «v2 / »)
• root description заповнено
• значення variants пояснені текстовими підписами на canvas поряд із component set або через description
• усі шари названі осмислено (Label, Icon, Container — не Rectangle 47)
• усі стилі через variables, не локальні
• немає detached instances всередині
• компонент заведено в Code Connect (для ідеальної точності)

Для бібліотеки в цілому:

• бібліотека запаблішена (якщо компоненти і екрани в різних файлах)
• усі компоненти, які використовуються в робочих файлах, — це інстанси з бібліотеки, а не локальні копії
• є компонент Text, який обгортає усі типографічні стилі (для економії токенів при читанні)

Для композитного компонента (Card, ListItem, FormGroup):

• усе з попереднього списку
• sub-component dependencies перераховано (хоч у root description, хоч на canvas поряд)
• інстанси всередині залишаються інстансами — без detach, без локальних замін стилів
• описано стани компонента (default, hover, loading, empty, error)
• немає «майже-інстансів» — тобто кнопок, які виглядають як ваш Button, але насправді намальовані окремо

Для секції:

• адаптивна логіка закладена в компонент як окремі layout-варіанти для різних брейкпоінтів
• Anatomy описано (з яких частин складається)
• Content rules задано (мін/макс кількість, переповнення)
• Sub-component dependencies перераховано
• немає вкладених secondary-патернів без документації

Якщо хоча б 70% цього списку закрито — Claude Code на іншому боці працює радикально точніше

Що це означає для ролі дизайнера

Що це означає для ролі дизайнера? Не хочу робити філософський розділ, але додам лише одне спостереження. Раніше документація компонента була переважно для інших дизайнерів і розробників — людей. Тепер у цієї документації з’явився ще один читач — агент. І він читає буквально те, що написано, без здогадок та інтерпретацій.

Це насправді добре. Бо коли я пишу опис компонента, знаючи, що його прочитає Claude Code, — я перестаю писати «красива кнопка для головної дії». Я пишу «Primary action element. One per view.» І раптом виявляється, що це і людям корисніше.

AI у цьому сенсі — не загроза професії. Це жорсткий редактор, який підсвічує, де ви насправді думали системно, а де просто намалювали красиво.