모노레포 디자인 시스템 + 멀티 프로덕트 패키지 재편

디자인 시스템에서 "스타일 토큰"과 "컴포넌트 동작"은 변경 빈도와 변경 주체가 달라요. 토큰은 디자이너가 자주 손대고, 컴포넌트는 개발자가 손대요. 이 둘을 한 패키지에 묶으면 토큰 한 줄 바꿀 때마다 모든 컴포넌트가 함께 재배포되고, 사용처가 의존성을 다 업데이트해야 하는 비효율이 생깁니다.

그래서 처음부터 두 패키지로 분리했어요. core는 Button·Modal·Accordion 같은 UI 컴포넌트의 동작과 구조, theme은 색상·타이포그래피·간격 같은 디자인 토큰. core는 theme의 토큰 인터페이스를 import해서 쓰지만 구체 값은 알지 못해요. theme이 갱신돼서 새로 배포되면, 사용처는 theme만 업데이트하면 되고 core는 그대로예요.

이 분리의 진짜 가치는 멀티 브랜드 / 라이트·다크 모드 전환에서 드러났어요. 하나의 core 위에 여러 theme을 갈아끼울 수 있는 구조가 자연스럽게 만들어져서, 나중에 멀티 프로덕트로 확장할 때 그대로 활용됐습니다. 변경 빈도가 다른 두 가지를 한 패키지에 묶지 마라 — 모노레포 분리 기준의 가장 일반적인 원칙이고, 본 케이스에서 가장 잘 들어맞은 사례였어요.

조직 내 신규 프로덕트가 연이어 출시되면서, 단일 core/theme로 감당이 안 되는 신호가 보였어요. 프로덕트 A는 둥근 모서리가 표준이고 B는 직각, A는 따뜻한 톤·B는 차가운 톤 같은 차이가 누적되면서, 한 컴포넌트 안에 if (product === 'A') 분기가 늘어나기 시작했습니다.

그 시점에 결정해야 했어요. 지금 패키지를 자르거나, 단일 패키지에 조건 분기를 계속 쌓거나. 후자는 단기로는 빠르지만, 6개월 후 분기가 30개쯤 되면 어떤 컴포넌트든 한 번 손대기 부담스러워지는 패턴이라 위험하다고 봤어요. 그래서 선제적으로 core-{product} / theme-{product} 형태로 분리를 단행했습니다.

비용 통제가 핵심이었어요. 컴포넌트 API 시그니처를 그대로 유지한 게 결정적이었습니다. 사용처는 import { Button } from '@org/core' 를 import { Button } from '@org/core-productA' 로 바꾸기만 하면 되도록 했어요. find-and-replace로 일괄 변환이 됐고, 코드 의미를 손볼 일이 없었어요. 이 과정에서 동시에 Emotion v10 → v11 메이저 업그레이드까지 한 번에 묻어 갔어요. 어차피 import 경로를 다 만져야 하니, 같은 PR에서 v11 호환 코드로 옮기는 게 효율적이었습니다.

이 재편 덕에 한 프로덕트의 디자인 변경이 다른 프로덕트에 영향을 주지 않는 안전한 구조가 됐고, 각 프로덕트 개발자들이 자기 패키지 안에서 자유롭게 실험할 수 있는 환경이 만들어졌어요.

디자인 시스템 패키지의 사용처가 다양하다는 게 출발점이에요. 어떤 프로덕트는 Next.js 13+ 라 ESM이 자연스럽고, 어떤 사내 도구는 webpack 4 기반 CRA 라 CJS 호환이 필요하고, 빌드 스크립트는 Node에서 require 형태로 import해요. 한 포맷만 제공하면 누군가는 호환 문제로 막힙니다.

그래서 ESM과 CJS를 둘 다 빌드해서 package.json의 exports 필드로 환경에 맞춰 자동 선택되게 했어요.

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  }
}

