디자인 토큰 중복 없애기

우리 회사는 여러 개의 프로젝트 레포지토리를 운영하고 있는데, 모바일 앱, 웹 서비스 등 각각의 프로젝트마다 Tailwind config 파일이 있었고, 모든 파일에 동일한 디자인 토큰 값들이 중복되어 있었다. 문제는 디자인 토큰이 변경될 때마다 각 레포의 tailwind.config.js에 하드코딩된 값을 일일이 수정해야 했다는 점이었다. 입사 후 처음 디자인팀과 진행한 회의에서 여러 레포를 일일이 수정해야 하는 비효율이 논의되었고, 이를 개선해보고자 하였다.

해결책: 디자인 토큰을 패키지로 분리하기

중복된 토큰을 한 곳에서 관리할 수 있는 구조를 만들기 위해 여러 고민을 했었는데, 결론적으로는 npm 패키지로 분리하는 게 가장 명확했다. 마침 Tailwind v4로 마이그레이션을 마친 상태였고, @theme 디렉티브를 통해 CSS 변수 기반으로 토큰을 정의할 수 있었다. 즉, tailwind.config.js 대신 순수 CSS 파일만으로 토큰을 선언하고, 각 프로젝트에서 @import 한 줄로 공통 스타일을 가져올 수 있게 됐다.
(Tailwind v4 마이그레이션 과정은 별도 글에서 정리했다.)

패키지 저장소 구조 잡기

나중에 디자인 시스템 컴포넌트도 여러 앱에서 공통으로 쓸 수 있도록 확장할 계획이 있었기 때문에, Yarn Workspace 기반의 모노레포 구조로 구성했다.

company-packages/
├── packages/
│   ├── themes/        # 디자인 토큰 패키지
│       ├── src/
│       │   ├── brands/
│       │   │   ├── mobile/   # 모바일 앱용
│       │   │   └── web/      # 웹용
│       ├── package.json
│       └── README.md
│  
├── scripts/
│   ├── publish.js         # 배포 자동화
│   ├── publish-all.js
│   └── test-publish.js
└── package.json           # 루트 workspace 설정

브랜드별 커스터마이징

우리 서비스는 여러 브랜드사와 제휴를 하고 있어서, 같은 앱이라도 브랜드별로 색상이나 테마를 다르게 보여줘야 하는 경우가 있다. 이런 요구사항을 위해 공통 모바일 토큰을 그대로 유지하면서, 특정 제휴 브랜드만 CSS 변수 레벨에서 색상 토큰을 오버라이드할 수 있는 구조를 만들었다.

:root[data-brand="PARTNER_A"] {
  --color-filled-red: var(--color-red01);
}

사용하는 앱의 HTML 루트 엘리먼트에 data-brand 속성만 지정해주면 된다.

<html data-brand="PARTNER_A">

배포 자동화 스크립트

패키지를 직접 배포하다 보니, 버전을 올리고 커밋하고 태그를 만드는 과정에서 휴먼 에러가 발생할 여지가 있었다. 이런 반복적인 과정을 줄이기 위해 배포 자동화 스크립트를 만들었다.

{
  "scripts": {
    "publish:themes:patch": "node scripts/publish.js themes patch",
    "publish:themes:minor": "node scripts/publish.js themes minor",
    "publish:themes:major": "node scripts/publish.js themes major"
  }
}

스크립트가 하는 일

1. package.json의 버전을 자동으로 올리고

- patch: `2.0.2` → `2.0.3`
- minor: `2.0.2` → `2.1.0`
- major: `2.0.2` → `3.0.0`

2. 변경사항을 커밋하고 태그를 생성한 다음

   git add .
   git commit -m "chore: release @company@2.0.3"
   git tag @company-theme@2.0.3

3. npm publish로 GitHub Packages에 배포
4. 마지막으로 main 브랜치와 태그를 push

덕분에 실수 없이, 누구나 같은 방식으로 배포할 수 있게 되었다.

GitHub Packages 인증 설정

팀원분들이 패키지를 설치하려면 GitHub 인증이 필요했다.

1. GitHub Personal Access Token 생성
2. 프로젝트 루트에. npmrc 파일 생성

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

3. 환경변수 설정

export NPM_TOKEN=ghp_xxxxxxxxxxxxx

터미널을 재시작할 때마다 토큰이 초기화되는 문제가 있었다. 매번 수동으로 입력해야 했기 때문에, macOS의 Keychain을 사용해 토큰을 자동으로 불러오는 방식으로 해결했다.

결과

Before
패키지화를 하기 전에는 단 하나의 색상만 수정해도 모든 레포지토리의 tailwind.config.js를 열어 같은 값을 반복 수정해야 했다. 색상 하나 바꾸려면 → 모든 레포 수정 + 배포 필요 -> 작업 시간이 늘어나고, 실수 가능성도 높았다.

After
이제는 모든 프로젝트가 공통 패키지의 토큰을 그대로 참조한다.

/* app.css */
@import '@company/themes/mobile';

레포 A: @import '@company/themes/mobile';
레포 B: @import '@company/themes/mobile';
레포 C: @import '@company/themes/web';

색상 하나를 바꾸려면 themes 패키지에서 변수 값을 수정하고 yarn publish:themes:patch로 배포한 뒤, 각 레포에서 yarn upgrade @company/themes를 실행하면 끝이다.

---

이번 프로젝트를 하면서 많은 고민이 있었다. 사실 처음에는 패키지로 만드는 것이 과한 선택은 아닐까, 유지보수가 더 어려워지지는 않을까 하는 생각도 했다. 하지만 실제로 패키지로 관리하게 되면서 "한 곳에서 바꾸면 모든 곳에 반영된다" 는 신뢰가 생겼고, 디자인팀과 개발팀 모두 훨씬 더 일관된 언어로 소통할 수 있게 되어 뿌듯하다. 🙂

저작자표시 (새창열림)

'🗂 WIL' 카테고리의 다른 글

배포 프로세스 작게 개선해보기 (0)	2025.11.23
Framer Motion으로 본 Rotating Text 레이아웃 처리 방식 (0)	2025.11.16
이번 주에 알게 된 것들 (0)	2025.11.02
이미지 프리로딩을 구현하며 알게 된 것들 (4)	2025.10.25
@property (1)	2025.10.18