Одна з найчастіших точок тертя між дизайном і розробкою — невідповідність між тим, як дизайнер мислить про компонент, і тим, як розробник його реалізує. Дизайнер бачить "кнопка з іконкою зліва". Розробник бачить: Button icon={<IconSearch />} iconPosition="left".
Якщо дизайнер розуміє, як мислить розробник — він проектує компоненти так, щоб вони природно транслювалися в код без десятків уточнень.
Що таке Component API
API компонента — це набір параметрів (props), які контролюють зовнішній вигляд і поведінку компонента ззовні. Для кнопки це може бути: variant, size, disabled, loading, icon, iconPosition, onClick.
Важливо розуміти: те, що ви називаєте "варіантами" у Figma Properties — це і є майбутній API. Якщо у вас в Figma є property "Size" зі значеннями "Small / Medium / Large" — в коді буде проп size="sm | md | lg".
Три типи пропсів
Boolean props — true/false. disabled, loading, fullWidth, readOnly. У Figma це Boolean properties. Найпростіший тип — перемикач.
Enum props — один з набору значень. variant="primary | secondary | ghost", size="sm | md | lg". У Figma — Instance Swap або Text з набором варіантів.
Slot props — слот для довільного вмісту. icon, leftElement, rightElement, children. У Figma — Layer що може бути замінений через Instance Swap або drag-and-drop.
Правило проектування: якщо два компоненти відрізняються тільки одним параметром — це один компонент з пропсом, а не два окремих компоненти. Але якщо вони відрізняються структурно (різна кількість елементів, різна логіка) — це різні компоненти.
Як дизайнер може спроектувати API заздалегідь
При проектуванні нового компонента задайте собі такі питання:
- Що в цьому компоненті може змінюватися? (колір, розмір, наявність іконки, текст)
- Чи є серед цих змін взаємовиключні? (primary або secondary, але не обидва одночасно)
- Що може бути відсутнім? (іконка може бути, а може не бути — це optional prop)
- Що завжди є? (текст кнопки — завжди, це required prop)
- Які комбінації варіантів неможливі? (розмір "large" + варіант "ghost" — чи це ОК?)
Відповіді на ці питання — це ваш Component API у вигляді природної мови. Далі його тільки потрібно записати у специфікацію.
Figma Component Properties як API-документація
Figma Component Properties (Panel → Design → Component → Properties) — це найближче до реального API, що є в дизайнерському інструменті. Добра практика — називати properties так само, як вони будуть названі в коді.
Якщо розробник бачить у Figma property "iconPosition: left | right | none" — він реалізує точно це. Якщо бачить property "With icon (boolean)" — він отримує неповну інформацію і буде гадати де іконка.
Дизайнер що мислить API-першим — це дизайнер чиї компоненти виходять у production такими, якими були задумані.