이 글은 누구를 위한 것인가
- 디자인 토큰을 여러 서비스나 플랫폼에서 공유하는 팀
- 토큰 변경이 예고 없이 프로덕션에 영향을 미쳐 문제가 생긴 경험이 있는 팀
- 디자인 시스템의 거버넌스 구조를 처음 만드는 팀 리더
들어가며
디자인 토큰이 팀 내 공유 자산이 되면 새로운 문제가 생긴다. 누군가 color.primary.default 값을 바꾸면 이를 사용하는 모든 서비스에 영향이 간다. Figma에서 바꾼 값이 코드에 즉시 반영되면 QA 없이 프로덕션에 배포될 수 있다.
소프트웨어 개발에서 API 변경 관리에 시맨틱 버저닝을 쓰듯, 디자인 토큰에도 동일한 원칙을 적용할 수 있다. 이 글에서는 Git 기반 토큰 버전 관리와 팀 워크플로우를 어떻게 설계할지 설명한다.
이 글은 bluefoxdev.kr의 디자인 시스템 거버넌스 를 참고하고, 토큰 버전 관리 관점에서 확장하여 작성했습니다.
1. 토큰 변경의 영향도 분류
1.1 변경 유형별 위험도
패치 (Patch): 하위 호환
- 기존 토큰 값 미세 조정 (색상 명도 1~2% 조정)
- 오탈자 수정
- 코드 주석 추가
→ 영향도: 낮음, 즉시 적용 가능
마이너 (Minor): 하위 호환 추가
- 새로운 토큰 추가
- 기존 토큰 별칭(alias) 추가
→ 영향도: 중간, 새 토큰만 영향
메이저 (Major): 브레이킹 체인지
- 토큰 이름 변경 또는 삭제
- 값의 의미론적 변경 (primary → brand)
- 계층 구조 변경
→ 영향도: 높음, 전체 서비스 영향
1.2 브레이킹 체인지 판단 기준
// 브레이킹 체인지 예시
// Before v1.x
{
"colors": {
"primary": "#3B82F6" // 직접 사용
}
}
// After v2.0 - BREAKING CHANGE
{
"color": { // 키 이름 변경
"primary": {
"default": "#3B82F6", // 중첩 구조 변경
"hover": "#2563EB"
}
}
}
2. Git 기반 토큰 버전 관리
2.1 토큰 저장소 구조
design-tokens/
├── src/
│ ├── primitive/
│ │ ├── color.json
│ │ ├── spacing.json
│ │ └── typography.json
│ ├── semantic/
│ │ ├── color.json
│ │ └── spacing.json
│ └── component/
│ ├── button.json
│ └── input.json
├── dist/
│ ├── css/variables.css
│ ├── js/tokens.js
│ └── json/tokens.json
├── CHANGELOG.md
└── package.json ← 버전 관리
2.2 npm 패키지로 배포
// package.json
{
"name": "@company/design-tokens",
"version": "2.1.0",
"main": "dist/js/tokens.js",
"exports": {
"./css": "./dist/css/variables.css",
"./json": "./dist/json/tokens.json"
},
"scripts": {
"build": "style-dictionary build",
"release": "npm run build && npm publish"
}
}
소비하는 팀은 버전을 명시적으로 고정:
// 소비 서비스의 package.json
{
"dependencies": {
"@company/design-tokens": "^2.1.0" // ^ = 마이너 버전까지 자동 업데이트
}
}
2.3 시맨틱 버저닝 자동화
# .github/workflows/release.yml
name: Release Tokens
on:
push:
branches: [main]
paths:
- 'src/**/*.json'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Detect breaking changes
id: breaking
run: |
node scripts/detect-breaking-changes.js
echo "is_breaking=$?" >> $GITHUB_OUTPUT
- name: Bump version
run: |
if [ "${{ steps.breaking.outputs.is_breaking }}" = "1" ]; then
npm version major
elif git log --oneline -1 | grep -q "feat:"; then
npm version minor
else
npm version patch
fi
- name: Build and publish
run: |
npm run build
npm publish
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
3. Figma-코드 토큰 양방향 싱크
3.1 Token Studio 연동
// Figma Token Studio 설정
{
"syncProviders": {
"github": {
"repository": "company/design-tokens",
"branch": "main",
"filePath": "src/",
"baseUrl": "https://api.github.com"
}
}
}
3.2 싱크 방향 정책
Figma → GitHub (디자이너 주도)
- 디자이너가 Figma에서 토큰 값 변경
- Token Studio로 PR 생성
- 리뷰 후 머지
GitHub → Figma (개발자 주도)
- 개발팀이 새 토큰 추가
- Figma에 자동 반영
- 디자이너 확인 후 사용
⚠️ 동시 수정 방지:
- 브레이킹 체인지는 반드시 디자이너-개발자 협의 후 진행
- Figma 변경은 항상 PR로 리뷰
4. 팀 규모별 거버넌스 구조
소규모 팀 (5명 이하)
- 단일 토큰 파일
- main 브랜치 직접 수정 허용
- 월 1회 토큰 리뷰 미팅
중간 팀 (5~30명)
- 토큰 저장소 분리
- PR + 리뷰 필수
- 토큰 변경 슬랙 알림
- 버전별 CHANGELOG 관리
대규모 팀 (30명 이상)
- 전담 디자인 시스템 팀
- RFC(Request for Comments) 프로세스
- 브레이킹 체인지 6주 전 공지
- 마이그레이션 가이드 문서화
- 폐기(Deprecated) 토큰 유예 기간 관리
CHANGELOG 관리
## [2.1.0] - 2026-04-23
### Added
- `color.brand.gradient.primary`: 브랜드 그라디언트 추가
### Changed
- `color.primary.default`: #3B82F6 → #2563EB (명도 조정)
### Deprecated
- `color.blue` → `color.primary` 사용 권장 (v3.0에서 제거 예정)
## [2.0.0] - 2026-03-01 ⚠️ BREAKING CHANGE
### Breaking Changes
- 모든 색상 토큰 계층 구조 변경
- `colors.*` → `color.*` (단수형으로 통일)
- 마이그레이션 가이드: docs/migration-v2.md
마무리: 토큰 거버넌스 핵심 원칙
- 변경 전 영향도 분류: 패치/마이너/메이저 구분이 혼란을 막는다
- 자동화된 배포: 수동 배포는 실수와 지연을 유발한다
- 브레이킹 체인지 공지: 사전 공지와 마이그레이션 가이드는 필수
- Changelog 관리: 변경 이력이 없으면 버그 추적이 불가능하다
디자인 토큰 버전 관리는 오버엔지니어링처럼 보일 수 있다. 하지만 토큰을 공유하는 서비스가 3개만 넘어가도 이 구조의 필요성을 실감하게 된다.