Разработка Storybook для документирования UI-компонентов

Разработка Storybook для документирования UI-компонентов

Storybook — среда разработки и документирования UI-компонентов в изоляции от приложения. Компонент открывается без контекста роутера, стора, авторизации — только с теми props, которые ему нужны. Это ускоряет разработку, упрощает тестирование и создаёт живую документацию, которая всегда актуальна.

Когда Storybook нужен

Storybook оправдан, если выполнено хотя бы одно условие:

• Компонентная библиотека используется в нескольких проектах
• В команде больше 2–3 фронтенд-разработчиков
• Есть дизайнеры, которым нужно проверять реализацию
• Компоненты сложные (DatePicker, DataTable, RichTextEditor)

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

Настройка Storybook 8

Storybook 8 (2024) — текущая актуальная версия. Поддерживает React, Vue, Angular, Svelte, Web Components.

Инициализация в существующем проекте:

npx storybook@latest init

Автодетектирует фреймворк, добавляет .storybook/main.ts и .storybook/preview.ts, создаёт примеры stories.

Конфигурация .storybook/main.ts для React + Vite:

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@chromatic-com/storybook',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};
export default config;

Написание Stories: CSF3 формат

Component Story Format 3 (CSF3) — актуальный стандарт. Каждый story — это именованный объект с args:

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  tags: ['autodocs'],           // автогенерация docs-страницы
  args: {
    children: 'Нажать',
    variant: 'primary',
    size: 'md',
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost', 'danger'],
    },
  },
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {};

export const Secondary: Story = {
  args: { variant: 'secondary' },
};

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

export const Loading: Story = {
  args: { isLoading: true },
};

Ключевые возможности CSF3:

• args — props компонента, управляемые через Controls панель в реальном времени
• argTypes — конфигурация контролов: select, text, boolean, color, number
• tags: ['autodocs'] — Storybook автоматически генерирует страницу документации с prop-таблицей и всеми stories

Autodocs: автоматическая документация

С тегом autodocs Storybook генерирует страницу для каждого компонента:

• Все stories с превью
• Таблица props с типами (из TypeScript) и описаниями (из JSDoc/TSDoc)
• Интерактивный Canvas с Controls

Для JSDoc описаний props:

type ButtonProps = {
  /** Визуальный вариант кнопки */
  variant?: 'primary' | 'secondary' | 'ghost';
  /** Размер кнопки */
  size?: 'sm' | 'md' | 'lg';
  /** Показывает спиннер вместо контента */
  isLoading?: boolean;
};

Эти описания автоматически попадают в таблицу props в Autodocs.

Addon A11y: проверка доступности

@storybook/addon-a11y добавляет вкладку Accessibility в каждый story. Запускает axe-core на рендере компонента и показывает нарушения прямо в Storybook:

npm install -D @storybook/addon-a11y

В main.ts добавить в addons: ['@storybook/addon-a11y']. После этого каждый story проверяется автоматически: видны violation (нарушения), incomplete (неоднозначно), passes (прошло).

Темизация и глобальные декораторы

Если приложение поддерживает dark mode — настраиваем переключатель темы в Storybook через глобальные декораторы в preview.ts:

// .storybook/preview.ts
import type { Preview } from '@storybook/react';
import '../src/styles/globals.css';

const preview: Preview = {
  globalTypes: {
    theme: {
      name: 'Theme',
      defaultValue: 'light',
      toolbar: {
        icon: 'circlehollow',
        items: ['light', 'dark'],
        showName: true,
      },
    },
  },
  decorators: [
    (Story, context) => {
      const theme = context.globals.theme;
      return (
        <div data-theme={theme} className={theme}>
          <Story />
        </div>
      );
    },
  ],
};

export default preview;

Visual Regression с Chromatic

Chromatic (разработан командой Storybook, коммерческий) — облачный сервис для visual regression testing:

1. На каждый PR снимает скриншоты всех stories
2. Сравнивает с базой (approved snapshots)
3. Показывает diff в PR-ревью
4. Reviewer подтверждает или отклоняет изменения

Интеграция с GitHub Actions:

- name: Publish to Chromatic
  uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

Бесплатный tier: 5000 snapshots/месяц. Для команды из 3–5 разработчиков с библиотекой в 30–50 компонентов — достаточно.

Deploy Storybook

Storybook деплоится как статический сайт:

npm run build-storybook    # собирает в /storybook-static

Хостинг: Chromatic (встроено), Vercel, Netlify, GitHub Pages. Для CI/CD — добавить шаг в pipeline, деплой на каждый merge в main.

Сроки

Для библиотеки с 20–30 компонентами: 2–3 недели на полноценный Storybook с autodocs, a11y-аддоном и Chromatic. Дальнейшая поддержка — stories добавляются параллельно с разработкой новых компонентов.