tokens-studio/figma-plugin 딥다이브
— "Figma 안의 변수·스타일"을 JSON 하나로 관리하는 토큰 엔진

1프로젝트 한 줄 요약

Tokens Studio for Figma는 "Figma 전용 디자인 토큰 편집기 겸 동기화 도구"다. 일반적인 Figma 플러그인처럼 UI 패널을 하나 띄우지만, 그 안에는 색상·간격·타이포그래피·그림자 등 수백 개의 토큰을 편집하는 미니 IDE(Monaco 에디터 포함)가 들어있다. 편집한 토큰은 현재 열린 Figma 파일의 스타일이나 변수(Variables)에 곧바로 반영되고, 원한다면 GitHub 저장소의 JSON 파일과도 실시간으로 맞춰볼 수 있다.

설치는 Figma 커뮤니티 플러그인 목록에서 "Tokens Studio"를 검색해 추가하면 끝이다. 개발자로서 소스를 직접 빌드하려면 저장소를 받아 yarn --frozen-lockfile --immutable로 의존성을 설치하고, packages/tokens-studio-for-figma에서 yarn build(또는 yarn start로 watch 모드)를 돌린 뒤 Figma 데스크탑 앱의 "Plugins → Development → Import plugin from manifest…"로 manifest.json을 불러오면 된다.

2왜 지금 주목받는가

Tokens Studio는 신생 도구가 아니라 2020년 "Figma Tokens"라는 이름으로 시작해 디자인 시스템 업계에서 사실상 표준처럼 자리잡은 도구다. 2026년 현재도 계속 활발히 개발되는 이유를 정리하면:

① Figma 자체가 "변수(Variables)" 기능을 낸 이후에도 필요한 이유

Figma는 2023년부터 자체 Variables 기능을 냈지만, JSON 파일 기반의 버전 관리, Git 히스토리, 코드 저장소와의 직접 동기화, 수식(math)·참조(alias) 표현력에서는 아직 Figma 네이티브 기능이 따라가지 못하는 부분이 있다. Tokens Studio는 그 위에서 "Figma Variables를 만들어주는 상위 계층" 역할로 스스로를 재정립했다 — 즉 경쟁하기보다 Figma Variables API를 활용해 값을 밀어넣는 도구가 됐다.

② DTCG(디자인 토큰 커뮤니티 그룹) 표준의 중심에 서 있음

W3C 산하 Design Tokens Community Group(DTCG)이 $value/$type 형식의 토큰 포맷 표준을 만드는 과정에 Tokens Studio 제작진이 깊이 관여했다. 플러그인 자체도 기존 방식(Legacy, value/type)과 W3C DTCG 방식($value/$type)을 상호 변환하는 기능을 내장하고 있어, 표준이 자리잡는 과정을 실제 코드에서 관찰할 수 있다.

③ 무료 코어 + 유료 Pro 확장이라는 지속가능한 모델

코어 기능(토큰 편집·GitHub 동기화·기본 테마)은 완전히 무료(MIT 라이선스, 오픈소스)이면서, 라이선스 키나 Tokens Studio 플랫폼 구독으로 풀리는 Pro 기능(고급 색상 모디파이어, TokenScript, Studio 플랫폼 실시간 동기화 등)을 얹는 구조다. 오픈소스 생태계에서 드물지 않은 모델이지만, 실제 코드에서 그 게이팅이 어떻게 클라이언트 훅 하나로 단순하게 구현돼 있는지가 흥미로운 관찰 포인트다(4·5·9절 참고).

3무엇을 해결하나

디자인 시스템을 운영하는 팀이 흔히 겪는 문제는 이렇다. 디자이너는 Figma에서 색상 팔레트를 스타일로 만들어 쓰고, 개발자는 그 색을 눈으로 보고 CSS 변수로 다시 타이핑한다. 나중에 디자이너가 브랜드 색을 바꾸면, 그 변경이 코드에 반영되기까지 사람이 손으로 옮기는 과정이 필요하다 — 늦고, 실수하기 쉽고, 어떤 값이 "진짜 최신"인지 헷갈린다.

