Storybook이란? — props가 많아질수록 개발이 느려진다고 느꼈다면

React로 컴포넌트를 만들다 보면 어느 순간 이런 상황을 마주하게 된다.

<Button
  size="sm"
  variant="danger"
  disabled
  loading
  onClick={handleClick}
  fullWidth
  iconLeft={<TrashIcon />}
/>

props가 하나둘 늘어나면서 "이거 어떻게 쓰는 거지?" 하고 직접 코드를 까봐야 하는 순간들이다.. 확인하려면 페이지에 직접 하드코딩하고, 저장하고, 브라우저 열고, 다시 되돌리는 이런 반복작업이 필요하다.

개발 속도가 느려지는 건 실력 문제가 아니라 구조 문제일 수 있다. 그 구조 문제를 해결하기 위해 나온 도구가 Storybook이다.

---

📖 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이 그 문제를 어느 지점에서 해결해 주는지 바로 와닿을 것 같다.