👉 Storybook을 도입하게 된 이유
디자이너와의 협업 과정에서 겪은 불편함
회사에서 컴포넌트 기반 개발을 하다 보면, 디자이너와의 협업은 일상이 됩니다. 새로운 디자이너분이 오시면서 디자인 시스템 도입을 시작하게 됐고 드디어 컴포넌트를 좀 더 체계적으로 관리할 수 있겠다는 기대가 생겼습니다.
사실 이런 기대가 생긴 건, 이전부터 UI 확인 과정에서 겪던 불편함이 꽤 많았기 때문이었습니다. 디자이너가 컴포넌트 UI를 확인하려면 “이 컴포넌트, 어디서 쓰이는 거죠?” 하고 개발자에게 물어본 뒤 해당 페이지로 이동해서 확인해야 했고, 간단한 UI 하나를 보기 위해 임시 테스트 페이지를 따로 만들어달라고 요청해야 하는 상황도 생겼습니다.
“modal은 Page A에서 확인해달라 하시고, tooltip은 Page B 들어가야 하고, 이건 로그인 상태에서만 보인다고 하니 계정도 받아야 하고…”
디자이너 입장에서도 UI 하나 확인하는 데에도 꽤 많은 절차와 시간이 필요했죠.
개발자 간에도 벌어지는 소소한 비극
이런 문제는 디자이너와의 협업에서만 발생하지 않았습니다. 개발자끼리도 중복된 컴포넌트를 만들거나, 기존 컴포넌트가 있는지 몰라 또 만드는 일이 생기기 시작했습니다. 그리고 새로운 사람이 투입되면 이렇게 됩니다.
“이거 이미 있는 거였어요? 저는 모르고 새로 만들었는데요…”
누군가는 분명 열심히 만들었지만 찾기 힘들고, 문서도 없고, 어디에서 어떻게 쓰였는지도 모르니 결국 또 만드는 겁니다. 그리고 그걸 또 리팩토링하고…
그래서 Storybook을 도입하게 되었다
이런 상황을 해결하려면 컴포넌트를 빠르게, 독립적으로 확인할 수 있는 도구가 필요했습니다. 게다가 웹에서 바로 볼 수 있고, 디자이너에게도 “이거 보시고 피드백 주세요” 라며 URL만 던질 수 있는 구조라면 더더욱 좋았죠.
그래서 선택한 도구가 Storybook 이었습니다.
다양한 상태의 컴포넌트를 페이지 이동 없이 한눈에 확인할 수 있고, 웹으로 배포되어 URL만 공유하면 바로 확인 가능하니까 디자이너도 개발자도 훨씬 편해졌습니다. 특히 디자인 시스템이 도입되는 시점과 맞물려 컴포넌트 관리의 체계를 잡기 위한 흐름에서 자연스럽게 함께 도입하게 되었습니다.
👉 Storybook 도입과 적용 과정
스토리북이란?
Storybook은 컴포넌트를 독립적으로 개발하고 테스트할 수 있는 UI 도구입니다. 페이지에 의존하지 않고 다양한 상태를 나눠서 볼 수 있어, 디자이너와 개발자가 UI를 빠르게 확인하고 피드백을 주고받기에 적합합니다.
또한 Controls(Args) 기능을 활용하면, 컴포넌트의 props 값을 직접 조작해보면서 텍스트 변경, 사이즈 조절 등 다양한 상태를 실시간으로 테스트할 수 있습니다.
디자인 확인뿐 아니라, 실제 동작을 눈으로 확인할 수 있다는 점이 큰 장점입니다.
프로젝트에 어떻게 적용했는지
도입하면서 가장 먼저 했던 건 디렉토리 구조를 정리하는 일이었습니다. Story 파일은 각각의 컴포넌트와 1:1로 매칭되도록 구성하여 기존 컴포넌트가 업데이트되거나 추가될 때도 일관성 있게 관리할 수 있도록 했습니다.
또한 loading, error, variant 등 컴포넌트의 다양한 상태를 분리된 스토리로 정의해서 디자이너와 함께 각 상태를 빠르게 확인하고 논의할 수 있는 환경을 만들었습니다.
추가로 Storybook의 Docs 탭을 활용해 props 정보나 사용 예시도 함께 문서화함으로써, 디자이너와 개발자 모두가 컴포넌트를 더 쉽게 이해하고 활용할 수 있는 구조를 만들었습니다.
Chromatic을 통한 배포 및 UI 리뷰
Storybook은 Chromatic을 통해 웹에 배포했습니다. 별다른 복잡한 설정 없이도 쉽게 배포할 수 있었고, 빌드가 완료될 때마다 고유 URL이 생성되기 때문에 디자이너나 팀원들에게 해당 링크를 공유해 언제든지 컴포넌트를 바로 확인할 수 있는 환경을 구성할 수 있었습니다.
Chromatic은 단순히 Storybook을 배포해주는 것뿐만 아니라, UI 변경 사항을 시각적으로 비교해주는 리뷰 기능도 제공합니다. PR을 올리면 자동으로 빌드가 되고, 어떤 컴포넌트가 변경되었는지, 시각적으로 어떤 차이가 생겼는지 쉽게 확인할 수 있는 리뷰 페이지가 생깁니다. 리뷰 기능을 이용하면 "음... 라벨의 패딩이 살짝 바꼈네?" 이런 미묘한 변화도 한눈에 볼 수 있습니다.
이 덕분에 디자이너와 리뷰어 모두, UI 변경 내용을 빠르게 확인하며 피드백할 수 있는 흐름이 자연스럽게 만들어졌습니다.
slack 웹훅 연동
Chromatic은 Slack Webhook 연동 기능도 지원하는데요, 저희는 이것을 적극 활용했습니다.
프로젝트 설정에서 Webhook URL만 입력해두면, 리뷰 생성 및 스토리북 빌드 완료 등 변경 사항 발생 시 자동으로 슬랙에 알림이 전송됩니다.
그 결과, “지금 바뀐 거 확인해보세요!”라는 말 대신 알림 하나로 팀 전체가 동시에 변경사항을 캐치할 수 있는 구조가 생겼습니다.
👉 마무리하며
Storybook을 도입한 건 단순히 “UI 문서화를 잘 해보자”는 목적만은 아니었습니다.
협업 속도는 높이고, 불필요한 커뮤니케이션은 줄이며, 누구나 쉽게 UI를 이해하고 재사용할 수 있는 환경을 만들고 싶었습니다.
컴포넌트를 독립적으로 개발하고 테스트할 수 있게 되면서 디자이너와 개발자 간의 피드백 속도도 확실히 빨라졌고 UI 변경에 대한 리뷰나 확인도 더 이상 번거로운 일이 아니게 되었습니다.
팀원 누구나 Storybook에 접속해서 컴포넌트를 직접 확인하고, 필요하면 슬랙 알림을 타고 들어가 바로 리뷰할 수 있는 흐름이 만들어졌다는 점에서 “팀 전체의 개발 경험이 한층 더 유연하고 명확해졌다”는 걸 느낄 수 있었습니다.
앞으로도 스토리북은 도입한 도구 중 가장 잘 뽑은 것 중 하나로 남을 것 같고 이런 흐름을 계속 유지하면서 팀 전체의 DX도 조금씩 끌어올려보고 싶습니다.