번들러는 Rollup으로 갔어요. 이유는 셋입니다. 첫째, 라이브러리 빌드 출력 품질. Rollup은 dead-code elimination이 깔끔하고, 출력이 사람이 읽을 수 있을 정도로 단정합니다. Vite는 내부적으로 Rollup을 쓰지만 앱 개발 dev server에 최적화되어 있어 라이브러리 빌드에는 부가 설정이 필요해요. 둘째, 트리쉐이킹. 컴포넌트 30개 중 사용처가 5개만 import하면 5개만 들어가야 하는데, Rollup이 가장 안정적으로 잘 합니다. 셋째, 플러그인 생태계. emotion, TypeScript, dts, terser 등 라이브러리 빌드에 필요한 플러그인이 다 잘 정리되어 있어요.

esbuild도 검토했어요. 빌드 속도는 Rollup의 10배 이상 빠르지만, type 선언 자동 생성과 일부 트리쉐이킹 옵션에서 아직 부족했고, 라이브러리 출력의 안정성에서 Rollup이 우세했습니다. 빌드 속도는 라이브러리에서 critical path가 아니라 의사결정에서 우선순위가 낮았어요.

도입 시점이 2020~2021년 즈음이었는데, 그 시점에 모노레포 표준은 사실상 Lerna였어요. yarn workspaces와 결합해서 패키지 간 로컬 링크 + 일괄 publish 흐름을 만드는 게 일반적이었고, 우리도 그 패턴을 그대로 채택했습니다.

가치는 분명했어요. core 패키지가 변경되면 자동으로 theme도 dependent로 인식되어 빌드 순서가 정해지고, 일괄 npm publish가 한 번에 끝나는 워크플로우가 안정적이었습니다.

한계도 있었어요. 첫째, bootstrap이 느렸어요. 패키지 수가 늘면 의존성 install이 분 단위로 길어졌습니다. 둘째, 빌드 캐싱이 없어서 의존이 안 바뀐 패키지도 매번 빌드 됐어요. 셋째, Lerna 자체의 메인테이너 변동으로 한동안 정체기가 있었습니다. (이후 Nrwl이 인수해서 다시 활발해졌지만 그건 후 이야기)

지금 새로 시작한다면 pnpm workspaces + Turborepo 조합이에요. pnpm은 strict하면서 디스크 효율도 좋고, Turborepo는 빌드 그래프 분석·캐싱·원격 캐시까지 갖춰서 모노레포 핵심 운영 비용을 크게 낮춰 줍니다. Nx도 좋은 선택지인데 학습 곡선이 약간 가파르고, 단순 라이브러리 모노레포라면 Turborepo가 가성비가 좋아요.

디자이너가 Figma에서 SVG로 export하면 보통 색상이 hex 값으로 박혀 있어요. 그걸 그대로 React 컴포넌트로 만들면 라이트/다크 모드에서 색이 안 따라가는 문제가 생깁니다. 사람이 손으로 hex를 토큰 변수로 바꾸는 건 50개 100개 단위의 아이콘에선 비현실적이에요.

파이프라인은 이렇게 동작합니다. 디자이너가 SVG 파일들을 폴더에 떨어뜨려요. 스크립트를 한 번 실행하면, xml2js로 각 SVG를 XML 트리로 파싱하고, fill·stroke 속성에 들어 있는 hex 값을 미리 정의한 매핑 테이블 — #3D8BFF → var(--color-primary) 같은 — 으로 치환합니다. 그런 다음 SVG XML을 React JSX로 emit해서 컴포넌트 파일을 자동 생성해요. 결과적으로 모든 아이콘 컴포넌트가 동일한 토큰 변수를 참조하게 되니, theme이 light/dark로 바뀌면 아이콘 색도 자연스럽게 따라갑니다.

SVGR과의 차이는 "토큰 주입과 라이트/다크 인식"이에요. SVGR은 일반적인 SVG → JSX 변환을 잘하지만, 색상을 토큰으로 바꾸는 건 사용자의 후처리로 둡니다. 우리는 그 후처리를 파이프라인에 박아 넣어서, 아이콘이 들어오는 순간 시스템 일관성이 자동으로 강제되도록 했어요.

