Ocean Road 문서 사이트를 만들었습니다 — Storybook 옆에 새 집 하나

Photo by Europeana on Unsplash — Photo by **Europeana** on **Unsplash**

Storybook만으로는 부족했던 것 Rspress를 선택한 이유 무엇을 만들었나 Storybook과 연결하기 배포 — S3에서 GitHub Pages로 마치며

개발을 하다 보면 이런 순간이 온다.

컴포넌트를 만들었고, Storybook에서 클릭해보면 잘 동작한다. 그런데 막상 다른 사람이 써보려 하면 "어떻게 설치해요?", "다크모드 지원하나요?", "디자인 토큰 변수 이름이 뭐예요?" 같은 질문이 돌아온다. Storybook이 없는 건 아닌데, 글로 된 설명이 없다.

Ocean Road도 같은 상황이었습니다.

Storybook만으로는 부족했던 것

Ocean Road는 COLDSURF의 디자인 시스템 모노레포입니다. 웹 컴포넌트, React Native 컴포넌트, 디자인 토큰을 하나의 저장소에서 관리하고 있습니다. Storybook은 컴포넌트를 눈으로 확인하고 인터랙션을 테스트하기에는 훌륭합니다.

하지만 Storybook이 잘 못하는 게 있습니다. "설치하려면 어떻게 해야 하나", "테마를 어떻게 적용하나", "이 컴포넌트의 props가 전부 뭔가" 같은 서술형 문서입니다. 스토리 파일에 args를 잔뜩 써놓는 것도 방법이지만, 결국 읽기 불편합니다.

그래서 별도 문서 사이트를 만들기로 했습니다. Storybook을 대체하는 게 아니라, 옆에 두는 개념으로.

Rspress를 선택한 이유

문서 사이트 프레임워크 선택지는 여러 개였습니다. Docusaurus, Nextra, VitePress, Rspress.

결정적인 이유는 두 가지였습니다. 첫째, 이미 모노레포가 pnpm + Turborepo로 구성되어 있어서 빌드 파이프라인에 자연스럽게 얹을 수 있는 게 중요했습니다. 둘째, RSPack 기반이라 빌드 속도가 빠릅니다.

MDX를 지원하기 때문에 마크다운에 React 컴포넌트를 직접 embed할 수도 있습니다. 디자인 시스템 문서에서 컴포넌트 예제를 직접 보여줄 수 있다는 건 꽤 실용적입니다.

무엇을 만들었나

apps/docs로 새 패키지를 추가하고, Turbo 파이프라인에 build와 dev 태스크를 등록했습니다. 이제 pnpm turbo build를 실행하면 docs도 함께 빌드됩니다.

문서 구성은 크게 세 파트입니다.

가이드 문서

Getting Started — 설치 방법, peerDependencies, 기본 사용법

Theming — ColorSchemeProvider로 감싸고 useColorScheme() 훅으로 소비하는 패턴

Responsive Design — media utility와 breakpoint 사용법

컴포넌트 API 레퍼런스

웹 기본 컴포넌트 11개(Button, Checkbox, Modal 등), 확장 컴포넌트 11개(GridCardList, Dropdown, Accordion 등), Next.js 전용 컴포넌트(AppHeader, RouteLoading 등)의 props를 전부 정리했습니다.

디자인 토큰 레퍼런스

이 부분이 가장 재밌는 작업이었습니다. 토큰 문서를 손으로 쓰면 토큰이 바뀔 때마다 문서도 같이 업데이트해야 합니다. 그래서 Style Dictionary가 생성한 dist/json/ 결과물을 읽어서 문서 페이지를 자동 생성하도록 만들었습니다. turbo.json에서 ocean-road-design-tokens#build를 명시적 의존성으로 추가해, 토큰 빌드가 먼저 완료된 뒤 docs 빌드가 실행되도록 순서를 보장했습니다.

Storybook과 연결하기

두 사이트가 서로를 모르면 사용자는 둘 중 하나만 알게 됩니다.

문서 사이트에서는 각 컴포넌트 페이지 하단에 Storybook iframe을 embed했습니다. 반대로 Storybook에서는 상단 툴바에 docs 링크를 추가했습니다. 이렇게 하면 API 레퍼런스를 읽다가 바로 인터랙티브 데모로 이동할 수 있고, 반대로도 됩니다.

docs.ocean-road.coldsurf.io → "직접 눌러보고 싶다" → Storybook으로 storybook.ocean-road.coldsurf.io → "props가 뭐였지?" → docs로

배포 — S3에서 GitHub Pages로

처음에는 S3 + CloudFront 구성을 고려했습니다. 하지만 이미 Storybook이 같은 방식으로 배포되어 있고, docs는 완전히 정적인 사이트입니다. 관리 포인트를 줄이는 편이 낫다고 판단해 GitHub Pages로 전환했습니다.

main 브랜치에 머지되면 GitHub Actions가 자동으로 pnpm turbo build --filter=@coldsurfers/docs를 실행하고 결과물을 배포합니다. 커스텀 도메인은 CNAME 파일로 docs.ocean-road.coldsurf.io를 등록했습니다.

마치며

Storybook을 처음 만들었을 때처럼, 문서 사이트를 만들고 나니 "왜 진작 안 했지"라는 생각이 드는 작업이었습니다.

아직 남은 작업도 있습니다. 타이포그래피 시스템(#117, #118)이나 React Native 컴포넌트 문서는 다음 단계로 미뤄두었습니다. 하지만 지금 당장 필요한 것들 — 설치 방법, 테마, 컴포넌트 API, 디자인 토큰 — 은 이제 글로 읽을 수 있습니다.

문서가 있으면 질문이 줄어들고, 질문이 줄어들면 컴포넌트를 더 쓰게 됩니다.