React로 컴포넌트를 만들다 보면 어느 순간 이런 상황을 마주하게 된다.
<Button
size="sm"
variant="danger"
disabled
loading
onClick={handleClick}
fullWidth
iconLeft={<TrashIcon />}
/>
props가 하나둘 늘어나면서 "이거 어떻게 쓰는 거지?" 하고 직접 코드를 까봐야 하는 순간들이다.. 확인하려면 페이지에 직접 하드코딩하고, 저장하고, 브라우저 열고, 다시 되돌리는 이런 반복작업이 필요하다.
개발 속도가 느려지는 건 실력 문제가 아니라 구조 문제일 수 있다. 그 구조 문제를 해결하기 위해 나온 도구가 Storybook이다.

Storybook이란?
Storybook은 UI 컴포넌트를 앱과 완전히 독립적으로 개발하고, 시각화하고, 문서화할 수 있는 도구다.
쉽게 말하면 컴포넌트만 따로 모아둔 브라우저 환경이라고 생각하면 된다. 페이지 전체를 켜지 않아도, 특정 컴포넌트만 꺼내서 다양한 상태로 확인할 수 있다. React뿐 아니라 Vue, Angular, Svelte도 지원한다.
동작 원리
그렇다면 Storybook이 어떻게 동작하는지에 대해 알아보겠다. 우선 Storybook을 사용하려면 기존 컴포넌트 파일과 별도로 Story 파일을 작성해야 한다.
Button.tsx → 기존 컴포넌트 (그대로 유지)
Button.stories.tsx → 내가 새로 만드는 Story 파일
Story 파일에서는 "이 컴포넌트를 어떤 상태로 보여줄 것인가"를 정의한다.
// Button.stories.tsx
export default {
title: 'Components/Button',
component: Button,
tags: ['autodocs'], // 자동 문서 페이지 생성
};
export const Primary = {
args: { label: '확인', variant: 'primary' },
};
export const Disabled = {
args: { label: '확인', disabled: true },
};
export const LoadingAndDisabled = {
args: { label: '확인', disabled: true, loading: true },
};
이렇게 Story를 등록해두면 브라우저에서 각 상태를 바로 확인할 수 있고, props 값도 패널에서 실시간으로 조작할 수 있다.
자동 문서화의 원리
Storybook 내부에서는 react-docgen-typescript라는 라이브러리를 사용해서 빌드 시점에 컴포넌트의 TypeScript 타입과 JSDoc 주석을 정적으로 분석한다.
interface ButtonProps {
/** 버튼에 표시될 텍스트 */
label: string;
/** 비활성화 여부 */
disabled?: boolean;
variant: 'primary' | 'secondary' | 'danger';
}
이 타입 정보가 자동으로 Props 테이블로 변환된다. 즉, 외부 API를 호출하는 게 아니라 내가 이미 작성한 TypeScript 코드가 그대로 문서가 된다.
| 자동 생성되는 것 | 출처 |
| Props 이름 / 타입 / 기본값 | TypeScript 타입 |
| Props 설명 | JSDoc 주석 (/** */) |
| 인터랙티브 컨트롤 | args 기반 자동 생성 |
| 코드 스니펫 | Story 코드 그대로 |
사용하는 이유
그렇다면 실제로는 뭐가 좋을까?
1. 엣지 케이스를 개발 중에 잡을 수 있다
loading이랑 disabled가 동시에 오는 케이스, 페이지 개발 중엔 놓치기 쉽다. Story로 그 조합을 미리 정의해 두면 UI가 깨지는 걸 사전에 발견할 수 있다.
2. 협업이 쉬워진다
디자이너나 기획자한테 URL 하나만 던져줘도 직접 props를 조작하면서 확인할 수 있다. "피그마랑 실제 구현이 다른데요?"를 코드 없이 바로 비교 가능하다.
3. 컴포넌트 설계가 좋아진다
Story를 쓰다 보면 자연스럽게 "이 props 설계 이상한데?" 를 개발 중에 발견하게 된다. 결국 Storybook을 쓰는 것 자체가 더 좋은 컴포넌트를 만드는 훈련이 된다.
디자인 시스템과 Storybook
Storybook을 깊게 이해하려면 디자인 시스템이라는 개념을 먼저 알아야 한다. 프로젝트 규모가 커질수록 이런 문제가 생긴다.
A 페이지의 버튼은 border-radius가 8px인데, B 페이지는 4px다. 어떤 곳은 primary 색이 #3B82F6이고, 어떤 곳은 #2563EB다. 팀원이 늘어날수록 UI가 조금씩 어긋나기 시작한다.
이걸 해결하기 위해 나온 개념이 디자인 시스템이다. 디자인 시스템은 쉽게 말해 "우리 서비스는 이렇게 생겼다" 를 정의한 규칙과 도구의 집합이다.
디자인 시스템의 구성요소
1. 디자인 토큰 : 색상, 폰트, 간격, 그림자 같은 가장 기본적인 값을 변수로 정의한 것
// tokens.ts
export const colors = {
primary: '#3B82F6',
danger: '#EF4444',
gray100: '#F3F4F6',
};
export const spacing = {
sm: '8px',
md: '16px',
lg: '24px',
};
이걸 정의해두면 팀 전체가 같은 값을 사용하게 된다.
2. 컴포넌트 라이브러리 : 토큰을 기반으로 만든 재사용 가능한 UI 컴포넌트. ex) Button, Input, Modal, Toast
3. 문서 : 컴포넌트를 어떻게 쓰는지, 어떤 상태가 있는지, 언제 쓰면 안 되는지를 설명하는 가이드
그래서 Stroybook이 디자인 시스템에서 어떤 역할일까?
디자인 시스템의 세 구성요소 중 문서화 + 컴포넌트 시각화를 담당하는 게 바로 Storybook이다.
디자인 토큰 → 코드로 정의 (CSS 변수, JS 객체)
컴포넌트 → React 컴포넌트로 구현
문서 + 시각화 → Storybook ✅
Storybook이 없다면 컴포넌트를 다 만들어도 "이게 어떻게 생겼는지", "어떻게 쓰는지"를 팀원이 코드를 직접 열어봐야 알 수 있다.
Storybook이 있으면 디자인 시스템이 살아있는 문서가 된다. 코드가 바뀌면 문서도 자동으로 바뀌기 때문이다.
실제 기업 사례
국내외 많은 기업들이 Storybook으로 디자인 시스템을 외부에 공개하고 있다.
- 토스 — Toss Design System
- 카카오 — Kakao Style Guide
- GitHub — Primer
이 회사들이 Storybook을 쓰는 이유는 단순하다. 수십 명의 개발자가 같은 컴포넌트를 쓰는 환경에서 문서가 코드와 따로 노는 순간 혼란이 생긴다. Storybook은 코드 자체가 문서가 되도록 만들어주기 때문에 그 문제를 근본적으로 해결한다.
정리
| Storybook 없을 때 | Storybook 있을 때 | |
| props 확인 | 페이지에 직접 하드코딩 | Story에서 실시간 조작 |
| 팀원 공유 | 코드 직접 설명 | URL 하나로 끝 |
| 문서화 | 코드랑 따로 관리 | 코드가 곧 문서 |
| 엣지케이스 | 놓치기 쉬움 | Story로 명시적 관리 |
| 디자인 시스템 | 구성요소가 흩어져 있음 | 한 곳에서 시각화 |
마무리
처음엔 단순히 "컴포넌트 문서화 도구"로만 알고 있었는데, 디자인 시스템이라는 맥락에서 보니 왜 대기업들이 필수로 쓰는지가 이해됐다. 컴포넌트가 많아질수록, 팀이 커질수록, 문서와 코드가 따로 노는 문제가 커지고 Storybook은 그걸 구조적으로 해결하는 도구다.
props가 많아질수록 개발이 답답하게 느려지는 경험을 해봤다면 Storybook이 그 문제를 어느 지점에서 해결해 주는지 바로 와닿을 것 같다.
'💻 STUDY > Frontend' 카테고리의 다른 글
| Next.js는 React의 어떤 문제를 해결할까? (0) | 2026.06.08 |
|---|---|
| React 클라이언트 전역 상태 관리 (0) | 2026.06.07 |
| React는 왜 Suspense를 만들었을까? (1) | 2026.05.21 |
| useState의 snapshot과 batching (0) | 2026.05.17 |
| Pagination과 Infinite Scroll, React에서는 어떻게 구현할까? (0) | 2026.05.10 |