API компонента и документация

Что это такое

API компонента задаёт, как с ним работать потребителю: какие входные данные он принимает, какие варианты допускает, что рисует в каждом состоянии и от чего намеренно отказывается. Рядом идёт документация — короткая страница, которая перечисляет эти свойства, показывает каждый вариант и объясняет решения за ними.

Почему это важно

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

Ключевые идеи

Проектируйте API от применений, а не от реализации

Сначала соберите реальные места вызова, а затем спроектируйте наименьший интерфейс, который их покрывает. Свойство, о котором никто не просил, спекулятивно, и им будут пользоваться непоследовательно.

Применения в продукте:
  основное действие на странице      "primary"
  второстепенное действие рядом      "secondary"
  разрушительное действие            "danger"
  ссылка в стиле кнопки              вариант "link"
-> variant: primary | secondary | danger | link
-> всё остальное (размер, иконка) отдельно и с именами

Предпочитайте небольшой набор именованных вариантов множеству независимых свойств

Независимые булевы значения складываются в состояния, которых никто не рисовал: large вместе с ghost, loading и icon-only — уже не одна из четырёх кнопок, которые кто-то нарисовал. Именованные варианты держат набор конечным и обозримым.

Каждый компонент документирует состояния, а не только состояние по умолчанию

Загрузка, отключён, ошибка, пусто и длинный контент. Если потребитель не видит состояния, он вынужден придумать его сам — и почти всегда иначе, чем следующая команда.

Напишите «делайте» и «не делайте» для каждого компонента

Двух-трёх строк достаточно. «Используйте опасную кнопку для действия, которое нельзя отменить. Не используйте её для важного основного действия». Именно этот текст предотвращает форк.

Документируйте решение, а не только результат

Запишите, почему набор вариантов именно такой и что отвергли. Тогда следующий, кто предложит пятый вариант, увидит аргумент вместо того, чтобы повторять его заново.

Практика

Спроектируйте API одного компонента

Возьмите самый дублируемый паттерн, соберите пять реальных мест вызова, напишите API с его вариантами и состояниями, затем реализуйте его и перенесите места вызова.

Готово, когда: все пять мест вызова используют компонент без локальных переопределений, а в API нет опции, которой не пользуется ни одно из них.

Полностью задокументируйте один компонент

Напишите его страницу: назначение, варианты, каждое состояние, «делайте» и «не делайте» и одно зафиксированное решение.

Готово, когда: человек, который никогда не пользовался компонентом, соберёт корректный экран по одной только странице, не заглядывая в исходный код.

Частые ошибки

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

Что читать дальше

Дизайн-системы (03-design-ux/32-design-systems) — трек, к которому относится эта глава.
Когда система окупает себя (03-design-ux/32-design-systems/01-when-a-system-pays-for-itself) — решение, которое предшествует работе над компонентами.
UI-компоненты (02-frontend/12-ui-components) — взгляд со стороны реализации на тот же вопрос API.
Управление и версионирование (03-design-ux/32-design-systems/03-governance-and-versioning) — что происходит, когда API приходится менять.