Проблема: как документировать 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 и ручной документации
| Критерий | Ручная документация | Storybook |
|---|---|---|
| Актуальность | Требует постоянного обновления | Всегда синхронизирована с кодом |
| Тестирование изменений | Вручную, через скриншоты | Автоматическое (визуальный регресс) |
| Удобство для QA | Нужно бегать по разделам | Все состояния на одной странице |
| Интеграция с тестами | Нет | addon-interactions + play-функции |
Что вы получите в результате?
- Живая документация всех UI-компонентов с возможностью интерактивного просмотра
- Автоматические тесты доступности (a11y) с помощью addon-a11y
- Визуальное регрессионное тестирование через Chromatic — каждое изменение контролируется
- Гайд по добавлению новых компонентов в Storybook для разработчиков
- Деплой статической сборки на ваш хостинг (GitHub Pages, Netlify, ваш сервер)
- Обучение команды — 2-часовой воркшоп по работе с Storybook
Как интегрировать Storybook с Chromatic?
Для визуального регрессионного тестирования мы подключаем Chromatic. Он автоматически делает скриншоты всех Stories при каждом коммите и сравнивает с эталоном. Если есть расхождения — присылает уведомление в Slack или e-mail. Настройка занимает около часа: регистрируем проект, добавляем токен в CI и запускаем сборку.
Типичные проблемы при внедрении Storybook
| Проблема | Решение | Как мы помогаем |
|---|---|---|
| Конфликт глобальных стилей | Изолировать стили в preview.ts | Настраиваем декораторы и импорты |
| Медленная сборка | Использовать Vite вместо Webpack | Переключаем бандлер, оптимизируем |
| Отсутствие тестов | Подключаем addon-interactions | Пишем play-функции для тестов |
| Непонятно, как писать Stories | CSF 3 документация | Составляем гайд и примеры |
Опыт и результаты
Мы — команда с более чем 10-летним опытом во frontend-разработке. За многолетнюю практику внедрили Storybook в 35 проектах: от стартапов до enterprise с Angular, React, Vue и Svelte. Наши клиенты отмечают сокращение времени QA на 40% и увеличение скорости разработки компонентов на 25%. Гарантируем результат — документация будет живой и всегда актуальной. Свяжитесь с нами для аудита ваших компонентов и получите коммерческое предложение с точными сроками.
Что мы делаем под ключ
- Анализ вашего стека и компонентов. Определяем, какие аддоны нужны.
- Установка и конфигурация Storybook со всеми зависимостями (Vite, TypeScript, CSS-фреймворк).
- Написание Stories для существующих компонентов с контролами и действиями.
- Настройка автоматической документации через
autodocsи MDX-страницы. - Подключение визуального регрессионного тестирования (Chromatic).
- Деплой статической сборки на хостинг (GitHub Pages, Netlify, ваш сервер).
- Обучение команды — 2-часовой воркшоп с практикой.
Сроки и бюджет
Сроки рассчитываются индивидуально под ваш проект. Базовая настройка занимает от 0.5 дня, написание Stories для существующих компонентов — 1–3 часа на каждые 10 компонентов. Точную оценку даём после аудита вашего кодовой базы. Закажите настройку Storybook под ключ — напишите нам, и мы свяжемся с вами в течение дня.