Одна з найбільших проблем хендофу — розробник відкриває компонент у Dev Mode, бачить вкладені фрейми і не розуміє, які стани існують, які параметри можна змінювати і що взагалі є опціональним. Результат: запитує дизайнера, той показує 20 варіантів у Figma, розробник пише хардкод.

Component API вирішує це. Це спосіб описати компонент у Figma так само, як він буде описаний у коді: через props, variants і slots.

Variants: зовнішні стани

Variant properties у Figma — еквівалент enum-пропів у коді. Наприклад, для Button:

  • Size: sm / md / lg
  • Variant: primary / secondary / ghost / destructive
  • State: default / hover / focus / disabled / loading

Важливо: назви Variant properties мають збігатися з назвами пропів у коді. Якщо в React компоненті є variant="primary", у Figma теж має бути property "Variant" зі значенням "primary".

Boolean properties: show/hide логіка

Boolean properties — для опціональних елементів всередині компонента.

  • Has Icon: true/false — показує або ховає іконку
  • Has Badge: true/false — показує лічильник
  • Is Full Width: true/false

Це еквівалент пропів типу showIcon?: boolean у TypeScript.

Instance swap: слоти для контенту

Instance swap properties — це слоти. Дозволяють замінити вкладений компонент (наприклад, іконку) без зміни загальної структури.

Правило хорошого Component API: якщо розробник дивиться на компонент у Dev Mode і може прочитати всі можливі стани і параметри без питань до дизайнера — API налаштований правильно.

Text properties: динамічний контент

Text properties дозволяють міняти текст прямо з панелі компонента, без заглиблення в шари. Використовуйте для: лейблів кнопок, заголовків карток, placeholder-тексту.

Як пов'язати Figma API і код

Найкращий інструмент для синхронізації — Figma Code Connect. Ви пишете mapping: "Figma property Variant=primary → React prop variant='primary'". Dev Mode тоді показує реальний код з правильними пропами, а не просто значення.

Без Code Connect — документуйте mapping вручну в Notion або Storybook stories. Мінімум: таблиця "Figma property → Code prop → Тип → Значення за замовчуванням".

Типові помилки

  • State (hover, focus) — окремий Variant замість interactive prototype state
  • Різні назви properties у Figma і пропів у коді без документованого mapping
  • Занадто багато Variants — комбінаторний вибух робить Figma непридатним
  • Boolean для станів замість Variant (наприклад, Is Disabled: true замість State: disabled)

Будуємо Figma-компоненти з правильним Component API і Figma Code Connect — щоб розробники читали компоненти як документацію.