디자인 토큰 관리 가이드: Figma와 코드에서 UI 기준을 일관되게 운영하는 방법
직접 답하면, 페이지마다 다른 회사처럼 보이는 문제는 ‘디자인 감각’보다 ‘UI 값을 관리하는 방식’에서 시작되는 경우가 많습니다. 버튼 색상은 Figma에 있고, 실제 코드는 CSS 파일마다 따로 쓰이며, 외주 개발자가 만든 관리자 화면은 또 다른 회색과 여백을 쓰는 식입니다. 디자인 토큰 관리는 이런 값을 색상표·가이드 문서에 머무르게 하지 않고, Figma와 코드가 함께 쓰는 운영 기준으로 만드는 일입니다.
사업 홈페이지, SaaS, 관리자 화면, 모바일 앱이 함께 커지는 팀이라면 디자인 토큰을 ‘예쁜 UI를 위한 디자이너 도구’로만 보면 안 됩니다. 토큰은 브랜드 신뢰도, 개발 속도, 리브랜딩 비용, 다크 모드 적용 범위, 외주 개발 후 유지보수 품질을 좌우하는 작은 API에 가깝습니다. W3C Design Tokens Community Group의 2025.10 포맷 문서는 디자인 토큰을 서로 다른 도구 사이에서 교환할 수 있는 파일 형식으로 다루며, 토큰을 플랫폼에 독립적인 디자인 결정으로 설명합니다. 다만 해당 문서는 W3C 표준 트랙의 Recommendation은 아니므로, 실무에서는 ‘공통 언어로 참고하되 팀의 도구와 배포 체계에 맞게 적용한다’는 태도가 필요합니다. ([w3.org](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/))
1. 디자인 토큰은 색상표가 아니라 ‘화면 기준의 API’입니다
디자인 토큰은 색상, 폰트, 간격, 라운드, 그림자, 투명도, z-index, 모션 시간처럼 UI에서 반복되는 결정을 이름 붙여 저장한 값입니다. 예를 들어 #2563eb를 여러 CSS 파일에 직접 쓰는 대신 color-brand-primary, color-bg-primary, button-primary-bg처럼 용도와 계층을 가진 이름으로 관리합니다. W3C DTCG 포맷에서는 토큰이 이름, 값, 타입을 가지며 JSON 기반으로 표현됩니다. 또한 alias/reference를 통해 한 토큰이 다른 토큰을 참조할 수 있고, composite token으로 typography나 shadow처럼 여러 하위 값을 묶을 수도 있습니다. ([w3.org](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/))
대표나 PM 입장에서 중요한 포인트는 이것입니다. 토큰이 있으면 “이번에 브랜드 파란색을 바꾸자”가 “랜딩 페이지 17곳, 관리자 CSS 9곳, 모바일 앱 4곳을 찾아서 수정하자”가 아니라 “승인된 토큰 값을 바꾸고 영향 범위를 확인한 뒤 배포하자”로 바뀝니다. 토큰은 디자인과 개발 사이의 말 번역 비용을 줄이는 장치입니다.
| 항목 | 문서형 가이드만 있을 때 | 토큰으로 운영할 때 |
|---|---|---|
| 브랜드 색상 변경 | 디자이너가 가이드 수정, 개발자는 화면별 수동 반영 | semantic token 변경 후 빌드·QA·배포 경로로 반영 |
| 다크 모드 | 화면별 예외 CSS 증가 | mode 또는 theme 단위로 값 교체 |
| 외주 인수인계 | “이 색은 왜 다른가요?”를 코드에서 역추적 | 토큰 목록과 사용 위치로 기준 확인 |
| 관리자 화면 확장 | 새 기능마다 버튼·폼 스타일 재결정 | 컴포넌트가 기존 토큰을 재사용 |
2. 어떤 값을 토큰으로 만들고, 어떤 값은 만들지 말아야 할까
처음부터 모든 숫자와 색을 토큰화하면 오히려 운영이 어려워집니다. 작은 팀은 ‘반복되고, 변경 가능성이 있고, 브랜드 또는 사용성에 영향을 주는 값’부터 토큰으로 만들어야 합니다. 반대로 특정 프로모션 배너 하나에만 쓰이는 장식 값, 실험 중인 마케팅 이미지 안의 색, 임시 랜딩 페이지의 일회성 레이아웃까지 모두 토큰으로 만들면 이름만 늘고 합의 비용이 커집니다.
| 우선순위 | 토큰화 권장 항목 | 이유 | 주의할 점 |
|---|---|---|---|
| 1순위 | 브랜드 색상, 텍스트 색상, 배경, 경계선, 상태 색상 | 브랜드 신뢰와 접근성에 직접 영향 | primary, success, warning, danger의 의미를 혼용하지 않기 |
| 1순위 | 본문·제목 폰트 크기, line-height, font-weight | 가독성과 화면 밀도에 영향 | Figma text style과 코드 typography scale의 차이를 기록 |
| 2순위 | spacing scale, radius, shadow | 화면 일관성과 개발 속도에 영향 | 4px, 8px 단위 등 기본 scale을 먼저 합의 |
| 2순위 | form 상태, button 상태, table 상태 | SaaS·관리자 화면 품질에 영향 | disabled, error, focus, loading 상태를 빠뜨리지 않기 |
| 나중 | 특정 캠페인 장식 값, 단발성 이미지 색 | 재사용 가능성이 낮음 | 토큰 수를 늘리는 것보다 삭제 가능성을 열어두기 |
실무 기준: “이 값이 바뀌면 여러 화면을 같이 바꿔야 하는가?”에 예라고 답할 수 있으면 토큰 후보입니다. “이 화면에서만 쓰이고 다시 안 쓸 가능성이 높은가?”에 예라면 컴포넌트 내부 값이나 페이지 스타일로 남겨도 됩니다.
3. primitive·semantic·component 토큰을 나누는 이유
토큰 관리에서 가장 흔한 실패는 blue-500 같은 원재료 값을 화면 코드에 직접 쓰는 것입니다. 처음에는 단순해 보이지만, 브랜드 컬러가 바뀌거나 다크 모드를 붙이면 “blue-500이 텍스트인가, 배경인가, 링크인가, 버튼인가”를 알 수 없습니다. 따라서 최소 3계층으로 생각하는 편이 안전합니다.
| 계층 | 역할 | 예시 | 누가 주로 다루나 |
|---|---|---|---|
| Primitive token | 색상·간격·폰트의 원재료 | color-blue-500, gray-100, spacing-4, radius-md | 디자이너, 디자인 시스템 담당자 |
| Semantic token | UI 용도와 의미 | color-bg-default, color-text-primary, color-border-danger | 디자이너, 프론트엔드 개발자 |
| Component token | 특정 컴포넌트의 상태별 값 | button-primary-bg, input-border-focus, card-shadow-hover | 프론트엔드 개발자, PM 검수자 |
권장 흐름은 component token → semantic token → primitive token입니다. 버튼은 button-primary-bg를 쓰고, 이 값은 color-bg-brand를 참조하며, 최종적으로 color-blue-600 같은 primitive 값에 연결됩니다. DTCG 포맷도 alias/reference를 통해 반복을 줄이고 토큰 간 의미 관계를 표현하는 방식을 다룹니다. 다만 순환 참조는 오류가 되므로 “A가 B를, B가 다시 A를 참조하는 구조”가 생기지 않도록 검증해야 합니다. ([w3.org](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/))
4. Figma와 코드 중 무엇을 ‘원본’으로 둘 것인가
디자인 토큰 관리의 핵심 의사결정은 도구 선택이 아니라 원본 결정입니다. Figma가 원본인지, Git 저장소의 JSON 파일이 원본인지, 또는 Tokens Studio 같은 플러그인이 원본과 동기화를 담당하는지 먼저 정해야 합니다. 원본이 불명확하면 디자이너는 Figma에서 바꿨다고 생각하고, 개발자는 코드가 진짜라고 생각하며, PM은 배포된 화면이 왜 다른지 설명을 듣지 못합니다.
| 방식 | 적합한 팀 | 장점 | 주의할 점 |
|---|---|---|---|
| Figma Variables 중심 | 디자인 변경이 잦고 Figma 사용 비중이 큰 팀 | 디자이너가 light/dark, mobile/desktop 모드를 쉽게 확인 | 코드 반영 자동화는 별도 설계 필요, API 권한·플랜 제한 확인 필요 |
| Git JSON 중심 | 개발 배포와 리뷰 프로세스가 중요한 SaaS 팀 | PR 리뷰, 버전 관리, CI 검증이 명확 | 디자이너가 JSON 변경 흐름을 이해해야 함 |
| Tokens Studio 중심 | Figma와 Git 사이의 토큰 동기화를 빠르게 시작하려는 팀 | DTCG 포맷 선택, token set·theme 운영이 쉬움 | 플러그인 사용 규칙과 충돌 처리 기준 필요 |
| 코드 우선 | 이미 서비스가 운영 중이고 Figma가 뒤늦게 정리되는 팀 | 실제 배포 화면과 가까운 기준에서 정리 가능 | 디자인 파일의 신뢰도를 다시 회복하는 작업 필요 |
Figma는 variables, collections, modes를 통해 색상·숫자·문자열·불리언 값을 관리하고, light/dark, 언어, 디바이스 크기 같은 컨텍스트를 mode로 다룰 수 있습니다. 변수는 같은 타입의 다른 변수를 참조할 수 있어 토큰 구조를 구현하는 데 활용됩니다. ([help.figma.com](https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes)) Figma 공식 문서상 변수는 REST API와 Plugin API에서도 다뤄지지만, Variables REST API에는 엔드포인트별 권한과 플랜 제한이 있으므로 “API가 있으니 무조건 자동화 가능하다”가 아니라 계정 조건부터 확인해야 합니다. ([help.figma.com](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma))
5. 실무 추천 파이프라인: Figma → 토큰 JSON → 빌드 산출물 → 화면
웹사이트와 SaaS, 관리자 화면을 함께 운영하는 팀에는 다음 파이프라인이 가장 설명하기 쉽습니다. 디자이너는 Figma에서 변수와 모드를 관리하고, 토큰 담당자는 JSON으로 내보내거나 동기화하며, 개발자는 Style Dictionary 같은 변환 도구로 CSS variables, TypeScript export, iOS·Android 리소스를 생성합니다. Style Dictionary는 토큰을 플랫폼별로 이해 가능한 이름과 값으로 변환하는 transforms, 그리고 CSS variables 같은 산출 파일을 만드는 formats 구조를 제공합니다. ([styledictionary.com](https://styledictionary.com/reference/hooks/transforms/))
- 토큰 후보 추출: Figma와 실제 코드에서 색상, 폰트, spacing, radius, shadow를 수집합니다.
- 중복 정리: 비슷하지만 다른 회색, 15px·16px처럼 애매한 여백, 같은 역할의 다른 버튼 색을 표로 만듭니다.
- 토큰 계층 설계: primitive, semantic, component 기준으로 나눕니다.
- 원본 저장소 결정: Figma, Git JSON, Tokens Studio 중 승인 경로를 정합니다.
- 변환 설정: 웹은 CSS variables, 앱은 플랫폼 리소스, 문서는 토큰 테이블로 출력합니다.
- 배포 전 QA: 주요 화면에서 light/dark, hover/focus/error 상태, 모바일 breakpoints를 확인합니다.
웹에서는 CSS Custom Properties를 사용하면 토큰 값을 런타임 theme 전환에 활용하기 쉽습니다. MDN 문서는 custom property를 :root에 정의해 전역 참조할 수 있고, var()로 값을 사용할 수 있으며, @property로 타입·초깃값·상속 여부를 더 명시적으로 다룰 수 있다고 설명합니다. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties))
:root { --color-bg-default: #ffffff; --color-text-primary: #111827; --radius-md: 8px; --spacing-4: 16px; } [data-theme='dark'] { --color-bg-default: #0b1220; --color-text-primary: #f8fafc; } .button-primary { background: var(--color-bg-brand); border-radius: var(--radius-md); padding: var(--spacing-3) var(--spacing-4); }중요한 점은 CSS 변수 이름이 곧 프론트엔드의 공용 계약이라는 것입니다. 한 번 배포된 --color-text-primary를 의미 없이 삭제하거나 이름을 바꾸면 기존 화면이 깨질 수 있습니다. 그래서 토큰 변경도 API 변경처럼 deprecate, migration, release note가 필요합니다.
6. 네이밍 컨벤션: 예쁜 이름보다 오래 버티는 이름
토큰 이름은 디자이너와 개발자가 함께 쓰는 언어입니다. 한국어 설명은 문서에 충분히 써도 되지만, 실제 key는 CSS, TypeScript, iOS, Android로 변환될 수 있으므로 영문 소문자 중심으로 정리하는 편이 안전합니다. W3C 포맷은 토큰 이름이 JSON 문자열이고 대소문자를 구분할 수 있다고 설명하지만, 다른 언어나 도구로 변환될 때 이름 충돌이 생길 수 있으므로 대소문자만 다른 토큰은 피하는 것이 좋습니다. ([w3.org](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/))
| 규칙 | 권장 예시 | 피해야 할 예시 | 이유 |
|---|---|---|---|
| 소문자와 하이픈 사용 | color-text-primary | ColorTextPrimary, 컬러-본문 | CSS 변수와 파일명 변환이 쉬움 |
| 값보다 용도 우선 | color-bg-danger | red-button | 색이 바뀌어도 의미가 유지됨 |
| 상태 명시 | input-border-focus | input-blue | 폼 검수 시 상태 추적 가능 |
| scale은 일관되게 | spacing-1, spacing-2, spacing-4 | small-gap, big-padding | 개발자가 예측 가능 |
| 컴포넌트 범위 표시 | button-primary-bg-hover | primary-hover | 다른 컴포넌트와 충돌 방지 |
이름을 만들 때는 “값이 무엇인가?”보다 “왜 이 값이 존재하는가?”를 먼저 묻습니다. gray-500은 값이고, color-text-muted는 사용 목적입니다. 실제 화면 코드는 가능하면 semantic 또는 component token을 쓰고, primitive token은 디자인 시스템 내부에서만 직접 참조하도록 제한하는 것이 유지보수에 유리합니다.
7. 다크 모드와 리브랜딩은 토큰 구조의 실전 시험입니다
다크 모드와 리브랜딩은 디자인 토큰 구조가 제대로 되어 있는지 확인하는 가장 빠른 테스트입니다. 만약 화면 코드에 #ffffff, #111827, blue-600 같은 값이 직접 박혀 있다면 다크 모드에서 예외 처리가 폭증합니다. 반대로 color-bg-default, color-text-primary, color-border-default처럼 용도 중심으로 설계되어 있으면 mode만 바꾸어도 상당 부분이 정리됩니다.
| 상황 | 토큰이 약할 때 | 토큰이 잘 나뉘어 있을 때 |
|---|---|---|
| 브랜드 컬러 변경 | 버튼, 링크, 배너, 그래프 색을 코드에서 검색 | brand primitive와 semantic 연결을 검토 |
| 다크 모드 | 페이지별 override CSS 증가 | mode별 semantic 값 교체 |
| 관리자 테이블 확장 | 행 hover, selected, error 색을 매번 재정의 | table 상태 토큰 재사용 |
| 모바일 앱 추가 | 웹 색상표를 앱 개발자가 수동 해석 | 플랫폼별 변환 산출물 제공 |
단, 다크 모드는 색상만 바꾸는 일이 아닙니다. shadow가 어두운 배경에서 보이지 않을 수 있고, border로 계층을 다시 잡아야 할 수도 있습니다. 텍스트 대비, focus ring, disabled 상태, chart color, skeleton loading 색상까지 함께 봐야 합니다. 접근성 기준과 함께 점검하려면 디자인 시스템 접근성 통합 가이드를 함께 참고하는 것이 좋습니다.
8. 토큰 변경은 ‘디자인 수정’이 아니라 ‘배포되는 제품 변경’입니다
토큰 하나가 여러 화면에 연결되어 있으면 작은 변경도 광범위한 영향을 줍니다. 그래서 토큰 운영에는 버전 관리와 승인 절차가 필요합니다. DTCG 포맷은 $deprecated 속성으로 향후 제거될 토큰이나 사용을 권장하지 않는 토큰을 표시할 수 있는 구조를 제공합니다. 이를 팀 운영에 적용하면 “삭제 예정이지만 기존 화면 때문에 유지하는 토큰”을 명확히 표시할 수 있습니다. ([w3.org](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/))
| 변경 유형 | 예시 | 권장 처리 |
|---|---|---|
| Patch | 설명 수정, 문서 오타, 미세한 값 보정 | 시각 회귀 테스트 후 배포 |
| Minor | 새 semantic token 추가, 새 component token 추가 | 기존 토큰 유지, 사용 가이드 추가 |
| Major | 토큰 삭제, 이름 변경, 의미 변경 | deprecated 기간, 마이그레이션 표, 화면 영향도 리뷰 |
이 표는 공식 표준이 아니라 실무 운영 규칙입니다. 하지만 API 버전 관리와 비슷하게 생각하면 PM과 개발자가 대화하기 쉬워집니다. “이번 디자인 변경은 major인가 minor인가?”를 묻는 순간, 단순한 색상 변경이 아니라 고객이 보는 제품 화면 변경으로 다루게 됩니다.
9. QA 체크리스트: 토큰은 적용보다 검수가 어렵습니다
토큰 적용 프로젝트에서 가장 많이 놓치는 부분은 “정상 화면만 보고 끝내는 것”입니다. 버튼 기본 상태는 맞는데 hover가 다르거나, 입력창 에러 상태는 맞지만 focus ring이 빠져 있거나, 관리자 테이블의 selected row 색이 예전 값으로 남는 경우가 많습니다. 특히 가입, 문의, 결제, 관리자 등록 폼은 상태가 많기 때문에 토큰 QA의 우선순위가 높습니다. 폼 상태별 검수는 폼 UX 최적화 가이드의 기준과 함께 보면 실무 적용이 쉽습니다.
| 검수 영역 | 확인 질문 | 담당 |
|---|---|---|
| 색상 | 텍스트, 배경, border, icon, chart가 semantic token을 쓰는가? | 디자이너·프론트엔드 |
| 상태 | hover, active, focus, disabled, loading, error가 모두 정의됐는가? | PM·QA |
| 타이포그래피 | 제목·본문·caption의 font-size, line-height가 코드와 Figma에서 일치하는가? | 디자이너·프론트엔드 |
| 간격 | 카드, 섹션, 폼, 테이블의 padding과 gap이 scale을 따르는가? | 프론트엔드 |
| 테마 | light/dark 또는 브랜드 모드 전환 시 읽기 어려운 조합이 없는가? | 디자이너·QA |
| 문서 | 토큰 이름, 설명, 사용 금지 사례, 변경 이력이 기록됐는가? | PM·디자인 시스템 담당자 |
10. 외주 개발 후라면 ‘토큰 인벤토리’부터 만드세요
이미 외주 개발이 끝났거나 여러 개발자가 지나간 프로젝트라면 처음부터 멋진 디자인 시스템을 만들기보다 토큰 인벤토리부터 만드는 것이 현실적입니다. 실제 코드에서 사용 중인 색상과 spacing을 추출하고, Figma 기준과 다른 값을 표로 정리합니다. 그다음 “지금 바로 치환할 값”, “다음 리뉴얼 때 정리할 값”, “삭제 예정 값”으로 나눕니다.
- CSS, Tailwind config, theme file, inline style에서 색상·폰트·간격 값을 추출합니다.
- Figma의 변수·스타일과 비교해 불일치 목록을 만듭니다.
- 매출·전환·운영에 가까운 화면부터 우선순위를 정합니다. 예: 랜딩 CTA, 가입·문의 폼, 결제, 관리자 핵심 테이블.
- 토큰 이름 규칙을 먼저 확정한 뒤 코드를 치환합니다.
- 변경 전후 스크린샷을 남기고 QA 기준을 문서화합니다.
이 과정은 인수인계 자료와도 연결됩니다. 소스코드, 서버, DB, 배포 문서만 받아서는 UI 기준이 복원되지 않습니다. 외주 산출물을 점검할 때는 외주개발 인수인계 체크리스트와 함께 토큰 또는 스타일 기준 파일이 있는지 확인하는 편이 좋습니다.
11. 작은 팀을 위한 2주 시작안
디자인 토큰 관리는 대기업 디자인 시스템 팀만 할 수 있는 일이 아닙니다. 다만 작은 팀은 범위를 작게 잡아야 성공합니다. 아래 2주 안은 사업 홈페이지와 SaaS MVP, 관리자 화면을 함께 가진 초기 팀에 맞춘 최소 운영안입니다.
| 기간 | 할 일 | 산출물 |
|---|---|---|
| 1~2일차 | 현재 화면 10~20개에서 색상·폰트·간격 추출 | UI 값 인벤토리 |
| 3~4일차 | 중복 값 정리, primitive scale 초안 작성 | color, spacing, radius 초안 |
| 5~6일차 | semantic token 이름 확정 | color-bg, color-text, color-border 기준 |
| 7~8일차 | Figma 변수 또는 JSON 원본 선택 | 토큰 원본 파일 |
| 9~10일차 | CSS variables 적용, 핵심 컴포넌트 치환 | button, input, card, table 토큰 적용 |
| 11~12일차 | light/dark 또는 기본/브랜드 모드 테스트 | 테마 전환 QA 결과 |
| 13~14일차 | 변경 규칙, deprecated 규칙, 담당자 확정 | 토큰 운영 문서 |
이 정도만 해도 “다음 화면은 어떤 회색을 쓰지?”, “이 버튼 높이는 44px인가 48px인가?”, “관리자 폼 error 색은 무엇인가?” 같은 반복 질문이 줄어듭니다. 중요한 것은 완벽한 체계가 아니라 팀이 실제로 따를 수 있는 작은 규칙입니다.
12. AgentMit이 보는 구현 포인트
AgentMit은 디자인 토큰을 디자인 용어가 아니라 사업 화면의 신뢰를 유지하는 구현 기준으로 봅니다. 특히 BizMit 같은 SaaS, 업무 자동화 화면, 관리자 대시보드, 정부지원사업 MVP에서는 초기 화면 수가 적더라도 이후 기능이 빠르게 늘어납니다. 이때 토큰 없이 화면을 추가하면 랜딩 페이지, 서비스 본 화면, 관리자 화면이 서로 다른 제품처럼 보이기 쉽습니다.
실제 프로젝트에서는 다음 지점에서 외부 구현 도움이 필요해지는 경우가 많습니다. 첫째, 기존 코드에서 UI 값을 추출해 토큰 후보로 정리하는 작업. 둘째, Figma Variables 또는 Tokens Studio와 Git 저장소를 연결하는 작업. 셋째, Next.js·React 프로젝트에서 CSS variables, Tailwind theme, 컴포넌트 props 구조를 맞추는 작업. 넷째, 디자인 변경이 배포로 이어지는 CI·QA 흐름을 만드는 작업입니다. AgentMit은 이런 구간에서 디자인 시스템 문서가 실제 코드와 관리자 화면, SaaS 운영 화면까지 이어지도록 프론트엔드 구축과 구현 컨설팅을 지원할 수 있습니다.
다만 토큰 프로젝트를 시작하기 전에는 먼저 내부 의사결정자를 정해야 합니다. 토큰 이름을 누가 승인할지, 브랜드 변경 시 누가 최종 결정을 내릴지, 배포 전 어떤 화면을 필수 검수할지를 정하지 않으면 도구를 도입해도 운영이 흔들립니다.
FAQ
Q1. 디자인 토큰은 디자인 시스템이 있는 팀만 필요한가요?
아닙니다. 화면이 5~10개뿐인 초기 서비스라도 브랜드 색상, 본문 폰트, 버튼 높이, 입력창 상태, 카드 여백이 반복된다면 최소 토큰을 두는 편이 좋습니다. 다만 처음부터 수백 개를 만들 필요는 없고 color, typography, spacing, radius, shadow의 공통 기준부터 시작하는 것이 현실적입니다.
Q2. Figma 변수를 만들면 코드에도 자동 적용되나요?
자동 적용된다고 보면 위험합니다. Figma 변수는 디자인 파일 안에서 일관성을 높여주지만, 실제 웹·앱 코드에 반영하려면 export, API, Tokens Studio, Style Dictionary, GitHub Actions 같은 동기화 경로를 별도로 설계해야 합니다. 핵심은 ‘누가 승인하고 언제 배포되는가’입니다.
Q3. primitive 토큰과 semantic 토큰은 꼭 나눠야 하나요?
서비스가 커질 가능성이 있다면 나누는 것을 권장합니다. primitive는 blue-500, gray-100처럼 원재료 값이고 semantic은 color-bg-primary, color-text-danger처럼 용도입니다. 화면 코드는 가능하면 semantic 토큰을 써야 리브랜딩이나 다크 모드 때 수정 범위가 줄어듭니다.
Q4. 디자인 토큰 이름은 한국어로 지어도 되나요?
문서 설명은 한국어로 해도 되지만 토큰 key는 영문 소문자, 숫자, 하이픈 또는 슬래시 규칙으로 통일하는 편이 안전합니다. CSS 변수, TypeScript export, iOS·Android 리소스 이름으로 변환될 수 있기 때문입니다. 예: color-text-primary, spacing-4, radius-md.
Q5. 외주 개발 후 화면 스타일이 제각각이면 디자인 토큰부터 정리해야 하나요?
대부분은 그렇습니다. 먼저 실제 코드에서 반복되는 색상·폰트·간격 값을 추출하고, Figma 기준과 다른 값을 표로 정리한 뒤, 토큰으로 치환할 우선순위를 정합니다. 단, 모든 화면을 한 번에 갈아엎기보다 랜딩, 가입·문의 폼, 관리자 주요 화면처럼 매출·운영에 가까운 화면부터 정리하는 것이 좋습니다.
참고 자료
- W3C Design Tokens Format Module 2025.10: 토큰 구조, JSON 포맷, alias/reference, deprecated 속성 확인에 참고했습니다. ([w3.org](https://www.w3.org/community/reports/design-tokens/CG-FINAL-format-20251028/))
- Figma Help Center와 Developer Docs: variables, collections, modes, API 동기화 가능성과 제한을 확인하는 데 참고했습니다. ([help.figma.com](https://help.figma.com/hc/en-us/articles/14506821864087-Overview-of-variables-collections-and-modes))
- Style Dictionary 공식 문서: 플랫폼별 transform과 CSS variables 산출 방식 설명에 참고했습니다. ([styledictionary.com](https://styledictionary.com/info/tokens/))
- MDN CSS Custom Properties 문서: 웹 구현에서
:root,var(),@property사용 기준을 확인했습니다. ([developer.mozilla.org](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties)) - Tokens Studio 문서: W3C DTCG 포맷과 레거시 포맷 선택, Figma 기반 토큰 운영 맥락을 확인했습니다. ([docs.tokens.studio](https://docs.tokens.studio/manage-settings/token-format))
