---
id: wiki-2026-0508-storybook
title: Storybook
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Storybook.js, Component Workshop, UI Sandbox]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
verification_status: applied
tags: [frontend, components, testing, design-system, react]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: Storybook 8 / React / Vue / Svelte
---

# Storybook

## 매 한 줄
> **"매 component 의 isolated workshop — 매 visual catalog + 매 interaction test + 매 a11y 의 single source"**. 2016 React Storybook (Arunoda) → 2026 Storybook 8 매 Vite-first + Test 매 first-class + 매 Chromatic 매 visual regression. 매 design-system 매 매 매 indispensable.

## 매 핵심

### 매 3 value
- **Isolation**: 매 component 의 매 props/state 의 explore 매 app context 의 X.
- **Documentation**: 매 stories 의 living spec — 매 Figma 의 ↔ 매 code 의 sync.
- **Testing**: 매 visual regression (Chromatic), 매 interaction (`play` fn), 매 a11y (axe).

### 매 file structure
- `Button.stories.tsx` 매 매 component 의 옆.
- `meta` (component, args, argTypes, parameters) + 매 export 별 매 story.
- CSF 3 (Component Story Format) 매 standard.

### 매 응용
1. Design-system component library.
2. Visual regression test (Chromatic / Loki).
3. Designer ↔ engineer collaboration.

## 💻 패턴

### Pattern 1: 매 CSF 3 매 story
```tsx
// 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,
  args: { onClick: fn() },
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'ghost'] },
    size: { control: 'radio', options: ['sm', 'md', 'lg'] },
  },
  parameters: { layout: 'centered' },
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;
export const Primary: Story = { args: { variant: 'primary', children: 'Save' } };
export const Disabled: Story = { args: { variant: 'primary', disabled: true, children: 'Save' } };
```

### Pattern 2: 매 interaction test (`play`)
```tsx
import { expect, userEvent, within } from '@storybook/test';

export const ClickIncrements: Story = {
  args: { children: 'Click me' },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);
    const btn = canvas.getByRole('button');
    await userEvent.click(btn);
    await userEvent.click(btn);
    expect(args.onClick).toHaveBeenCalledTimes(2);
  },
};
```

### Pattern 3: 매 a11y addon
```ts
// .storybook/preview.ts
import type { Preview } from '@storybook/react';
const preview: Preview = {
  parameters: {
    a11y: { config: { rules: [{ id: 'color-contrast', enabled: true }] } },
  },
};
export default preview;
// 매 axe-core 매 매 story 매 자동 audit, panel 의 violation 의 surface
```

### Pattern 4: 매 Chromatic 매 visual regression CI
```yaml
# .github/workflows/chromatic.yml
- uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    onlyChanged: true
    exitZeroOnChanges: false
```

### Pattern 5: 매 design token 의 import + 매 theme switch
```tsx
// .storybook/preview.tsx
import { withThemeByClassName } from '@storybook/addon-themes';
export const decorators = [
  withThemeByClassName({
    themes: { light: 'theme-light', dark: 'theme-dark' },
    defaultTheme: 'light',
  }),
];
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Design-system / component lib | Storybook + Chromatic — default |
| App-only, no shared component | Storybook 매 optional — 매 cost > value 의 risk |
| Vue / Svelte / Angular | Storybook 의 multi-framework 의 native support |
| 매 mobile (RN) | Storybook React Native — viable but small ecosystem |
| Lightweight alt | Ladle (Vite-only, faster), Histoire (Vue-first) |

**기본값**: Storybook 8 + Vite + interaction test + Chromatic CI.

## 🔗 Graph
- 부모: [[Design System]]
- 응용: [[Component Library]] · [[Figma-to-Code-Workflow]]
- Adjacent: [[Test_Automation]] · [[CI_CD_Pipeline]] · [[Figma]]

## 🤖 LLM 활용
**언제**: 매 component 의 stories 의 boilerplate 의 generate, 매 interaction-test 의 scaffold, 매 design-spec ↔ args 의 sync.
**언제 X**: 매 visual judgment (snapshot review) — 매 designer 의 human review.

## ❌ 안티패턴
- **매 stories 의 component 의 모든 prop combo 의 explosion** — 매 visual diff 매 noise. 매 representative 매 5-10 의 keep.
- **매 fetch / global store 의 story 의 raw use** — 매 isolation broken. 매 mock + decorator.
- **매 interaction test 의 unit test 의 replace** — 매 unit (Vitest) + 매 interaction (Storybook) 의 complement.
- **Chromatic 의 baseline 의 매 PR 매 auto-accept** — 매 visual regression 의 silent miss.

## 🧪 검증 / 중복
- Verified (Storybook 8 docs 2025, Chromatic guide, CSF 3 RFC).
- 신뢰도 A.
- 중복 risk: 매 X (unique tool).

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — CSF 3 patterns, play interaction, Chromatic, a11y 정리 |