API компонента и документация — Примеры

Пример 1 — Одна таблица свойств из пяти реальных мест вызова

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

Места вызова в продукте
  основное действие в шапке страницы   "Сохранить изменения"
  второстепенное действие в диалоге    "Отмена"
  удаление аккаунта                    "Удалить аккаунт"
  действие в строке таблицы            иконка + "Изменить"
  ссылка в стиле кнопки                "Смотреть отчёт"

Решение

Свойство   Значения                              По умолчанию   Примечание
variant    primary | secondary | danger | link   primary        именованный набор, без свободного булева
size       small | medium | large                medium         независим от варианта
icon       элемент                              нет            необязательная иконка слева
loading    логическое значение                  false          документированное состояние

Отвергнуто: large, ghost, icon-only, full-width как булевы значения; они
складываются в кнопки, которых никто не рисовал. icon-only становится
size="small" + icon + без метки.

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

Пример 2 — Страница, которая останавливает первый форк

Кнопка выходит, и дизайнер просит разрушительное действие, которое на самом деле таким не является. Напишите короткую страницу документации: какие состояния показать и какие строки «делайте» и «не делайте» в неё включить. Потребитель прочитает этот фрагмент вместо того, чтобы форкать.

Запрос
  «Нам нужна красная кнопка для "Архивировать проект". Не разрушительное,
   но должно выделяться. Можете добавить ещё один вариант?»

Решение

Кнопка

Состояния
  по умолчанию  метка, основная заливка
  загрузка      метка заменена индикатором, элемент отключён
  отключена     приглушённая заливка, нет отклика на нажатие

Делайте
  используйте variant="danger" для действия, которое нельзя отменить
  используйте variant="primary", когда это единственное главное действие на экране
Не делайте
  используйте variant="danger" для важного основного действия
  не форкайте локальную кнопку из-за нехватки варианта; заявите случай вместо этого

Решение
  архивация обратима, поэтому использует variant="secondary". Вариант
  danger зарезервирован за удалением, и именно это зарезервированное
  значение заставляет его всё ещё читаться как опасное.

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