Tokens Studio는 이 문제를 "토큰 JSON을 단일 진실원으로 두고, Figma와 코드 저장소 둘 다 그 JSON을 바라보게" 만들어 해결한다. 디자이너가 플러그인 안에서 토큰 값을 바꾸면 Figma 문서의 스타일·변수가 즉시 갱신되고, 같은 값이 GitHub 같은 저장소의 JSON 파일로 커밋되어 개발자의 빌드 파이프라인(Style Dictionary 등)이 그대로 소비할 수 있다.

4전체 구조

모든 Figma 플러그인은 구조적으로 두 개의 격리된 실행 환경을 갖는다. Tokens Studio도 예외가 아니라, 이 2프로세스 분리가 아키텍처의 뼈대다.

manifest.json의 "main": "dist/code.js"가 [2] 샌드박스에서, "ui": "dist/index.html"이 [1] iframe에서 각각 실행된다. 이 둘은 서로 다른 자바스크립트 컨텍스트라 변수도 함수도 공유할 수 없고, 오직 postMessage라는 메시지 전달로만 대화한다 — 마치 서로 다른 건물에 있는 두 팀이 편지로만 소통하는 것과 같다.

5핵심 설계·동작 원리

① 메시지 브릿지 — AsyncMessageChannel의 실제 코드

src/AsyncMessageChannel.ts는 이 플러그인 통신의 심장이다. 한 클래스가 같은 로직으로 양쪽 모두(PluginInstance는 샌드박스용, ReactInstance는 UI용)에 쓰인다. 생성자 인자 inFigmaSandbox 하나로 "내가 지금 어느 쪽에서 도는지"를 구분하고, 그에 따라 figma.ui.postMessage(샌드박스 → UI로 보낼 때)와 parent.postMessage(UI → 샌드박스로 보낼 때)를 갈라 쓴다.

class AsyncMessageChannel {
  public static PluginInstance: AsyncMessageChannel = new AsyncMessageChannel(true);
  public static ReactInstance: AsyncMessageChannel = new AsyncMessageChannel(false);

  protected $handlers: Partial<AsyncMessageChannelHandlers> = {};

  public handle<T extends AsyncMessageTypes>(type: T, fn: AsyncMessageChannelHandlers[T]) {
    this.$handlers[type] = fn;
  }

  public async message<Message extends AsyncMessages>(message: Message) {
    // 메시지마다 고유 id를 만들고, 응답이 같은 id로 돌아올 때까지 Promise로 대기
    const messageId = hash({ message, datetime: Date.now() });
    // ...postMessage로 보낸 뒤, id가 일치하는 응답을 resolve/reject
  }
}

핵심 트릭은 "요청마다 해시로 고유 id를 만들고, 응답이 그 id를 달고 돌아오면 Promise를 resolve"하는 패턴이다. postMessage는 원래 "쏘고 잊어버리는" 단방향 API인데, 이 id 매칭으로 await AsyncMessageChannel.ReactInstance.message({ type: 'PULL_VARIABLES' })처럼 마치 함수 호출처럼 쓸 수 있게 감싼 것이다. controller.ts는 이 채널에 PULL_STYLES·CREATE_LOCAL_VARIABLES·UPDATE_VARIABLES 등 80개가 넘는 메시지 타입 핸들러를 등록한다.

② 상태 관리 — Rematch(Redux) 모델 구조

UI 쪽 상태는 Redux 위에 Rematch라는 얇은 레이어를 얹어 관리한다. src/app/store/models/index.tsx는 6개 모델을 조합하는데, 그중 tokenState.tsx(1,222줄)가 토큰·테마·토큰 세트 전체를 다루는 가장 큰 모델이다.

