01-Figma 디자인 토큰 완전 정복
1. 1장. 디자인 토큰이란?
1.1. 1.1 이런 경험이 있는가?
디자인 작업을 하다 보면 이런 상황이 자주 생긴다.
개발자: “버튼 색이 피그마랑 다른데요?” 디자이너: “아, 제가 쓴 파란색이
#2563EB인데 혹시#1D4ED8쓰셨나요?” 개발자: ”… 비슷해 보여서 그냥 썼어요.”
또는 이런 상황도 있다.
디자이너: “브랜드 컬러가 바뀌었어요. 파란색 → 보라색으로요.” 개발자: “피그마에 파란색이 쓰인 곳이 87군데네요. 다 찾아서 바꿔야 해요?”
이 두 가지 문제를 한 번에 해결하는 것이 디자인 토큰이다.
1.2. 1.2 디자인 토큰이란?
쉽게 말하면 **“색상, 크기, 간격 같은 디자인 값에 이름을 붙여놓은 것”**이다.
예를 들어 버튼 색상을 이렇게 정의한다.
1버튼 배경색 = 브랜드 메인 색상2브랜드 메인 색상 = #2563EB이렇게 하면 나중에 브랜드 색상을 #7C3AED(보라색)로 바꾸고 싶을 때 한 곳만 수정하면 버튼, 링크, 배지 등 연결된 모든 요소가 동시에 바뀐다.
요약하면:
- 값(
#2563EB)에 이름(브랜드 메인 색상)을 붙인 것이 토큰이다. - 디자이너와 개발자가 같은 이름을 공유하면 오해가 사라진다.
- Figma에서 수정하면 코드까지 자동으로 바뀌는 연결 고리가 된다.
1.3. 1.3 토큰이 없으면 어떤 일이 생기는가?
상황 1: 색상 값을 직접 쓰는 경우
1버튼 배경 → #2563EB (직접 입력)2헤더 배경 → #2563EB (직접 입력)3링크 색상 → #2563EB (직접 입력)4강조 텍스트 → #2563EB (직접 입력)브랜드 색상이 바뀌면 위 4곳을 모두 찾아서 일일이 바꿔야 한다. 실제 프로젝트에서는 이런 값이 수십~수백 군데에 퍼져 있다.
상황 2: 토큰을 쓰는 경우
1버튼 배경 → {color.primary} (토큰 참조)2헤더 배경 → {color.primary} (토큰 참조)3링크 색상 → {color.primary} (토큰 참조)4강조 텍스트 → {color.primary} (토큰 참조)5
6color.primary = #2563EB ← 여기 1곳만 바꾸면 끝1.4. 1.4 토큰의 3단계 구조
토큰을 처음 보면 “왜 이렇게 나눠놓았지?”라는 생각이 드는 게 정상이다. 한 단계씩 이해해보자.
단계 1 — Primitive (원재료)
브랜드가 가진 모든 색상·크기 값을 그냥 나열한다. 요리 재료통에 재료를 보관하는 것과 같다.
1blue-50 = #EFF6FF2blue-100 = #DBEAFE3 ...4blue-600 = #2563EB ← 그냥 이 색이 존재한다는 사실만 기록5blue-700 = #1D4ED8⚠️ Primitive는 UI에 직접 연결하지 않는다. “파란색”이라는 사실만 기록하는 단계이다. 어디에 쓰이는지는 아직 정하지 않는다.
단계 2 — Semantic (용도 부여)
Primitive 값에 “어디에 쓰인다”는 의미를 붙이는 단계이다.
1color.primary = {blue-600} ← "브랜드 메인 색"2color.primary.hover = {blue-700} ← "호버 시 색"3color.text.primary = {gray-900} ← "기본 텍스트 색"4color.bg.default = {white} ← "기본 배경색"단계 3 — Component (컴포넌트 전용)
특정 컴포넌트에서만 쓰는 값을 Semantic을 참조해서 정의한다.
1button.bg.default = {color.primary} ← 버튼 배경2button.bg.hover = {color.primary.hover} ← 버튼 호버 배경3input.border = {color.border.default} ← 인풋 테두리왜 이렇게 3단계로 나누는가?
다크모드를 생각해보면 바로 이해가 된다.
1라이트 모드: color.bg.default = {white} → #FFFFFF2다크 모드: color.bg.default = {gray-900} → #0F172ASemantic 토큰 값만 교체했는데, 이 토큰을 참조하고 있는 모든 컴포넌트가 동시에 바뀐다. 컴포넌트를 하나씩 수정할 필요가 없다.
1.5. 1.5 토큰에 담을 수 있는 것들
색상만 토큰으로 만드는 게 아니다.
| 종류 | 예시 이름 | 예시 값 |
|---|---|---|
| 색상 | color.primary | #2563EB |
| 글자 크기 | font.size.md | 16 |
| 글자 두께 | font.weight.bold | 700 |
| 줄 간격 | font.lineHeight.normal | 1.5 |
| 여백 | spacing.4 | 16 |
| 모서리 둥글기 | radius.md | 8 |
| 그림자 | shadow.md | 0 4px 12px rgba(0,0,0,0.1) |
| 전환 속도 | duration.fast | 150 |
1.6. 1.6 이름 짓는 방법
토큰 이름은 개발자가 코드에서 그대로 사용하기 때문에 규칙을 미리 합의해야 한다.
권장 형식: 카테고리 / 용도 / 상태
1color / primary / default2color / primary / hover3color / text / secondary4spacing / button / paddingX좋은 이름 vs 나쁜 이름:
| ✅ 좋은 이름 | ❌ 나쁜 이름 | 나쁜 이유 |
|---|---|---|
color/primary | blue-color | 색상 이름이 들어가면 색이 바뀔 때 이름이 틀려진다 |
color/text/secondary | gray-500-text | 값(gray-500)이 이름에 들어가 있다 |
spacing/4 | padding-16px | 단위(px)가 들어가면 단위 변경 시 이름도 바꿔야 한다 |
color/danger | red | 용도가 없고 색상만 표현한다 |
💡 핵심 규칙 이름에 실제 값이나 색상명을 넣지 않는다. “어디에, 어떤 상황에 쓰인다”는 의미만 담는다.
2. 2장. Figma Variables로 토큰 만들기
Figma에서 토큰을 직접 만들 수 있는 기능이 Variables이다. 2023년에 추가된 기능으로, 별도 플러그인 없이도 기본 토큰 시스템을 구성할 수 있다.
⚠️ 시작 전 확인
- Figma 계정이 있으면 무료로 사용 가능하다.
- Variables 패널 열기: 우측 상단 메뉴 →
Local variables클릭- 단축키:
Option+Ctrl+L(Mac) /Alt+Ctrl+L(Win)
2.1. 2.1 Variables 패널 살펴보기
Variables 패널을 처음 열면 아무것도 없다. 여기서 토큰을 직접 만든다.
저장할 수 있는 값의 종류:
| 타입 | 저장하는 것 | 주로 쓰는 곳 |
|---|---|---|
| Color | 색상 | 배경색, 글자색, 테두리색 |
| Number | 숫자 (단위 없이) | 여백, 글자 크기, 모서리 둥글기 |
| String | 글자 | 폰트 이름 |
| Boolean | 켜짐/꺼짐 | 요소의 표시 여부 |
패널 용어 정리:
- Collection — 토큰을 담는 폴더.
Primitives,Semantic같은 큰 묶음이다. - Group — Collection 안에서 이름에
/를 쓰면 자동으로 폴더처럼 묶인다. - Variable — 실제 이름-값 한 쌍이다. 우리가 만드는 토큰 하나하나이다.
- Mode — 같은 토큰에 다른 값을 지정하는 기능이다. 라이트/다크 모드에 사용한다.
2.2. 2.2 Primitives Collection 만들기
Collection 생성:
- Variables 패널 →
+ New collection클릭 - 이름을
Primitives로 입력한다.
첫 번째 Variable 추가:
+ Add variable클릭- 타입:
Color선택 - 이름:
color/blue/600입력 (슬래시가 폴더처럼 묶어준다) - 값:
#2563EB입력
이 과정을 반복해서 아래 색상들을 모두 만든다.
Blue 팔레트:
1color/blue/50 → #EFF6FF (아주 연한 파랑)2color/blue/100 → #DBEAFE3color/blue/200 → #BFDBFE4color/blue/300 → #93C5FD5color/blue/400 → #60A5FA6color/blue/500 → #3B82F67color/blue/600 → #2563EB ← 라이트 모드 메인 색으로 쓸 기준8color/blue/700 → #1D4ED89color/blue/800 → #1E40AF10color/blue/900 → #1E3A8A (아주 진한 파랑)Gray 팔레트 (배경·텍스트에 사용):
1color/gray/50 → #F8FAFC (거의 흰색)2color/gray/100 → #F1F5F93color/gray/200 → #E2E8F04color/gray/300 → #CBD5E15color/gray/400 → #94A3B86color/gray/500 → #64748B7color/gray/600 → #4755698color/gray/700 → #3341559color/gray/800 → #1E293B10color/gray/900 → #0F172A (거의 검정)흰색·검정:
1color/white → #FFFFFF2color/black → #000000여백 스케일 (Number 타입으로 추가):
Number 타입은 숫자만 입력한다.
16px이 아니라16이다. 단위는 개발자가 코드로 변환할 때 붙인다.
1spacing/1 → 42spacing/2 → 83spacing/3 → 124spacing/4 → 165spacing/5 → 206spacing/6 → 247spacing/8 → 328spacing/10 → 409spacing/12 → 4810spacing/16 → 64모서리 둥글기 (Number 타입):
1radius/none → 02radius/sm → 43radius/md → 8 ← 버튼에 주로 사용4radius/lg → 12 ← 카드에 주로 사용5radius/xl → 166radius/full → 9999 ← 완전히 둥근 알약 모양글자 관련 (Number + String 타입 혼용):
1// 글자 크기 (Number)2font/size/xs → 123font/size/sm → 144font/size/md → 16 ← 본문 기본 크기5font/size/lg → 186font/size/xl → 207font/size/2xl → 248font/size/3xl → 309
10// 글자 두께 (Number)11font/weight/regular → 400 ← 일반12font/weight/medium → 50013font/weight/semibold → 60014font/weight/bold → 700 ← 굵게15
16// 줄 간격 (Number, 비율로 입력)17font/lineHeight/tight → 1.25 ← 제목에 주로 사용18font/lineHeight/normal → 1.5 ← 본문 기본19font/lineHeight/loose → 1.75 ← 가독성 높일 때20
21// 폰트 이름 (String)22font/family/sans → Pretendard, sans-serif23font/family/mono → JetBrains Mono, monospace2.3. 2.3 Semantic Collection 만들기
이제 Primitive 값들에 “어디에 쓰인다”는 의미를 붙인다.
Collection 생성 + Mode 추가:
+ New collection→ 이름:Semantic- 우측 상단
Edit modes클릭 - 기본 Mode 이름 →
Light로 변경 + Add mode→Dark추가
이렇게 하면 같은 토큰이 라이트/다크 두 가지 값을 가질 수 있다.
Variable에 다른 Variable 참조하는 방법:
값을 직접 입력하는 대신 Primitive Variable을 참조할 수 있다.
- Variable 값 입력란 우측의
◆(육면체 아이콘) 클릭 - Primitives Collection의 Variable 목록이 뜬다
- 원하는 Variable 클릭 → 참조 연결 완료
💡 왜 직접 값을 입력하지 않는가?
#2563EB를 직접 입력하면 나중에 색이 바뀌어도 여기는 안 바뀐다. Primitive Variable을 참조하면 Primitive 값만 바꿔도 여기까지 자동으로 바뀐다.
컬러 Semantic 토큰 (Light / Dark 값 동시 설정):
| 토큰 이름 | Light 값 | Dark 값 | 어디에 쓰는가 |
|---|---|---|---|
color/bg/default | {color/white} | {color/gray/900} | 페이지 기본 배경 |
color/bg/subtle | {color/gray/50} | {color/gray/800} | 구분 영역 배경 |
color/bg/elevated | {color/white} | {color/gray/800} | 카드·모달 배경 |
color/text/primary | {color/gray/900} | {color/white} | 본문 주요 텍스트 |
color/text/secondary | {color/gray/600} | {color/gray/400} | 설명·부제목 텍스트 |
color/text/disabled | {color/gray/300} | {color/gray/600} | 비활성 텍스트 |
color/border/default | {color/gray/200} | {color/gray/700} | 기본 테두리 |
color/border/strong | {color/gray/400} | {color/gray/500} | 강조 테두리 |
color/primary | {color/blue/600} | {color/blue/400} | 버튼·링크 등 메인 색 |
color/primary/hover | {color/blue/700} | {color/blue/300} | 마우스 올렸을 때 |
color/primary/subtle | {color/blue/50} | {color/blue/900} | 배지·태그 배경 |
color/danger | {color/red/600} | {color/red/400} | 에러·삭제 |
color/success | {color/green/600} | {color/green/400} | 성공·완료 |
color/warning | {color/yellow/500} | {color/yellow/400} | 경고 |
💡 이름에 색상명을 넣으면 안 되는 이유
color/blue라고 이름 지으면 다크모드에서 값이 연한 파랑으로 바뀌어도 이름은 여전히blue다. 혼란스럽다.color/primary처럼 용도 중심으로 이름을 짓는다.
2.4. 2.4 라이트/다크 모드 전환 확인하기
이제 Mode를 전환해서 토큰이 잘 동작하는지 확인한다.
프레임에 Mode 적용하는 방법:
- 최상위 프레임 선택
- 우측 패널
Layer섹션 아래Mode드롭다운 클릭 Light또는Dark선택
프레임 안에 Semantic 토큰이 연결된 요소가 있다면 Mode를 바꾸는 순간 모든 색이 한 번에 바뀐다.
🔍 실습 과제
- 배경에
color/bg/default를 연결한 프레임을 만든다.- 그 안에 텍스트를 넣고
color/text/primary를 연결한다.- Mode를 Light ↔ Dark로 전환하며 자동으로 바뀌는지 확인한다.
2.5. 2.5 Component Collection 만들기
컴포넌트마다 전용 토큰을 만들어두면 나중에 디자인을 수정할 때 훨씬 편하다. Component 토큰은 Semantic 토큰을 참조한다. Primitive를 직접 참조하지 않는다.
❓ 왜 Semantic을 거쳐야 하는가? 버튼 배경을
{color/blue/600}으로 직접 연결하면 다크모드에서 색이 안 바뀐다.{color/primary}로 연결하면 Mode 전환만으로 다크모드 대응이 끝난다.
Button 토큰 예시:
1button/bg/default → {color/primary} 버튼 기본 배경2button/bg/hover → {color/primary/hover} 마우스 올렸을 때3button/bg/disabled → {color/bg/subtle} 비활성 버튼 배경4button/text/default → {color/white} 버튼 글자색5button/text/disabled → {color/text/disabled} 비활성 버튼 글자6button/radius → {radius/md} 버튼 모서리 둥글기7button/paddingX → {spacing/4} 버튼 좌우 여백8button/paddingY → {spacing/2} 버튼 위아래 여백Input 토큰 예시:
1input/bg/default → {color/bg/default} 인풋 배경2input/border/default → {color/border/default} 기본 테두리3input/border/focused → {color/primary} 포커스 시 테두리4input/border/error → {color/danger} 에러 시 테두리5input/text/default → {color/text/primary} 입력 텍스트 색6input/text/placeholder → {color/text/secondary} 플레이스홀더 색7input/radius → {radius/sm} 인풋 모서리2.6. 2.6 컴포넌트에 Variable 연결하기
토큰을 만들었으면 이제 실제 컴포넌트에 연결한다.
색상 연결 방법:
- 색을 바꿀 레이어 선택
- Fill (또는 텍스트 색) 클릭
- 색상 피커 좌측 하단
Libraries탭 클릭 - 원하는 Variable 검색 후 클릭
Auto Layout 여백 연결 방법:
- Auto Layout이 적용된 프레임 선택
- 우측 패널에서 Gap, Padding 숫자 옆
◆아이콘 클릭 - Spacing Variable 선택
모서리 둥글기 연결 방법:
- 요소 선택 → Corner radius 값 클릭
◆아이콘 → Radius Variable 선택
⚠️ 연결이 끊기는 경우 Variable이 연결된 상태에서 값을 직접 수정하면 연결이 끊어진다. 값을 바꾸고 싶을 때는 Primitive Collection의 원래 값을 수정해야 한다.
3. 3장. 무료 플러그인으로 토큰 생성·내보내기
2장에서 Figma Variables로 토큰을 직접 만드는 방법을 배웠다. 이번 장에서는 두 가지 무료 플러그인으로 작업 속도를 높이는 방법을 다룬다.
| 플러그인 | 역할 | 방향 |
|---|---|---|
| Tailwind Tokens | Tailwind 기본 토큰 스케일을 Figma Variables로 자동 생성 | Tailwind → Figma |
| Figma to JSON Exporter | 완성된 Variables를 JSON 파일로 내보내기 | Figma → JSON (개발자 전달용) |
💡 두 플러그인의 관계 Tailwind Tokens로 Primitive 토큰을 빠르게 세팅하고, Figma to JSON Exporter로 완성된 토큰을 개발자에게 전달하는 흐름으로 사용한다.
3.1. 3.1 Tailwind Tokens — Primitive 토큰 자동 생성
3.1.1. 이 플러그인이 하는 일
Tailwind CSS는 색상·여백·타이포그래피 등의 기본 스케일이 이미 잘 정의되어 있다. 이 플러그인은 그 Tailwind 기본값을 클릭 한 번으로 Figma Variables에 생성해준다.
2장에서 Blue 팔레트를 한 줄씩 직접 입력했던 것을 기억하는가? Tailwind Tokens를 쓰면 그 작업을 자동으로 처리한다.
🔗 설치 링크 Figma Community →
Tailwind Tokens - Create Tailwind CSS Variables & Styleshttps://www.figma.com/community/plugin/1513618945140968492
3.1.2. 설치 및 실행
- 위 링크 접속 →
Open in Figma클릭 → 설치 - Figma 파일 열기 → 우측 하단 플러그인 아이콘(⬡) 또는
메뉴 →
Plugins→Tailwind Tokens실행
3.1.3. 토큰 생성 방법
- 플러그인 패널에서 생성할 토큰 카테고리를 선택한다.
1✅ Colors (색상 스케일 전체)2✅ Spacing (여백 스케일)3✅ Border Radius (모서리 둥글기)4✅ Typography (글자 크기·두께·줄 간격)5☐ Shadows (필요 시 선택)Generate클릭 → Figma Variables에 Collection이 자동 생성된다.- Variables 패널을 열면
Tailwind CSSCollection 안에 토큰이 채워진 것을 확인할 수 있다.
3.1.4. 생성된 결과 예시
1Collection: Tailwind CSS2├── colors/3│ ├── blue/50 → #EFF6FF4│ ├── blue/100 → #DBEAFE5│ │ ...6│ └── blue/900 → #1E3A8A7├── spacing/8│ ├── 1 → 49│ ├── 2 → 810│ │ ...11│ └── 16 → 6412└── borderRadius/13 ├── sm → 214 ├── md → 615 └── lg → 83.1.5. 생성 후 할 일
Tailwind Tokens는 Primitive(원재료) 역할의 토큰을 자동으로 만들어준다.
이후에는 2장에서 배운 것처럼 Semantic Collection을 직접 추가하고
Tailwind Tokens가 만든 값을 참조(◆ 아이콘)해서 연결한다.
⚠️ Tailwind 스케일과 브랜드 스케일이 다를 때 Tailwind 기본 파란색(
blue/600 = #2563EB)이 브랜드 색과 다르다면 생성된 Variable 값을 직접 수정하면 된다. 스케일 구조(50~900)는 그대로 재활용할 수 있다.
3.2. 3.2 JSON이 무엇인가?
개발자에게 토큰을 전달할 때 사용하는 파일 형식이다. JSON은 메모장으로 열 수 있는 텍스트 파일이고, 아래처럼 생겼다.
1{2 "color": {3 "primary": {4 "value": "#2563EB",5 "type": "color",6 "description": "버튼·링크 등 메인 브랜드 색상"7 }8 },9 "spacing": {10 "4": {11 "value": "16",12 "type": "dimension"13 }14 }15}각 항목의 의미:
"color/primary"— 토큰 이름"value"— 실제 값"type"— 값의 종류 (색상인지, 크기인지 등)"description"— 이 토큰을 어떻게 쓰는지 설명 (개발자가 읽는다)
💡
description은 꼭 채운다 개발자는 이 설명을 보고 토큰을 어디에 써야 할지 판단한다. 예:"버튼 호버 시 배경색. 클릭 가능한 요소에만 사용한다."
3.3. 3.3 Figma to JSON Exporter — 토큰 파일 내보내기
3.3.1. 이 플러그인이 하는 일
Figma에서 만든 Variables(토큰)를 JSON 파일로 변환해준다. 개발자는 이 JSON 파일을 받아서 CSS·JS 코드로 변환한다.
🔗 설치 링크 Figma Community →
Figma to JSON Exporterhttps://www.figma.com/community/plugin/1510358539626018288
3.3.2. 설치 및 실행
- 위 링크 →
Open in Figma→ 설치 Plugins메뉴 →Figma to JSON Exporter실행
3.3.3. 내보내기 방법
- 플러그인 실행 후 내보낼 범위 선택 (전체 파일 또는 선택한 프레임)
Export클릭- JSON 파일이 다운로드된다.
- 다운로드된 파일을 개발자에게 전달한다.
3.3.4. 내보낸 JSON 파일 예시
1{2 "variables": {3 "color/primary": {4 "value": "#2563EB",5 "type": "COLOR",6 "collection": "Semantic"7 },8 "spacing/4": {9 "value": 16,10 "type": "FLOAT",11 "collection": "Primitives"12 }13 }14}⚠️ 개발자에게 알려줄 것 이 플러그인이 출력하는 JSON은 Figma 내부 데이터 구조 형식이다. W3C 표준(
$value,$type) 형식과 구조가 다를 수 있으므로 개발자가 변환 스크립트를 별도로 작성해야 할 수 있다. 이 점을 핸드오프 시 미리 공유한다.
4. 4장. 핸드오프 준비
핸드오프는 디자이너가 만든 결과물을 개발자에게 공식으로 전달하는 과정이다. 토큰이 잘 정리되어 있으면 핸드오프가 훨씬 빠르고 오류가 줄어든다.
4.1. 4.1 전달 전 점검 체크리스트
토큰 구조 점검:
- Primitive → Semantic → Component 연결이 중간에 끊기지 않았는가?
- Semantic 토큰 이름에 색상명이나 수치가 들어가지 않았는가? (예:
blue,16px금지) - 모든 컴포넌트 속성에 Variable이 연결되어 있는가? (직접 입력한 색상이 남아있지 않은가?)
- 쓰이지 않는 Primitive 토큰을 삭제했는가?
Mode(테마) 점검:
- Light와 Dark 두 Mode 모두 값이 채워져 있는가?
- Mode를 전환했을 때 모든 컴포넌트가 올바르게 바뀌는가?
- 흰색·검정처럼 모드에 상관없이 고정되어야 할 값은 Primitive에만 있는가?
이름 점검:
- 개발자와 사전에 합의한 네이밍 규칙을 따르고 있는가?
- 같은 의미인데 이름이 다른 토큰이 없는가?
4.2. 4.2 설명($description) 작성하기
모든 Semantic·Component 토큰에 설명을 추가한다. 개발자는 이 설명을 보고 “이 토큰을 어디에 써야 하는지” 판단한다.
어떻게 쓰면 좋은가:
| 토큰 종류 | 설명에 담을 내용 |
|---|---|
| 색상 | 어떤 컴포넌트의, 어떤 상태에 사용하는가 |
| 여백 | 어느 위치의 기본 간격인가 |
| 모서리 | 어떤 크기 컴포넌트에 사용하는가 |
예시:
1button/bg/hover2→ 설명: "버튼에 마우스를 올렸을 때 배경색. 클릭 가능한 버튼 요소에만 사용한다."3
4color/danger5→ 설명: "에러 메시지, 삭제 버튼, 필수 입력 표시에 사용한다."6
7spacing/48→ 설명: "16px. 컴포넌트 내부 패딩의 기본 단위이다."4.3. 4.3 개발자에게 전달할 파일 목록
| 전달물 | 형식 | 내용 |
|---|---|---|
| 토큰 JSON | .json | Figma to JSON Exporter로 내보낸 파일 |
| 토큰 문서 | Notion / 스프레드시트 | 토큰 이름·값·용도 표 |
| Figma 파일 링크 | URL | 보기(View) 권한으로 공유 |
| 네이밍 규칙 | 문서 | 팀에서 합의한 규칙 |
| 지원 테마 목록 | 문서 | Light, Dark 등 어떤 Mode가 있는지 |
| 변경 이력 | GitHub PR | 무엇을 왜 바꿨는지 |
4.4. 4.4 토큰을 바꿀 때 주의할 것들
핸드오프 후에도 토큰을 수정하는 일이 생긴다. 종류에 따라 위험도가 다르다.
| 변경 종류 | 위험도 | 처리 방법 |
|---|---|---|
| 값만 바꿈 (색상, 수치) | 낮음 | GitHub PR로 변경 내용 알리기 |
| 토큰 추가 | 낮음 | GitHub PR로 전달 |
| 토큰 이름 변경 | 🔴 높음 | 개발자와 반드시 사전 협의 — 코드에서 사용 중인 이름이 바뀌면 오류가 난다 |
| 토큰 삭제 | 🔴 높음 | 개발자와 반드시 사전 협의 — 코드에서 참조 중인 토큰이 사라지면 오류가 난다 |
5. 부록. 참고 자료 & 체크리스트
5.1. 공식 참고 자료
| 자료 | URL |
|---|---|
| W3C 디자인 토큰 표준 | https://design-tokens.github.io/community-group/format/ |
| Figma Variables 공식 문서 | https://help.figma.com/hc/en-us/articles/15339657135383 |
| Tailwind Tokens 플러그인 | https://www.figma.com/community/plugin/1513618945140968492 |
| Figma to JSON Exporter 플러그인 | https://www.figma.com/community/plugin/1510358539626018288 |
5.2. 핸드오프 전 최종 체크리스트
토큰 설계
- Primitive 컬러 스케일 완성 (Gray, Primary 최소 2종)
- Semantic 토큰 전체에 Light/Dark 값 모두 입력
- Component 토큰 주요 컴포넌트 완성 (버튼, 인풋, 카드)
- 모든 Semantic·Component 토큰에
description작성
Figma 파일
- 컴포넌트 전체에 Variable 연결 완료
- Light/Dark Mode 전환 정상 동작 확인
- 쓰지 않는 로컬 스타일 삭제
- 레이어 이름 정리 완료
전달 파일
- Token Studio JSON 내보내기 완료
- GitHub 또는 공유 드라이브에 업로드
- 토큰 문서 최신 상태 유지
- 개발자와 킥오프 미팅 일정 잡기
5.3. 자주 묻는 질문
Q. Local Styles와 Variables 중 무엇을 써야 하는가? 새 프로젝트라면 Variables를 사용한다. Variables가 코드 연동에 유리하고 Mode 기능도 있다. 기존 프로젝트는 새로 만드는 컴포넌트부터 Variables로 점진적으로 전환한다.
Q. 토큰이 너무 많아지면 어떻게 관리하는가?
실제로 컴포넌트에 쓰이지 않는 토큰을 우선 정리한다.
Figma 검색(Ctrl+F 또는 Cmd+F)으로 특정 Variable이 어디에 쓰이는지 확인할 수 있다.
Q. 디자이너 혼자 토큰을 만들어야 하는가? 네이밍 규칙과 단위 체계는 반드시 개발자와 함께 정한다. 디자이너 혼자 만든 이름을 나중에 바꾸면 코드까지 수정해야 하므로 처음에 같이 논의하는 것이 훨씬 낫다.
Q. 지금 진행 중인 프로젝트에 중간에 도입할 수 있는가? 가능하다. 전체를 한 번에 바꾸려 하지 말고, 새로 만드는 컴포넌트부터 토큰을 적용하면서 서서히 전환한다.
디자인 토큰은 디자이너와 개발자가 처음으로 같은 언어를 쓰게 해주는 도구이다. 처음엔 설정이 번거롭게 느껴지지만, 한 번 잘 만들어두면 브랜드 색상이 바뀌어도 Primitive 값 하나만 수정하고 끝낼 수 있다.
6. 피그마 토큰 생성 플러그인
테일윈드
Easy Color and token generator 2.0
Supa Design Tokens
6. 피그마 기타 플러그인
Json 을 디자인으로 JSON to Figma Import Figma to JSON Exporter