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

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

Storybook — середовище розробки та документування UI-компонентів в ізоляції від додатка. Компонент відкривається без контексту маршрутизатора, сховища, авторизації — тільки з тими props, які йому потрібні. Це прискорює розробку, спрощує тестування та створює живу документацію, яка завжди актуальна.

Коли Storybook потрібен

Storybook оправданий, якщо виконана хоча б одна умова:

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

Для невеликих проектів з однією командою Storybook — overheads. Достатньо візуального тестування в самому додатку.

Налаштування 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

Додати в addons: ['@storybook/addon-a11y'] в main.ts. Після цього кожен 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, deployment на кожен merge в main.

Строки

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