הגדרת Storybook: תיעוד חי של רכיבי UI שנעשה נכון

הבעיה: תיעוד רכיבי UI ללא כאב

הצוות שלך גדל, הרכיבים מתרבים. מעצב מציע וריאנט חדש לכפתור, מפתח בונה אותו, אבל הווריאנט הישן כבר בשימוש בשלושה מקומות. התיעוד הופך למיושן תוך שבוע. ה-QA מבזבז 3 ימים על בדיקות רגרסיה לכל שינוי. התרחיש הזה מוכר מדי. נתקלנו בו פעמים רבות, ולכן אנו מציעים הגדרת Storybook — הסטנדרט לתיעוד חי ופיתוח רכיבי UI מבודדים. לאחר אימוץ עם Storybook ו-Chromatic, בדיקות רגרסיה חזותיות מקצרות את זמן הרגרסיה מ-3 ימים לשעתיים, עם כיסוי רכיבים המגיע ל-95%. חברות המשתמשות ב-Storybook מדווחות על 40% פחות באגים בסביבת הייצור.

Storybook הוא סביבה שבה כל רכיב מתואר עם Stories: מצבים בודדים (כפתור ברירת מחדל, מושבת, טוען, עם אייקון). מפתחים רואים את כל המצבים בבת אחת, מעצבים בודקים ללא השקת האפליקציה, QA בודק כל מצב בנפרד. הוא תומך ב-React, Vue, Angular, Svelte, Web Components — כל טכנולוגיה מודרנית. במהלך השנים שילבנו את Storybook ב-35 פרויקטים: מסטארטאפים ועד ארגונים גדולים. הלקוחות שלנו מפחיתים את תקציב בדיקות הרגרסיה שלהם בעד 80%.

איך Storybook מאיץ פיתוח רכיבים

ההתקנה בפרויקט קיים אורכת דקה:

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

לאחר האתחול, נוצרות תיקיות npx storybook@latest init # Storybook определит фреймворк автоматически (config) ו-.storybook/ (דוגמאות). אנו משכתבים את התצורה עבור הפרויקט שלך: מחברים addons, decorators, וסגנונות גלובליים.

תצורה בסיסית ל-React + Vite + TypeScript

הגדרת stories/ ו-main.ts היא השלב המרכזי. היא קובעת כיצד addons ו-stories יעבדו.

// .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>
  ),
}
"}

עבור רכיבים מורכבים כמו טבלת נתונים, ניתן להוסיף בדיקות אינטראקציה באמצעות פונקציית preview.ts:

// 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 שעות וחסך $10,000 לרבעון. כעת הצוות מוסיף רכיבים חדשים ל-Storybook בעצמו.

השוואה: Storybook מול תיעוד ידני

מה מקבלים כתוצאה?

• תיעוד חי של כל רכיבי ה-UI עם תצוגה מקדימה אינטראקטיבית
• בדיקות נגישות (a11y) אוטומטיות דרך addon-a11y
• בדיקות רגרסיה חזותיות דרך Chromatic — כל שינוי מפוקח
• מדריך למפתחים להוספת רכיבים חדשים ל-Storybook
• פריסת build סטטי לאחסון שלך (GitHub Pages, Netlify, השרת שלך)
• הכשרת צוות — סדנה של שעתיים לעבודה עם Storybook

איך לשלב את Storybook עם Chromatic?

לבדיקות רגרסיה חזותיות, אנו מחברים את Chromatic. הוא מצלם אוטומטית את כל ה-Stories בכל commit ומשווה אותם לקו הבסיס. אם נמצאו הבדלים, הוא שולח הודעה ל-Slack או למייל. ההתקנה אורכת כשעה: אנו רושמים את הפרויקט, מוסיפים את ה-token ל-CI, ומריצים את ה-build.

בעיות טיפוסיות באימוץ Storybook

ניסיון ותוצאות

אנחנו צוות עם למעלה מ-10 שנות ניסיון בפיתוח frontend. במהלך השנים שילבנו את Storybook ב-35 פרויקטים: מסטארטאפים ועד ארגונים גדולים עם Angular, React, Vue ו-Svelte. הלקוחות שלנו מדווחים על הפחתה של 40% בזמן ה-QA ועלייה של 25% במהירות פיתוח הרכיבים. Storybook מהיר פי 3 מתיעוד ידני להטמעת מפתחים חדשים. אנו מבטיחים תוצאות — התיעוד שלך יהיה חי ותמיד מעודכן. צור קשר לבדיקת הרכיבים שלך וקבל הצעה מסחרית עם לוחות זמנים מדויקים.

מה אנחנו עושים turnkey

1. ניתוח הטכנולוגיה והרכיבים שלך. קביעה אילו addons נדרשים.
2. התקנה והגדרה של Storybook עם כל התלויות (Vite, TypeScript, CSS framework).
3. כתיבת Stories לרכיבים קיימים עם controls ו-actions.
4. הגדרת תיעוד אוטומטי דרך // .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 ודפי MDX.
5. שילוב בדיקות רגרסיה חזותיות (Chromatic).
6. פריסת build סטטי לאחסון (GitHub Pages, Netlify, השרת שלך).
7. הכשרת הצוות שלך — סדנה מעשית של שעתיים.

לוחות זמנים ותקציב

לוחות הזמנים מחושבים בנפרד עבור הפרויקט שלך. הגדרה בסיסית אורכת מ-0.5 ימים; כתיבת Stories לרכיבים קיימים אורכת 1–3 שעות לכל 10 רכיבים. תקציב טיפוסי לפרויקט בינוני מתחיל ב-$2,000. אנו נותנים הערכה מדויקת לאחר בדיקת הקוד שלך. הזמן הגדרת Storybook turnkey — פנה אלינו, ונחזור אליך תוך יום.