Storybook을 처음 구성할 때는 개발된 컴포넌트를 보기 좋게 모아두는 문서라고 생각했습니다.

버튼과 입력창, 탭, 모달을 화면에 나열하고 Props를 확인할 수 있으면 역할을 다한 것처럼 보였습니다.

하지만 디자인 시스템을 실제 프로젝트에서 사용하기 시작하니 Storybook에 남겨야 할 것은 완성된 모양보다 컴포넌트를 사용하는 기준이었습니다.

한 가지 예제로는 컴포넌트를 설명하기 어려웠습니다

버튼 하나에도 기본, 비활성화, 로딩, 아이콘 포함, 크기와 종류별 상태가 있습니다. 입력 컴포넌트에는 값이 없는 상태와 입력 중인 상태, 오류, 도움말, 읽기 전용 상태가 존재합니다.

기본 화면만 등록하면 컴포넌트가 정상적으로 보인다는 사실은 확인할 수 있습니다. 하지만 화면 개발자가 어느 Props를 사용할 수 있는지, 조합하면 안 되는 상태가 무엇인지 알기는 어렵습니다.

그래서 Story에는 실제 서비스에서 마주할 수 있는 상태를 중심으로 담기로 했습니다.

  • 기본 사용 예시와 자주 쓰는 조합
  • 빈 값, 긴 텍스트, 오류 같은 경계 조건
  • 허용되는 Props와 기본값
  • 키보드와 포커스 동작
  • 사용하면 안 되는 사례

예쁜 예시를 많이 만드는 것보다 개발자가 잘못 사용하기 쉬운 지점을 먼저 보여주는 편이 더 유용했습니다.

Figma와 코드가 만나는 검수 공간이 필요했습니다

Figma는 디자인 기준을 보여주고, React 코드는 실제 동작을 만듭니다. 두 결과가 같은지는 한쪽 도구만으로 확인하기 어렵습니다.

Storybook에서는 개발된 컴포넌트의 상태를 독립적으로 확인할 수 있습니다. 디자인팀은 색상과 간격, 상태 표현이 의도와 맞는지 보고, 개발팀은 Props와 이벤트, 접근성과 예외 상태를 함께 검증할 수 있습니다.

검수 시점을 서비스 화면이 완성된 뒤로 미루면 컴포넌트 문제와 화면 조합 문제를 분리하기 어렵습니다. 컴포넌트 단계에서 먼저 확인하면 수정 범위가 더 작고 기준도 명확했습니다.

Storybook은 개발 결과를 전달하는 마지막 단계라기보다 디자인과 개발이 중간 결과를 함께 확인하는 공간에 가까웠습니다.

변경 이력을 컴포넌트 가까이에 남겼습니다

디자인 시스템은 한 번 만들고 끝나지 않습니다. 버튼 높이가 바뀌거나 입력 오류 상태가 추가되고, 모달 동작 기준이 달라질 수 있습니다.

변경 이유와 영향 범위가 남지 않으면 기존 화면이 어떤 기준으로 만들어졌는지 추적하기 어렵습니다. 그래서 컴포넌트의 문서와 변경 이력을 구현체 가까이에 두는 방식을 검토했습니다.

Storybook Docs에는 사용 목적과 Props, 상태별 예시를 남기고, changelog에는 무엇이 바뀌었으며 어떤 화면의 확인이 필요한지 기록합니다.

단순히 최신 결과만 보여주는 것이 아니라 그 결과가 어떤 기준을 거쳐 현재 모습이 되었는지도 확인할 수 있게 하는 것이 목적이었습니다.

문서가 아니라 반복 가능한 협업 흐름이었습니다

Storybook을 운영하려면 등록 기준도 단순해야 합니다.

컴포넌트를 구현하고 Story를 추가한 뒤 개발팀이 동작을 검토하고, 디자인팀이 시각적 기준을 확인합니다. 변경사항을 기록한 다음 서비스 화면에서 사용하도록 흐름을 맞췄습니다.

Storybook이 일부 개발자만 보는 전시장에 머무르면 시간이 지나면서 실제 코드와 달라질 수 있습니다. 컴포넌트 변경과 Story 변경을 같은 작업으로 다뤄야 문서와 구현이 함께 유지됩니다.

좋은 Storybook은 예쁜 컴포넌트를 많이 보여주는 곳이 아니었습니다. 디자인팀과 개발팀, 화면 개발자가 같은 컴포넌트를 같은 기준으로 이해하도록 만드는 협업의 접점이라고 생각합니다.