Storybook: мастерская UI-компонентов с 33 живыми примерами

Чтобы проверить одну кнопку в большом приложении, иногда приходится пройти авторизацию, открыть нужный экран и создать подходящие данные. А для состояния «загрузка» ещё и поймать короткий момент между запросом и ответом. Гораздо удобнее иметь отдельное место, где нужное состояние открывается сразу.

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

Что такое Storybook и что такое история

Storybook не является готовой библиотекой красивых кнопок. Он предоставляет среду, в которой вы показываете собственные компоненты и описываете их состояния; React, Vue, Angular, Svelte и другие интеграции перечислены в официальном репозитории.

В нашей мастерской компонент Button один, а историй для него несколько: обычная кнопка, недоступное действие и сохранение. Каждая история задаёт начальные параметры, или args. Панель Controls позволяет менять эти параметры и сразу видеть результат, согласно документации Controls.

Живая мастерская прямо на странице

Выберите пример и нажмите «Запустить Storybook». Внутри откроется настоящая сборка Storybook 10.6.4 с React, панелями Controls, Actions, Accessibility и документацией. Для экономии загрузки она не запускается до вашего действия.

На телефоне удобнее сначала выбрать историю в списке над мастерской. Собственное меню Storybook и панель дополнений открываются его штатными кнопками; если нужно больше места, воспользуйтесь ссылкой «Открыть отдельно».

Интерфейс самого Storybook частично англоязычный, а названия состояний и учебные компоненты подготовлены на русском. Это не скриншоты: изменение Controls, события и проверки выполняются в работающем Storybook.

Для встраивания служебные настройки Storybook в этой сборке хранятся только в памяти вкладки и сбрасываются при перезагрузке. Это небольшая адаптация хранения предпочтений, а не замена Storybook собственной имитацией.

33 состояния, которые стоит проверить

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

Все 33 истории используют одни и те же исходные компоненты, а не отдельную картинку для каждого состояния. Состояния загрузки здесь зафиксированы намеренно: они не обещают, что через несколько секунд придут реальные данные.

Controls и Actions: параметры отдельно, события отдельно

Начните с Button → «Основная». В Controls измените label, затем выберите secondary или danger в variant, переключите размер и включите disabled. Подпись и внешний вид меняются за счёт параметров компонента; устройство этого механизма описано в руководстве Controls.

Верните disabled в false, откройте Actions и нажмите кнопку. В проекте обработчики заданы через fn() из storybook/test, рекомендованный способ создавать функции-шпионы и наблюдать вызовы согласно документации Actions.

• Controls: какие данные и настройки получает компонент.
• Actions: какие обработчики вызвал компонент при взаимодействии.
• Внутреннее состояние: например, выбранная вкладка или открытый диалог. Оно не обязано автоматически записываться обратно в Controls.

Параметры initialTab и initialChecked в наших примерах означают именно начальное состояние. Пользовательское переключение после запуска живёт внутри компонента; для проверки сброса выберите историю снова или измените соответствующий начальный параметр.

Узкий экран, длинный текст и клавиатура

В панели инструментов Storybook выберите подготовленный viewport: телефон 375, планшет 768 или десктоп 1200. Это размер области предпросмотра компонента, а не переключение самого WordPress на мобильную тему; принцип работы описан в документации Viewport.

На десктопе откройте Card → «Длинный заголовок», выберите узкий viewport и проверьте переносы. Затем перейдите к Dialog → «Длинное описание»: откройте окно, пройдите кнопки Tab, закройте Escape и посмотрите, куда вернулся фокус.

Вкладки Tabs можно переключать стрелками после попадания фокуса в группу. Для Switch используйте Space, а в Quantity дойдите до обоих краёв: кнопки уменьшения и увеличения должны становиться недоступными там, где дальнейшее изменение запрещено.

Доступность: намеренная ошибка и исправление

Аддон Accessibility использует axe-core и анализирует отрисованный DOM; его установка и режимы описаны в официальном руководстве по a11y. Автоматический отчёт полезен для обнаружения части проблем, но не является доказательством полной доступности интерфейса.

Откройте Contrast → «Намеренная ошибка», затем вкладку Accessibility и запустите проверку, если она не началась сама. В этой истории текст кнопки намеренно слишком светлый относительно фона. После этого откройте «Исправлено» и сравните результаты.

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

Документация и проверяемое поведение

В каждом разделе компонентов есть Docs. Тег autodocs включает автоматически создаваемую страницу документации на основе историй, args и метаданных, согласно руководству Autodocs. В этой сборке доступны описание, параметры и примеры; исходный код компонента можно скачать отдельным архивом над мастерской.

Для Button → «Основная» и Field → «Проверка формы» добавлены реальные play-функции: первая нажимает кнопку и проверяет callback, вторая вводит учебный email, отправляет локальную форму и проверяет результат. Поэтому в этих историях вы можете увидеть уже выполненное действие сразу после загрузки.

В публичной статической сборке мы не поднимаем сервер тестов Vitest и не выдаём её за готовый CI. Для проекта с постоянной разработкой отдельно настройте запуск тестов в репозитории; интеграция a11y с Vitest описана в документации Storybook.

Минимальная история на примере кнопки

Это сокращённый рабочий пример из нашей сборки. Сам Button импортируется из файла компонентов, а истории задают варианты его параметров. Для всех функций, которые вы хотите проверять, удобно использовать явный fn(), как рекомендует руководство Actions.

import { Button } from './components';
import { fn } from 'storybook/test';

export default {
  title: 'Основы/Button',
  component: Button,
  tags: ['autodocs'],
  args: {
    label: 'Сохранить',
    disabled: false,
    onClick: fn(),
  },
};

export const Primary = {};
export const Disabled = {
  args: { disabled: true, label: 'Нет доступа' },
};

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

Как подключить и разместить свой Storybook

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

# В корне вашего фронтенд-проекта
npm create storybook@latest

# Локальная разработка
npm run storybook

# Если нужен аддон проверки доступности
npx storybook add @storybook/addon-a11y

# Статическая сборка для размещения
npm run build-storybook

Готовую сборку можно обслуживать обычным веб-сервером без запущенного dev-сервера Storybook, как описано в руководстве публикации. Именно так устроен этот пример: WordPress выводит статью и iframe, а сервер отдаёт статические HTML, JavaScript, CSS и шрифты мастерской.

Не включайте в публичные истории реальные персональные данные, токены, внутренние URL и секретные бизнес-сценарии. Статическая публикация делает примеры и включённые в сборку данные доступными посетителям. Для закрытой библиотеки компонентов сначала продумайте ограничение доступа.

Когда инструмент полезен, а когда его недостаточно

Storybook особенно удобно рассматривать как каталог воспроизводимых состояний: что получает компонент, что он показывает и какие события вызывает. Для UI-кита начните с нескольких базовых компонентов и сразу добавьте ошибки, пустые состояния, длинный текст и клавиатурные сценарии.

Но успешная история не доказывает, что весь пользовательский путь работает. Интеграцию с API, маршрутизацию, авторизацию и реальные данные нужно проверять отдельно. Мастерская компонентов дополняет такие проверки, а не отменяет их.

Исходный проект доступен в GitHub Storybook. Для других практических задач в блоге есть лаборатория Requestly, компоненты Kokonut UI и сжатие изображений Squish.