사내 디자인 시스템 구축기 (Part.2)

Feb 06, 2026

Contents

1. 들어가며: "이거 색상 코드 바뀐 건가요?"2. 왜 Figma Tokens Studio였나?전체 자동화 워크플로우 정리 3. 기술적 설계 방법 1) tokens.json을 중심으로 한 토큰 관리 전략 2). tokens.json → vanilla-extract 코드 변환 스크립트 3). 자동 생성 파일 구조 설계 4. 운영 규칙: 시스템을 지키기 위한 약속 5. 도입 이후 체감한 변화 6. 앞으로의 확장 방향 7. 마치며

1. 들어가며: "이거 색상 코드 바뀐 건가요?"

디자인 시스템 foundation인 컬러와 타이포를 구축하기 전에 이런 고민을 했었습니다.

“디자인 시스템 특성상 컬러랑 타이포는 확장되고 변경될 가능성이 높지 않을까?
“이 많은 걸 코드로 옮기는 게 맞나…? 더 좋은 방법 없을까?”

처음에는 몇 개 안 되던 컬러와 타이포가 브랜드 컬러 확장, 접근성 대응, 서비스 기능 추가를 거치면서 점점 늘어나기 시작합니다. 그리고 그 변화는 대부분 작지만 잦은 변경의 형태로 찾아옵니다.

컬러와 타이포는 디자인 시스템의 가장 기본 요소이면서 까다롭기도 한 영역입니다.

첫째, 개수가 많고 계속 늘어납니다.
컬러는 단순히 Primary 하나로 끝나지 않습니다.
Background, Text, Border, Status, Interaction 등 역할이 쪼개지면서 자연스럽게 수십 개의 토큰이 생깁니다.
타이포 역시 헤딩, 본문, 캡션, 강조 등 다양한 프리셋으로 확장됩니다.
둘째, 변경의 영향 범위가 큽니다.
컬러 하나, 타이포 하나가 바뀌면 여러 화면, 여러 컴포넌트에 영향을 줍니다.
그래서 반영이 누락되면 UI 일관성이 바로 깨집니다.
셋째, 사람이 옮기기엔 너무 반복적인 작업입니다.
Figma를 보고 → 값을 복사하고 → 코드에 붙여넣고 → 이름 맞추고
문제는 이러한 변경 사항을 개발자가 직접 코드로 옮기는 구조에서 발생합니다. 이 과정은 개발자의 기술적 판단이 거의 필요 없는 단순 반복 작업이지만 아이러니하게도 가장 실수가 많이 발생하는 구간이기도 합니다

이번 작업은 바로 이 지점에서 출발했습니다.
컬러와 타이포처럼 앞으로도 계속 늘어나고 바뀔 수밖에 없는 영역은 수동 관리가 아니라 자동화가 필요하다고 판단했습니다.

이번 글에서는 이 반복의 굴레를 끊기 위해 Figma의 디자인 토큰을 코드(Vanilla Extract)로 자동 변환하는 파이프라인을 구축한 과정을 공유합니다.

2. 왜 Figma Tokens Studio였나?

여러 접근 방법 중 Figma Tokens Studio 플러그인을 선택했습니다.

선택 이유는 명확했습니다.

JSON 기반 관리: Figma에 정의된 스타일을 디자인 토큰(JSON) 형태로 관리 및 추출이 가능합니다.
GitHub 동기화: 플러그인에서 버튼 하나만 누르면 GitHub 저장소에 변경 사항을 커밋할 수 있어 직접 동기화가 가능합니다.
단일 진실 공급원 (Single Source of Truth): 디자인 변경이 곧 코드 변경의 시작점이 됩니다.

이 구조를 선택하면서 자연스럽게 아래 원칙이 정해졌습니다.

디자인 토큰의 원천(Source of Truth)은 Figma
GitHub에는 “디자인의 결과물”만 저장
코드는 그 결과를 자동으로 소비

즉, 디자이너가 작업한 결과가 파일(tokens.json) 로 남고 그 파일을 기준으로 개발 환경에서 언제든 동일한 결과를 재현할 수 있는 구조입니다.

