Figma 에 토큰 import 하기

경로 선택

경로 1 · Tokens Studio (권장)

1-1. 플러그인 설치

1. Figma 에서 "Tokens Studio" 검색 + 설치

   Figma 메뉴 → Plugins → Browse plugins in Community → "Tokens Studio for Figma" 검색 → Install

2. 플러그인 실행

   Figma 파일 우클릭 → Plugins → Tokens Studio for Figma → Run

1-2. 토큰 JSON 가져오기

1. JSON 파일 다운로드

   아래 버튼으로 figma-tokens-studio.json 다운로드 (28 KB).

2. 플러그인에서 Import

   Tokens Studio 패널 → 좌측 메뉴 ☰ → "Tools" → "Load from file..." → 방금 다운로드한 JSON 선택

3. 토큰 적용 확인

   플러그인 좌측에 cellogram 토큰 세트가 표시됨. 색상 · spacing · typography 등 카테고리별 사용 가능.

1-3. 디자인에 토큰 사용

1. 색상 적용

   Figma 객체 선택 → Fill 색 클릭 → 플러그인 좌측에서 토큰 이름 클릭 (예: color.brand.500). 자동으로 #947F82 적용.

2. 타이포 적용

   텍스트 선택 → Tokens Studio 의 Typography 카테고리에서 display / heading / body / small 클릭. font-size · line-height · letter-spacing · font-weight 일괄 적용.

3. Figma Styles 자동 생성

   Tokens Studio 우측 상단 "Apply to document" 클릭 → 모든 토큰이 Figma Styles 로 변환. 다른 디자이너도 즉시 사용 가능.

경로 2 · Figma Variables (네이티브)

1. JSON 파일 다운로드

   figma-variables.json (16 KB) — Figma Variables REST API format.

2. Figma 파일에서 Variables 패널 열기

   우측 사이드바 "Local variables" 클릭 (없으면 빈 부분 우클릭 → Show variables).

3. JSON Import

   Variables 패널 우측 상단 "..." → "Import" → JSON 파일 선택.
   또는 Figma REST API 또는 변수 plugin (예: "Variables Import" plugin) 사용.

4. 적용

   객체 Fill → "Variables" 아이콘 클릭 → color/brand/500 선택. Variable bound 됨.

일상 사용 패턴

모든 새 시안에서

1. 색상 picker 대신 → 토큰 이름으로 적용 (절대 hex 직접 입력 X)
2. 임의 spacing 대신 → spacing.md · spacing.lg 등 step 사용
3. 임의 radius 대신 → radius.sm ~ radius.full
4. 한국어 텍스트 → typography.body 그대로 (line-height 1.85 자동)
5. 다국어 변경 시 → text 의 language 속성만 변경, 토큰 자동 재계산

금지 사항

• ❌ Figma 에서 hex 직접 입력 (예: #947F82 수동 입력)
• ❌ 토큰 사이즈를 임의 조정 (Figma 에서 display 의 line-height 변경 X)
• ❌ 토큰 이름 변경 (예: color.brand.500 → color.primary)
• ❌ CN 금지어 사용 (胶原架构 / ECM 臻萃 / 细胞记) — 빌드 시 차단됨

토큰 자체를 바꾸고 싶을 때

현재 v4.0 은 단방향 sync:

코드 (packages/tokens/source/*.json)
  ↓ Style Dictionary 빌드
JSON · CSS · Tailwind · TypeScript · Figma Variables JSON 자동 생성
  ↓ 디자이너 가져옴
Figma

Figma 에서 직접 토큰 값을 수정해도 코드에는 자동 반영되지 않습니다. 변경 요청 흐름:

1. Figma 에서 변경하고 싶은 토큰 + 신규 값 정리 (예: color.brand.500 을 #947F82 → #9B848A 로)
2. CLEARMED 팀에 변경 요청 (Slack, Email, 또는 Issue)
3. 팀이 packages/tokens/source/ 수정 + Brand IP guardrail 검증
4. 빌드 자동 실행 → JSON · CSS · Tailwind · TypeScript · Figma Variables 모두 갱신
5. 디자이너는 다시 import → 신규 값 자동 반영

FAQ

Q. Tokens Studio 와 Figma Variables 둘 다 import 해도 되나요?

가능하지만 권장하지 않음. 둘 중 하나만 사용 — 동기화 충돌 위험. 한 파일에서는 일관되게 하나의 source 만 유지.

Q. 색상이 RGB 로 표시되는데 hex 로 안 되나요?

Tokens Studio 는 import 시 RGB 또는 hex 둘 다 표시. Figma Variables 는 자동으로 hex 변환. 둘 다 실제 값은 동일.

Q. 다국어 (영문/일본어/중국어) 타이포는 어떻게 적용?

Figma 텍스트의 "Language" 속성을 ko/en/ja/zh-Hans 로 변경. 또는 Tokens Studio 에서 lang variant 토큰 사용 (예: typography.body.en).

Q. 다크 모드 시안은?

Figma Variables (Org plan) 사용 시 자동 mode 전환 가능. Tokens Studio 는 별도 토큰 세트로 "cellogram-dark" 만들어 토글.

Q. 한 컴포넌트가 두 브랜드 (CELLOGRAM/CLEARMED) 모두에서 사용되나요?

예. color.brand.500 토큰을 사용하면 브랜드 switch 시 자동 변경. #947F82 hex 를 직접 쓰지 마세요.

Q. 토큰이 너무 많아서 어떤 걸 쓸지 모르겠어요

가장 자주 쓰는 5개부터 익히세요: color.brand.500 · color.surface.canvas · color.text.primary · typography.body · spacing.md.

트러블슈팅

"Plugin not loading" 에러

Tokens Studio plugin 페이지에서 최신 버전 재설치. Figma 새로고침 (Cmd+R).

JSON import 시 "Invalid format" 에러

경로 1 (Tokens Studio) 에는 figma-tokens-studio.json, 경로 2 (Variables) 에는 figma-variables.json. 파일 헷갈리지 않게 주의.

색상이 import 됐는데 명도가 이상함

Figma 의 color profile 이 P3 또는 sRGB 인지 확인. Cellogram 토큰은 sRGB 기준. Figma 메뉴 → Settings → Color Space → sRGB.

한글 타이포 letter-spacing 이 안 먹음

Figma 의 letter-spacing 단위가 % 가 아닌 em 으로 설정되어 있어야 함. Tokens Studio 가 자동 처리하지만 수동 적용 시 주의.

추가 자료