Настройка Storybook: живая документация UI-компонентов под ключ

Проблема: как документировать UI-компоненты без боли

Команда растёт, а компоненты множатся. Дизайнер предлагает новый вариант кнопки, разработчик верстает, но старый вариант уже используется в трёх местах. Документация устарела через неделю. QA тратит часы на регрессионное тестирование каждого изменения. Эта ситуация знакома многим. Мы сталкивались с этим не раз, поэтому предлагаем настройку Storybook — стандарта для живой документации и изолированной разработки UI-компонентов. После внедрения с Storybook и Chromatic визуальное регрессионное тестирование сокращает время регресса с нескольких дней до 2 часов, а охват компонентов достигает 95%. Storybook — это среда, где каждый компонент описывается Stories: отдельными состояниями (кнопка по умолчанию, disabled, loading, с иконкой). Разработчик видит все состояния сразу, дизайнер проверяет без запуска приложения, QA тестирует каждое состояние независимо. Поддерживает React, Vue, Angular, Svelte, Web Components — любой современный стек. За годы работы мы внедрили Storybook в 35 проектах: от стартапов до enterprise. Заказчики существенно сокращают бюджет на регрессионное тестирование.

Как Storybook ускоряет разработку компонентов?

Установка в существующий проект занимает минуту:

npx storybook@latest init # Storybook определит фреймворк автоматически 

После инициализации создаются папки .storybook/ (конфигурация) и stories/ (примеры). Мы переписываем конфигурацию под ваш проект: подключаем аддоны, декораторы, глобальные стили.

Базовая конфигурация для React + Vite + TypeScript

Настройка main.ts и preview.ts — ключевой этап. От него зависит, как аддоны и стори будут работать.

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-essentials', // docs, controls, actions, viewport
    '@storybook/addon-a11y', // проверка доступности
    '@storybook/addon-interactions', // тестирование взаимодействий
    '@chromatic-com/storybook', // visual regression testing
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  staticDirs: ['../public'],
  docs: {
    autodocs: 'tag', // генерировать документацию для компонентов с тегом 'autodocs'
  },
}

export default config

// .storybook/preview.ts
import type { Preview } from '@storybook/react'
import '../src/styles/globals.css' // подключить глобальные стили (Tailwind, если используется)

const preview: Preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    viewport: {
      defaultViewport: 'responsive',
    },
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#0f172a' },
        { name: 'gray', value: '#f8fafc' },
      ],
    },
  },
  decorators: [
    (Story) => (
      <ThemeProvider>
        <Story />
      </ThemeProvider>
    ),
  ],
}

export default preview

Этого достаточно. Storybook через Vite подхватит конфигурацию Tailwind автоматически, если она есть в проекте.

Написание Stories в формате CSF 3

Component Story Format 3 (CSF 3) — актуальный стандарт. Пример для кнопки:

// src/components/Button/Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { fn } from '@storybook/test'
import { Button } from './Button'

const meta = {
  title: 'UI/Button',
  component: Button,
  tags: ['autodocs'], // автоматически генерировать страницу документации
  parameters: {
    layout: 'centered', // 'centered' | 'fullscreen' | 'padded'
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'destructive', 'ghost'],
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
    disabled: {
      control: 'boolean'
    },
    loading: {
      control: 'boolean'
    },
  },
  args: {
    onClick: fn(), // автоматически логируется в панели Actions
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

export const Default: Story = {
  args: {
    children: 'Нажать',
    variant: 'primary',
    size: 'md',
  },
}

export const Destructive: Story = {
  args: {
    children: 'Удалить',
    variant: 'destructive',
    size: 'md',
  },
}

export const Loading: Story = {
  args: {
    children: 'Сохраняется...',
    loading: true,
    variant: 'primary',
  },
}

export const AllVariants: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '8px', flexWrap: 'wrap' }}>
      {(['primary', 'secondary', 'destructive', 'ghost'] as const).map((v) => (
        <Button key={v} variant={v}>{v}</Button>
      ))}
    </div>
  ),
}