🚨 현실적인 제약과 전략: Free Version 활용기

Tokens Studio 유료 버전은 여러 파일로 토큰을 분리해 관리할 수 있지만 현재는 무료 버전을 사용했기 때문에 단일 파일(tokens.json)만 지원된다는 제약이 있었습니다.

하지만 이를 단점이 아닌 강력한 규칙으로 활용했습니다. 모든 변경 사항이 오직 하나의 tokens.json 파일에 기록되므로 관리 포인트가 명확해지는 효과를 얻었습니다."

전체 자동화 워크플로우 정리

현재 구축한 자동화 흐름은 다음과 같습니다.

디자이너가 Figma에서 컬러/타이포 스타일을 수정하거나 추가
Tokens Studio 플러그인에서 Import & Commit 실행
GitHub 저장소에 tokens.json 파일이 자동 커밋
개발자가 로컬에서 git pull
npm run tokens:generate 실행 (token 코드로 변환 script 실행)
컬러/타이포 토큰 코드 자동 생성 (src/tokens/colors.css.ts, typography.css.ts)
코드에서 생성된 토큰 import 후 사용

이 플로우를 통해 디자인 변경이 코드까지 안정적으로 전달됩니다. 가장 중요한 점은 토큰 값을 개발자가 직접 옮기는 단계가 없다는 것입니다.

3. 기술적 설계 방법

1) tokens.json을 중심으로 한 토큰 관리 전략

free version 제약 사항으로 토큰 저장 방식은 단일 파일(tokens.json)을 사용했습니다.

tokens.json은 Tokens Studio가 자동 생성/관리
로컬에서 직접 수정하지 않도록 규칙화
Figma → Tokens Studio → GitHub 커밋이라는 단일 흐름 유지

이렇게 한 이유는 “토큰을 어디서 관리해야 하는지”를 명확히 하기 위해서입니다.
이 규칙이 없으면 자동화 파이프라인은 쉽게 무너질 수 있습니다.

2). tokens.json → vanilla-extract 코드 변환 스크립트

자동화의 핵심은 scripts/tokens-to-code.js 스크립트입니다

이 스크립트는 tokens.json을 읽어 실제 서비스 코드에서 바로 사용할 수 있는 형태로 토큰을 변환합니다.

구현 시 고려한 주요 포인트는 다음과 같습니다.

중첩 구조 토큰 재귀 탐색
Tokens Studio에서 생성되는 토큰은 계층 구조를 가지기 때문에 깊이에 상관없이 모든 토큰을 탐색할 수 있도록 재귀 로직을 사용했습니다. findTokensByType() 함수로 nested 구조에서도 토큰 탐색이 가능합니다.
토큰 참조(reference) 해석
"변환 스크립트에서 가장 공을 들인 부분은 참조 해결이었습니다.
{fontFamilies.pretendard} 같은 참조 형태를 실제 값("Pretendard")으로 치환하지 않으면 생성된 코드가 바로 사용 불가능해집니다.
그래서 변환 과정에서 참조를 모두 해석하도록 구현했습니다. Figma에서는 primary-color가 blue-500을 참조하고, blue-500은 #e7effc를 참조하는 식의 중첩 구조를 가집니다.
스크립트가 단순히 JSON을 읽는 것을 넘어, {global.blue.500} 같은 참조 문자열을 발견하면 재귀적으로 실제 값을 찾아내도록 구현하여 런타임에는 순수한 값만 남도록 최적화했습니다."
타입별 변환 전략 분리
변환 결과물은 토큰의 성격에 따라 다른 자료구조를 택했습니다.
- Colors: 단일 값으로 쓰이는 경우가 많아 Tree-shaking이 용이하도록 개별 export const 상수로 변환했습니다.
  - 형식:
    export const blue_100 = '#e7effc';
    export const blue_500 = '#85aeef';
  - 사용법:
    import { blue_100, blue_500 } from '@/tokens/colors.css';
