쏘카 디자인 시스템 2.0 개발기 2편: 기술로 굴리기(웹)

쏘카 디자인 시스템 2.0의 웹 기술 구현 편으로, rollup tree-shaking 최적화와 llms.txt 도입을 중심으로 라이브러리 번들링과 AI 협업 전략을 다룬다. 1편(시스템편)에서 정의한 컴포넌트 설계를 실제 npm 패키지로 배포하는 과정의 기술 선택과 함정을 상세히 기술했다.

핵심 포인트

Rollup + `sideEffects: false` 선언으로 소비자 앱의 번들에서 사용하지 않는 컴포넌트가 자동 제거되도록 tree-shaking 파이프라인 설계
Named export 강제: default export는 번들러가 re-export 추적을 포기해 tree-shaking 무력화 위험
`llms.txt` 파일을 디자인 시스템 패키지에 포함해 AI 코드 어시스턴트가 컴포넌트 사용법을 정확히 이해하도록 지원
CSS-in-JS 대신 CSS Modules + CSS 변수(토큰)를 선택해 서버 컴포넌트 호환성과 번들 크기 모두 확보
Peer dependency로 React를 선언해 소비자 앱과 React 버전 충돌 방지

상세 정리

빌드 도구 선택: Vite Library Mode vs Rollup 직접 구성 비교 후 세밀한 청크 제어를 위해 Rollup 선택
Entry point 전략: `index.ts` 단일 진입 대신 컴포넌트별 개별 entry 파일로 코드 분할 극대화
`sideEffects: false` 함정: CSS import가 있는 파일을 `false`로 선언하면 스타일이 tree-shaking되는 문제 — `"sideEffects": ["*.css"]` 패턴으로 해결
TypeScript declaration 파일 생성: `tsc --emitDeclarationOnly` + rollup-plugin-dts 조합
Storybook 연동: 빌드 결과물 대신 소스를 직접 참조하도록 별도 tsconfig 구성
llms.txt 작성 원칙: 컴포넌트명, Props 타입, 사용 예시 코드를 구조화해 AI 파싱 용이하게
CSS 토큰 레이어: 디자인 토큰을 CSS 커스텀 속성으로 export해 테마 스위칭 지원
패키지 배포 자동화: Changesets + GitHub Actions로 버전 범프·CHANGELOG·npm publish 파이프라인 구성
소비자 팀 온보딩 지표: 도입 후 첫 2주간 Storybook 접속 300% 증가, 슬랙 디자인 시스템 채널 문의 40% 감소