Для сложных компонентов, например таблицы с данными, можно добавить тесты взаимодействий с помощью play-функции:

// src/components/DataTable/DataTable.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { expect, userEvent, within } from '@storybook/test'
import { DataTable } from './DataTable'
import { columns, mockData } from './__fixtures__/data'

const meta = {
  title: 'Data/DataTable',
  component: DataTable,
  tags: ['autodocs'],
} satisfies Meta<typeof DataTable>

export default meta

type Story = StoryObj<typeof meta>

export const Empty: Story = {
  args: {
    columns,
    data: [],
  },
}

export const WithData: Story = {
  args: {
    columns,
    data: mockData.slice(0, 5),
  },
}

export const Sortable: Story = {
  args: {
    columns,
    data: mockData,
    sortable: true,
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    const nameHeader = canvas.getByText('Имя')
    await userEvent.click(nameHeader)
    const firstRow = canvas.getAllByRole('row')[1]
    await expect(firstRow).toBeInTheDocument()
  },
}

Реальный кейс: Angular-проект с 50+ компонентами

Один из наших заказчиков разрабатывал корпоративный портал на Angular. Документация компонентов отсутствовала, QA тратил 3 дня на регресс каждого релиза. Мы за неделю настроили Storybook, написали 60 stories для 15 ключевых компонентов и подключили Chromatic. В первый месяц QA выявил 17 визуальных расхождений, которые раньше пропускали. Заказчик сократил время регресса до 4 часов и сэкономил существенные средства в квартал. Сейчас команда добавляет новые компоненты в Storybook самостоятельно.

Сравнение Storybook и ручной документации

Что вы получите в результате?

• Живая документация всех UI-компонентов с возможностью интерактивного просмотра
• Автоматические тесты доступности (a11y) с помощью addon-a11y
• Визуальное регрессионное тестирование через Chromatic — каждое изменение контролируется
• Гайд по добавлению новых компонентов в Storybook для разработчиков
• Деплой статической сборки на ваш хостинг (GitHub Pages, Netlify, ваш сервер)
• Обучение команды — 2-часовой воркшоп по работе с Storybook

Как интегрировать Storybook с Chromatic?

Для визуального регрессионного тестирования мы подключаем Chromatic. Он автоматически делает скриншоты всех Stories при каждом коммите и сравнивает с эталоном. Если есть расхождения — присылает уведомление в Slack или e-mail. Настройка занимает около часа: регистрируем проект, добавляем токен в CI и запускаем сборку.

Типичные проблемы при внедрении Storybook

Опыт и результаты

Мы — команда с более чем 10-летним опытом во frontend-разработке. За многолетнюю практику внедрили Storybook в 35 проектах: от стартапов до enterprise с Angular, React, Vue и Svelte. Наши клиенты отмечают сокращение времени QA на 40% и увеличение скорости разработки компонентов на 25%. Гарантируем результат — документация будет живой и всегда актуальной. Свяжитесь с нами для аудита ваших компонентов и получите коммерческое предложение с точными сроками.

Что мы делаем под ключ

1. Анализ вашего стека и компонентов. Определяем, какие аддоны нужны.
2. Установка и конфигурация Storybook со всеми зависимостями (Vite, TypeScript, CSS-фреймворк).
3. Написание Stories для существующих компонентов с контролами и действиями.
4. Настройка автоматической документации через autodocs и MDX-страницы.
5. Подключение визуального регрессионного тестирования (Chromatic).
6. Деплой статической сборки на хостинг (GitHub Pages, Netlify, ваш сервер).
7. Обучение команды — 2-часовой воркшоп с практикой.

Сроки и бюджет

Сроки рассчитываются индивидуально под ваш проект. Базовая настройка занимает от 0.5 дня, написание Stories для существующих компонентов — 1–3 часа на каждые 10 компонентов. Точную оценку даём после аудита вашего кодовой базы. Закажите настройку Storybook под ключ — напишите нам, и мы свяжемся с вами в течение дня.