- Typography: vanilla-extract의 styleVariants 형태로 변환했습니다. 이런 방식으로 구성한 이유는 타이포가 단일 값이 아니라 속성 묶음으로 한번에 적용되어야 하기 때문입니다. font-size, weight, height 등을 하나의 이름으로 묶어두면 타이포를 하나의 “프리셋”으로 관리할 수 있게 해주고 UI 전반에서 일관된 사용을 가능하게 합니다.
  - 형식:
```
export const typography = styleVariants({
  head1_b_36: {
    fontFamily: 'Pretendard',
    fontWeight: '700',
    fontSize: '36px',
    lineHeight: '52px',
  },
  // ...
});
```
  - 사용법:
    import { typography } from '@/tokens/typography.css'; <div className={typography.head1_b_36}>제목</div>

3). 자동 생성 파일 구조 설계

변환 결과물은 아래 파일들로 생성됩니다.

tokens.json
Figma Tokens Studio가 자동 생성하는 디자인 토큰 원본 파일
수동 수정 금지
src/tokens/index.ts
토큰 관련 export를 통합 관리하는 엔트리 파일
src/tokens/colors.css.ts
컬러 토큰을 export 상수 형태로 변환한 자동 생성 파일
scripts/tokens-to-code.js 토큰 변환 스크립트를 통해 변환된 컬러 토큰 예시
src/tokens/typography.css.ts
타이포 토큰을 styleVariants 형태로 변환한 자동 생성 파일

이 파일들은 모두 명령어 실행을 통해서만 생성되며 직접 수정하지 않는 것을 원칙으로 합니다.

4. 운영 규칙: 시스템을 지키기 위한 약속

자동화는 구현보다 운영 규칙이 더 중요하다고 생각했기 때문에 이 시스템이 유지되도록 다음과 같은 규칙을 정했습니다.

수동 수정 금지
- tokens.json은 오직 Figma 플러그인을 통해서만 수정합니다.
- 자동 생성된 colors.css.ts, typography.css.ts는 절대 손대지 않습니다. (수정하더라도 다음 변환 시 덮어씌워집니다.)
Single Source of Truth
- 코드가 아닌 Figma가 디자인의 원천입니다. 코드에 급하게 색상을 하드코딩하지 않습니다.
Sync Process
- 디자인 변경 시: Figma 수정 → Plugin Sync → GitHub Commit
- 개발 적용 시: git pull → npm run tokens:generate

5. 도입 이후 체감한 변화

가장 큰 변화는 작업 방식의 변화였습니다.

컬러/타이포 추가에 대한 심리적 부담 감소
리뷰에서 값 복사가 아닌 구조와 의도를 이야기하게 됨
디자이너와 개발자가 같은 토큰 파일을 기준으로 대화 가능

무엇보다 사람이 반복 작업을 하며 실수할 가능성이 높은 영역을 시스템이 대신 처리해주게 된 점과 토큰 관리의 비효율성 제거가 가장 큰 수확이었습니다.

6. 앞으로의 확장 방향

현재 구조는 “지금 팀 상황에서 유지 가능한 자동화”를 기준으로 설계했습니다.
이후 필요에 따라 다음 단계로 확장할 수 있다고 생각하고 있습니다.

CI에서 tokens.json 변경 감지 후 자동 변환 (현재는 터미널에서 스크립트 변환 명령어 입력이 필요하기 때문에 이 과정도 Git hook 또는 CI/CD를 통해 대체할 수 있을 거라 생각합니다)
다크 모드 등 테마 확장 (createTheme 옵션)
spacing, radius 등 추가 토큰 타입 지원

7. 마치며

이번 자동화 작업은 단순히 편해지기 위한 개선이 아니라 변화가 많아질 것을 전제로 한 구조 설계였습니다.

컬러와 타이포는 앞으로도 추가 및 수정될 가능성이 높기 때문에 그 변화를 사람이 감당하는 대신 시스템이 자연스럽게 흡수하도록 만드는 것이 이번 설계의 가장 큰 목표였습니다. 이 구조를 기반으로 디자인 시스템을 더 안정적으로 확장해 나갈 예정입니다!