도입 효과는 두 가지였어요. 첫째, 아이콘 추가 시간 단축. 갯수가 50개든 100개든 단 한 번의 스크립트 실행으로 끝납니다. 둘째, 사람의 실수가 사라졌어요. hex 값을 손으로 옮기다가 오타가 나거나 토큰을 안 쓰는 케이스가 자동화로 원천 차단됐습니다.

디자이너가 Figma에서 토큰을 수정하면 코드에 반영되기까지 며칠이 걸리던 게 출발점이었어요. 디자이너가 슬랙에 올려주면 개발자가 hex를 일일이 옮기고, PR 만들고, 리뷰받고, 머지하는 과정이 반복됐습니다.

흐름은 이렇게 자동화했어요. 디자이너가 Figma 플러그인이나 export 도구로 디자인 토큰을 JSON으로 뽑아냅니다. 우리 모노레포에는 그 JSON을 받아 TypeScript theme 파일로 변환하는 스크립트가 있고, 디자이너가 토큰을 갱신했을 때 PR 한 번에 스크립트 실행 → 자동 생성된 theme 파일 변경분이 들어가요. 사람이 hex를 직접 만지지 않습니다. (※ 실제 Figma 연결 방식이 플러그인인지 Tokens Studio인지 본인 구현에 맞춰 답변)

Light/Dark 모드 설계가 가장 신경 쓴 부분이에요. 핵심 사상은 컴포넌트는 의미적(semantic) 토큰만 참조한다예요. 컴포넌트 코드에는 color.primary 가 아니라 color.text.default 처럼 의미를 담은 키를 쓰고, light theme에서 color.text.default = #1a1a1a, dark theme에서 color.text.default = #f5f5f5 같이 같은 의미 토큰이 두 모드에서 다른 값을 갖도록 매핑했어요. 결과적으로 컴포넌트 코드는 light/dark의 존재를 모르고, theme 객체를 갈아끼우는 것만으로 모드가 전환됩니다.

이 설계 덕에 다크 모드를 신규 도입했을 때 컴포넌트 코드는 한 줄도 바뀌지 않았고, 디자이너가 dark theme 토큰만 채워 넣으면 끝나는 워크플로우가 됐어요.

일반적으로 메이저 업그레이드와 패키지 재편을 같이 묶는 건 위험해요. 문제 생겼을 때 어느 쪽이 원인인지 분리가 어렵거든요. 그런데 본 케이스는 사용처가 어차피 모든 import 경로를 바꿔야 하는 상황이었어요. import styled from '@org/core' 가 import styled from '@org/core-productA' 로 바뀌는데, 그 과정에서 emotion v10의 jsx pragma → v11 방식으로 옮기는 건 같은 파일을 한 번 더 만지는 것뿐이라 추가 비용이 거의 없었습니다.

세 가지 안전 장치를 두고 진행했어요. 첫째, 시각 회귀 테스트 안전망. Storybook 기반 visual regression을 미리 충분히 깔아 둔 상태였어요. emotion 업그레이드는 클래스명 생성 방식이 미묘하게 달라서 시각 차이가 날 가능성이 있었는데, snapshot 변화가 의도된 것인지를 PR 단위로 확인할 수 있었습니다. 둘째, 점진적 전환. 한 product 패키지를 먼저 v11 + 새 import 경로로 옮기고 운영에 일주일 띄워본 뒤, 안정성이 확인된 후 다른 product로 확장했어요. 셋째, Codemod 활용. emotion v11이 제공하는 codemod를 일부 적용해서 jsx pragma·import 경로 변경을 자동화하고, 사람이 만질 부분을 줄였습니다.

결과적으로 한 분기에 걸쳐 모든 product가 v11 + 신규 패키지 구조로 전환됐고, 그 사이 운영 장애 없이 진행됐어요. 부수 효과로 번들 사이즈가 약간 줄었고, v11의 jsx 자동 변환 덕에 코드가 더 깔끔해졌습니다.