Питання "чи потрібна специфікація для компонента?" — риторичне. Якщо ви передаєте компоненти розробникам без документації, кожен компонент реалізується по-своєму: інші відступи, інша поведінка при hover, інший спосіб обробки помилок.

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

Що розробник запитує при отриманні компонента

Перш ніж писати специфікацію, корисно зрозуміти, які питання виникають у розробника. За досвідом роботи з десятками команд, список завжди схожий:

  • Які стани є у компонента (default, hover, active, disabled, error, loading)?
  • Як компонент поводиться на мобільному vs десктопі?
  • Які пропси/параметри потрібні?
  • Що відбувається при overflow контенту?
  • Які анімації/переходи і з якою тривалістю?
  • Чи є accessibility-вимоги (aria-label, keyboard nav)?

Якщо ваша специфікація відповідає на всі ці питання — вона достатня. Якщо ні — вона або неповна, або перевантажена не тим.

Структура специфікації: 7 секцій

1. Overview (2–3 речення) — навіщо цей компонент існує і де він використовується. Не треба писати роман — достатньо одного параграфа.

2. Anatomy — розбивка компонента на складові частини з підписами. В Figma це робиться через червоні лінії-анотації або Figma Annotations plugin. Кожна частина отримує назву, яка відповідатиме назві проп в коді.

3. Variants & Props — таблиця всіх варіантів із значеннями. Для кнопки: variant (primary, secondary, ghost, danger), size (sm, md, lg), state (default, hover, focus, disabled, loading), icon (leading, trailing, none).

4. States — зображення кожного стану з описом коли він активується. Hover, focus, active, disabled, error, success, loading — залежно від компонента.

5. Behavior — що відбувається при взаємодії. Анімації (тривалість, easing), keyboard navigation, touch targets на мобільному.

6. Responsive — як компонент змінюється на різних брейкпоінтах. Якщо не змінюється — теж зазначте явно.

7. Accessibility — ARIA-ролі, aria-label, keyboard navigation, мінімальний контраст.

Ключове: специфікація — це не скрін з Figma. Це відповіді на запитання розробника у форматі, де не потрібно відкривати Figma щоб зрозуміти як зробити.

Що НЕ включати у специфікацію

  • Pixel-perfect виміри кожного елементу (Figma Dev Mode це покаже сам)
  • Кольори у hex якщо є токени (посилайтеся на токени, не на значення)
  • Скріншоти "як виглядає на різних пристроях" без пояснення логіки
  • Дизайн-рішення без пояснення чому (краще: "кнопка disabled має opacity 40% бо це стандарт нашої системи відповідно до WCAG 1.4.3")

Шаблон у Notion/Confluence

Найпростіший спосіб стандартизувати специфікації — шаблон у вашому документаційному інструменті. Створіть page template з 7 секціями і пустими полями. Дизайнер заповнює — розробник отримує структуровану відповідь на всі питання.

Для автоматизації частини специфікації — Figma Tokens плагін може генерувати таблиці tokenів з компонента. Claude MCP для Figma дозволяє описати компонент на натуральній мові і отримати структуровану специфікацію.

Хороша специфікація — це інвестиція 2–3 годин, яка економить 10–15 годин запитань в Slack і "а давай переробимо" після реалізації.