08-pipeline-distribution — 디자인 시스템 패키지의 빌드·배포·문서·거버넌스
이 챕터가 답하는 질문: 토큰·컴포넌트·문서를 어떤 패키지 구조로 분해하고, 어떤 빌드 도구로 묶고, 어떻게 버전을 매기고, 어떻게 망가뜨리지 않고 배포하며, 어떻게 채택률을 측정할 것인가. 작성: 2026-05-19 / 분량: 7개 본문 + 인덱스
한 문장 답 (Pyramid Top)
디자인 시스템의 배포는 “모노레포(Turborepo) → 묶기(tsup) → 버저닝(Changesets) → 문서화(Storybook + Chromatic) → 거버넌스(RFC) → 측정(adoption metrics)“의 6-스테이지 파이프라인이다. 핵심은 토큰·아이콘·컴포넌트·preset·docs를 각각 독립 패키지로 분리하되, 하나의 changeset이 영향받는 패키지의 SemVer를 자동으로 올려주는 단일 배포 트랜잭션을 갖는 것이다.
Why — 왜 별도 챕터인가
토큰을 잘 정의해도, recipe를 잘 만들어도, 배포가 깨지면 사용자에게 도달하지 않는다. 디자인 시스템 팀의 80% 시간은 다음 같은 전달 문제에 쓰인다.
| 깨지는 약속 | 증상 | 해결의 단위 |
|---|---|---|
| ”한 번 publish 하면 모든 패키지가 일관된 버전” | tokens는 1.2.0인데 react는 1.1.0을 쓰고 있음 | Changesets + 워크스페이스 의존성 |
”RSC에서 <Button>이 동작” | "use client"가 빌드 후 사라져 hydration 에러 | tsup banner 옵션 / preserve directive |
| ”ESM·CJS 둘 다 지원” | Next.js는 ESM, Jest는 CJS — 같은 코드 두 곳에서 require | dual output + exports map |
| ”토큰 이름 바꿨는데 사용자가 안 깨짐” | color.brand → color.primary로 200곳 깨짐 | deprecation alias + codemod |
| ”PR마다 시각적 변화가 보임” | 디자이너가 코드 리뷰 못 함 | Chromatic visual regression |
| ”새 컴포넌트는 누가 결정?” | PR 17개가 7개월째 리뷰 대기 | RFC 절차 + 결정자(owner) |
| “이 디자인 시스템 잘 쓰이고 있나?” | 사용자 앱에 raw hex가 더 많음 | adoption metrics 자동 수집 |
이 챕터는 그 7개 문제를 7개의 본문에 1:1로 대응시킨다.
How — 어떻게 정리했나
6-스테이지 파이프라인
본문 목차 (7개)
| 번호 | 본문 | 핵심 도구·키워드 |
|---|---|---|
| 01 | 모노레포 레이아웃 | Turborepo, pnpm workspace, tokens/icons/react/preset/docs |
| 02 | 번들링과 tree-shaking | tsup, unbuild, ESM/CJS dual, “use client”, sideEffects |
| 03 | Changesets로 버저닝 | SemVer, snapshot release, prerelease mode |
| 04 | 토큰 이름 변경 deprecation | alias 유지, console.warn, codemod (jscodeshift) |
| 05 | Storybook과 문서 | Storybook 9, MDX docs, autodocs, Chromatic, Figma plugin |
| 06 | 거버넌스와 RFC | RFC 템플릿, owners, CODEOWNERS, contribution guide |
| 07 | Adoption metrics | npm downloads, raw hex grep, 토큰 vs hex 비율 |
What-if — 이 챕터의 한계
- 사내 npm registry(Verdaccio, GitHub Packages)의 세부 운영은 다루지 않는다. 공개 npm 기준으로 설명하되, 사내 레지스트리로 치환 가능한 형태로 작성한다.
- 모바일(iOS·Android) 배포 채널은 다루지 않는다. Style Dictionary로 토큰을 export 하는 지점까지는 01-tokens 챕터에서 다룬다.
- CI/CD 전체 플랫폼 비교(GitHub Actions vs CircleCI vs Buildkite)는 다루지 않는다. GitHub Actions 기준의 yaml만 제시.
Insight — 왜 Changesets가 사실상 표준이 되었나
2020년 이전의 모노레포는 Lerna의 lerna publish로 버전을 올렸다. Lerna는 모든 패키지의 버전을 한꺼번에 올리는 fixed 모드가 기본이었고, 결과적으로 바꾸지 않은 패키지도 버전이 올라가 npm 다운로드 그래프를 오염시켰다.
Changesets(2019, Atlassian)는 정확히 그 문제를 풀었다:
- 변경 의도를 작은 markdown 파일로 분리 (
.changeset/lucky-cats-jump.md) - PR 단위로 changeset 누적 (사람이 의도를 기록)
changeset version명령이 영향받은 패키지만 SemVer 올림changeset publish가 자동으로 의존 관계를 따라 publish
이 모델은 **“기능 단위 PR ↔ 의미 단위 release notes”**의 1:1 대응을 만들어 냈고, 2025년 현재 대형 React 디자인 시스템의 90% (Radix, Chakra, MUI Joy, Saas-UI, Park-UI 등)가 Changesets를 쓴다.
요약
- 디자인 시스템 배포는 모노레포 → 묶기 → 버저닝 → deprecation → docs → governance → measurement의 6-스테이지다.
- Turborepo + pnpm workspace + tsup + Changesets + Storybook + Chromatic이 2025년 사실상 표준 스택이다.
- 깨지지 않는 배포의 핵심은 (a) ESM·CJS dual +
"use client"보존, (b) 토큰 deprecation 시 alias·codemod 동봉, (c) RFC로 의사결정 가시화 셋이다.