Rematch의 장점은 reducer + action + effect(비동기 로직)를 한 "모델" 객체 안에 모아 보일러플레이트를 줄이는 것이다. tokenState 모델 내부는 다시 reducers/tokenState/*.ts(테마 저장, 토큰 세트 이름 변경 등)와 reducers/settingsState/*.ts(스타일·변수 생성 옵션 토글)로 잘게 쪼개져, 하나의 거대한 리듀서 함수가 되지 않도록 관리한다.

③ 토큰 → Figma 노드 적용 파이프라인 — setValuesOnNode

실제로 "이 텍스트 레이어에 spacing.md 토큰을 적용해줘"가 일어나는 지점은 src/plugin/setValuesOnNode.ts다. 이 함수는 하나의 거대한 if-else 대신, 속성별로 쪼갠 16개의 작은 apply 함수를 순서대로 호출하는 파이프라인이다.

await applyBorderValuesOnNode(node, data, values, baseFontSize);
await applyBorderRadiusValuesOnNode(node, data, values, baseFontSize);
await applyShadowValuesOnNode(node, data, values, baseFontSize);
// ... applyOpacityValuesOnNode, applySizingValuesOnNode, applySpacingValuesOnNode,
// applyColorTokenOnNode, applyTypographyTokenOnNode, applyAssetTokenValuesOnNode 등
await applyBooleanTokenValuesOnNode(node, data, values);

각 applyXxxValuesOnNode 함수 안에서는 다시 "이 값을 Figma 변수로 바인딩할지, 아니면 고정 값(raw value)으로만 박아넣을지"를 판단한다 — 사용자가 설정에서 "변수로 만들기"를 켰다면 setColorValuesOnVariable.ts 같은 파일이 figma.variables.createVariable API를 호출하는 경로로 빠지고, 아니면 레이어 속성에 값만 직접 쓴다. 이 "속성별 apply 함수 + 값/변수 이원화"가 이 저장소에서 가장 규모가 큰 코드 영역이다(src/plugin/apply*.ts 파일만 16개).

④ 토큰 참조·수식 해석 — {}·$ alias와 math 표현식

토큰 값 안에 {color.brand.primary}나 $color.brand.primary처럼 다른 토큰을 가리키는 참조(alias)를 쓸 수 있다. 이걸 실제 값으로 풀어내는 정규식이 src/constants/AliasRegex.ts에 있다.

// {foo} 형태 또는 $foo 형태를 모두 잡아내는 정규식
export const AliasRegex = /\{((?:[^{}]|{[^{}]*})*)\}|(?:\$([^\s,]+\w))/g;

src/utils/alias/getAliasValue.ts가 이 참조를 재귀적으로 따라가며 최종 값을 찾는다. 흥미로운 점은 토큰 값이 그냥 숫자·색이 아니라 사칙연산 수식일 수도 있다는 것이다. src/utils/math/checkAndEvaluateMath.ts는 expr-eval 라이브러리로 {spacing.sm} * 2 같은 식을 계산하고, clamped()·lerp()·cubicBezier1D() 같은 커스텀 함수까지 지원한다.

⑤ 테마와 토큰 세트 — "어떤 값 뭉치를 켤지"의 개념

Tokens Studio에서 토큰 세트(token set)는 토큰들을 담는 파일 같은 단위다(예: global.json, light.json, dark.json). 테마(theme)는 "지금 어떤 토큰 세트들을 켜서(active) 합칠지"를 정의한 조합이다 — 예를 들어 "Dark 테마 = global + dark 세트를 켠 상태"처럼. src/types/ThemeObject.ts가 이 조합을 정의하고, tokenState 모델의 reducers/tokenState/setActiveTheme.ts 등이 테마 전환 시 어떤 스타일·변수 id를 새 테마에 연결할지 처리한다.

⑥ 원격 저장소 동기화 프로바이더 — 10종의 스토리지

src/constants/StorageProviderType.ts에 정의된 저장 방식은 아래 10가지다. 각 프로바이더는 src/app/store/providers/<name>/ 폴더 하나씩을 갖고, "토큰 JSON을 어디서 읽고 어디로 쓸지"만 다르게 구현한다.

⑦ DTCG 포맷 지원 — 두 세계를 오가는 변환 스위치

src/plugin/TokenFormatStoreClass.ts가 현재 포맷이 Legacy(value/type 키)인지 W3C DTCG($value/$type 키)인지를 전역으로 들고 있고, ConvertToDTCGModal.tsx UI에서 사용자가 한 방향으로 변환할 수 있다. 변환은 되돌릴 수 없는 게 아니라, 원격 저장소가 있으면 w3c-dtcg-conversion이라는 이름의 브랜치를 만들어 커밋하므로 검토 후 병합할 수 있다.

⑧ Pro 기능 게이팅 — 코드에서는 그냥 "훅 하나"

라이선스 체계가 복잡할 거라 예상했다면, 실제 코드는 의외로 단순하다. src/app/hooks/useIsProUser.ts 전체가 이렇다.

export function useIsProUser() {
  const existingKey = useSelector(licenseKeySelector);
  const licenseKeyError = useSelector(licenseKeyErrorSelector);
  const { isPro } = useAuthStore();

  return useMemo(() => {
    const hasLicenseKey = Boolean(existingKey && !licenseKeyError);
    // 라이선스 키가 유효하거나, Tokens Studio OAuth 구독이 활성 상태면 Pro
    return hasLicenseKey || isPro;
  }, [existingKey, licenseKeyError, isPro]);
}

이 useIsProUser() 훅 하나를 ColorTokenForm.tsx(고급 색상 모디파이어), ManageStylesAndVariables.tsx(내보내기 옵션) 같은 컴포넌트 20여 곳에서 불러다 UI 요소를 보여줄지 숨길지를 결정한다. 즉 게이팅은 서버가 아니라 클라이언트(플러그인 UI) 쪽에서 조건부 렌더링으로 이뤄진다 — 실제 값 검증(라이선스 키가 진짜 유효한지)은 별도 라이선스 API가 담당하고, 그 결과만 Redux 셀렉터로 내려받는 구조다.

6기술 스택·의존성

7설치·요구사항

8실제 사용 흐름 — 디자인→코드 토큰 파이프라인

9함정·오해 방지

함정 ① "토큰을 지우면 Figma 값도 알아서 사라진다"는 오해

토큰과 레이어의 연결은 레이어에 저장된 숨은 메타데이터(pluginData)로 이뤄진다. 토큰을 지우거나 이름을 바꾸면, 플러그인이 문서를 다시 스캔해 해당 메타데이터를 가진 레이어를 찾아 갱신하는 절차가 필요하다 — 즉시 반영이 아니라 동기화 스캔이 한 번 더 필요한 비동기 과정이라는 점을 README도 명시한다. 대형 문서에서는 이 스캔이 눈에 띄게 걸릴 수 있다.

함정 ② "라이브러리(외부) 스타일"에는 적용이 안 될 수 있다

같은 색상 이름의 로컬 스타일은 플러그인이 값을 갱신할 수 있지만, 다른 파일에서 가져온 원격(라이브러리) 스타일은 Figma Plugin API 자체가 수정 권한을 주지 않는다. README는 이 경우 "raw hex 값을 대신 적용하니, 스타일 갱신은 Figma의 네이티브 Style 기능으로 하고 이 플러그인은 관리자 역할만 하라"고 권한다 — 문서가 스스로 한계를 인정하는 대목이다.

10대안 비교

요약하면 Tokens Studio는 "Figma 안에서 편집"과 "코드 저장소 동기화" 두 축 사이의 다리 역할에 특화됐고, 순수 변환(Style Dictionary)이나 전체 플랫폼(Supernova)과는 경쟁이라기보다 서로를 보완하는 조합으로 쓰이는 경우가 많다.

11정리 — 누가 쓰면 좋은가

디자인 시스템을 운영하는 팀(디자이너+개발자 협업)이라면, 색상·간격 값이 Figma와 코드에서 따로 놀지 않게 하려는 목적으로 이 플러그인이 정확히 맞는 도구다. 특히 이미 GitHub 등으로 코드를 관리하고 있고, 토큰 JSON을 Git 히스토리로 버전 관리하고 싶다면 자연스러운 선택이다.

Figma 플러그인 개발을 배우고 싶은 개발자에게도 이 저장소는 좋은 교재다. postMessage 기반의 2프로세스 통신, 대규모 Redux(Rematch) 상태 설계, 속성별로 잘게 쪼갠 "적용 파이프라인" 패턴은 어떤 Figma 플러그인을 만들든 재사용할 수 있는 아이디어다.

반대로 Figma를 아예 쓰지 않거나, 팀 규모가 작아 색상 몇 개를 손으로 맞춰도 무리 없는 경우라면 이 정도 규모의 도구는 과할 수 있다 — 그럴 때는 Figma 네이티브 Variables만으로도 충분할 수 있다.