Storybook: документация компонентов с примерами состояний

Прямой ответ

Документация компонента описывает состояние элемента примером, поэтому каждое состояние отображается отдельно и проверяется до применения в продукте.

export const Disabled = { args: { disabled: true } };

Каждое состояние отображается отдельным примером, поэтому сочетание параметров, не описанное в документации, не применяется в продукте. О структуре системы — в статье про дизайн-систему.

Описание состояний и сочетание параметров

Состояние компонента определяется сочетанием параметров, поэтому каждое значимое сочетание описывается отдельным примером.

Отдельный пример на состояние. Состояние отображается независимо, поэтому поведение проверяется без переключения параметров вручную.

Значимое сочетание. Сочетание, влияющее на внешний вид либо поведение, описывается отдельно, поэтому неявное состояние не остаётся непроверенным.

Граница значений. Крайние значения параметра описываются примером, поэтому поведение при граничном значении проверяется до применения.

Практическое следствие: документация с одним примером показывает обычное состояние, поэтому поведение при отключённом либо загруженном состоянии остаётся непроверенным.

Отдельный аспект — сочетание параметров. Состояние, достижимое только при определённом сочетании, требует отдельного примера, поскольку проверка каждого параметра по отдельности не покрывает сочетание.

Свойства компонента в документации

Перечень свойств определяет, как компонент настраивается, поэтому документация содержит тип и назначение каждого свойства.

Тип свойства. Ограничивает допустимые значения, поэтому передача значения другого типа обнаруживается до отображения.

Назначение свойства. Описывает, что изменяет параметр, поэтому выбор свойства не требует чтения кода компонента.

Значение по умолчанию. Показывает поведение без передачи свойства, поэтому отсутствие параметра не приводит к неопределённому состоянию.

Практическое следствие: документация без описания назначения свойства требует чтения кода компонента, поэтому настройка замедляется.

Проверка вариантов и визуальное сравнение

Проверка варианта выполняется до применения компонента в продукте, поэтому расхождение обнаруживается на этапе описания.

Отображение варианта. Вариант отображается в изоляции, поэтому влияние остальных частей страницы исключается.

Сравнение с предыдущей версией. Изменение внешнего вида фиксируется сравнением, поэтому незапланированное расхождение обнаруживается до выпуска.

Проверка при изменении. Обновление компонента сопровождается пересбором примеров, поэтому изменение состояния видно сразу.

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

О сравнении снимков — в статье про визуальное регрессионное тестирование; о значениях внешнего вида — в статье про дизайн-токены.

Состав примеров при изменении компонента

Состав примеров обновляется при изменении компонента, поэтому новое состояние отображается отдельно и проверяется до применения.

Новое свойство. Добавление свойства сопровождается примером, поэтому поведение при значении свойства проверяется изолированно.

Изменение поведения. Изменение поведения без изменения свойства отражается в примере, поэтому ожидание потребителя соответствует реализации.

Удаление состояния. Пример удалённого состояния убирается, поэтому перечень примеров соответствует доступным состояниям компонента.

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

Практика: настройка документации компонента

1. Описывайте каждое состояние отдельным примером. Поведение состояния проверяется без переключения параметров.

2. Добавьте примеры для крайних значений параметра. Поведение при граничном значении проверяется до применения.

3. Описывайте назначение каждого свойства. Настройка компонента не требует чтения кода.

4. Фиксируйте значение по умолчанию. Поведение без передачи свойства определено.

5. Описывайте сочетания параметров отдельными примерами. Неявное состояние не остаётся непроверенным.

6. Проверяйте компонент в изоляции. Влияние остального содержимого страницы исключается.

7. Пересобирайте примеры при изменении компонента. Изменение состояния видно сразу.

Рекомендации:

1. Не ограничивайтесь одним примером на компонент. Состояния кроме обычного остаются непроверенными.
2. Сопровождайте свойство описанием назначения. Документация без назначения требует чтения кода компонента.
3. Не проверяйте компонент только в составе страницы. Изолированное отображение показывает изменение без постороннего влияния.
4. Фиксируйте условие применения варианта. Выбор между вариантами определяется правилом, а не предпочтением.
5. Пересматриваем примеры при добавлении свойства. Новое состояние требует отдельного примера.

Практический сценарий: состояние компонента не отображалось в продукте

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

1. Диагностика. Проверка документации показала, что отключённое состояние не было описано отдельным примером. Единственный пример показывал обычное состояние, поэтому сочетание параметра отключения с остальными не проверялось.
2. Причина. Документация содержала один пример на компонент, поэтому состояния, достижимые сочетанием параметров, не отображались и не проверялись.
3. Действия. (а) Добавили отдельный пример для отключённого состояния, чтобы поведение отображалось изолированно; (б) добавили примеры для остальных состояний — загруженного и с ошибкой, чтобы каждое состояние проверялось отдельно; (в) описали назначение свойства отключения в перечне свойств, чтобы настройка не требовала чтения кода; (г) проверили сочетание отключения с остальными параметрами отдельным примером, чтобы неявное состояние не осталось непроверенным; (д) настроили пересборку примеров при изменении компонента, чтобы изменение состояния было видно сразу.
4. Результат. Отключённое состояние отображается отдельным примером и проверяется до применения в продукте, поэтому элемент не отвечает на действие.

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

FAQ

Зачем описывать каждое состояние отдельным примером? Состояние отображается изолированно, поэтому поведение проверяется без переключения параметров вручную.

Почему одного примера на компонент недостаточно? Пример показывает обычное состояние. Поведение при отключённом либо загруженном состоянии остаётся непроверенным.

Что описывать в перечне свойств компонента? Тип, назначение и значение по умолчанию. Настройка компонента не требует чтения кода.

Как проверить сочетание параметров? Отдельным примером для значимого сочетания. Проверка параметров по отдельности не покрывает сочетание.

Источники: Storybook Docs, Storybook Writing Stories, Semantic Versioning — ссылки в шапке.