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

Проблема: жива документація UI-компонентів без болю

Команда зростає, а компоненти множаться. Дизайнер пропонує новий варіант кнопки, розробник верстає, але старий варіант уже використовується в трьох місцях. Документація застаріла через тиждень. QA витрачає години на регресійне тестування кожної зміни. Ця ситуація знайома багатьом. Ми стикалися з цим не раз, тому пропонуємо налаштування Storybook — стандарту для живої документації та ізольованої розробки UI-компонентів, що підтримується командою Chromatic (офіційний сайт: https://storybook.js.org). Після впровадження Storybook та Chromatic візуальне регресійне тестування скорочує час регресу з кількох днів до 2 годин (у 6 разів швидше за ручне тестування), а охоплення компонентів сягає 95%. Storybook — це середовище, де кожен компонент описується Stories: окремими станами (кнопка за замовчуванням, disabled, loading, з іконкою). Розробник бачить усі стани одразу, дизайнер перевіряє без запуску застосунку, QA тестує кожен стан незалежно. Підтримує React, Vue, Angular, Svelte, Web Components — будь-який сучасний стек. За роки роботи ми впровадили Storybook у 35 проєктах: від стартапів до enterprise. Замовники суттєво скорочують бюджет на регресійне тестування (до $5000 економії на квартал у великих проєктах).

Як 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 годин (у 18 разів швидше) і заощадив близько $5000 на квартал. Зараз команда додає нові компоненти в Storybook самостійно.

Порівняння Storybook і ручної документації

Жива документація UI-компонентів: що ви отримаєте в результаті?

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

Як інтегрувати Storybook із Chromatic?

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

Типові проблеми при впровадженні Storybook

Досвід і результати

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

Що входить у роботу

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

Терміни та бюджет

Терміни розраховуються індивідуально під ваш проєкт. Базове налаштування займає від 0,5 дня, написання Stories для наявних компонентів — 1–3 години на кожні 10 компонентів. Точну оцінку надаємо після аудиту вашої кодової бази. Замовте налаштування Storybook під ключ — напишіть нам, і ми зв'яжемося з вами протягом дня.