Figma Variables는 2023년에 플랫폼의 오랫동안 기다려왔던 디자인 토큰 대답으로 등장했습니다. 기능은 강력합니다: 명명된 기본 값의 컬렉션 — 색상, 숫자, 문자열, 불리언 — 을 어떤 컴포넌트의 어떤 속성에도 바인딩할 수 있습니다. 변수를 변경하면 모든 인스턴스가 업데이트됩니다. 다크 모드 컬렉션을 추가하면 모든 변수 바인딩이 자동으로 교체됩니다.

AI 코드 생성에서 Variables는 단순히 유용한 것이 아닙니다. Figma 파일을 픽셀 완벽한 목업에서 에이전트가 올바르게 구현할 수 있는 명세로 변환하는 메커니즘입니다. 색상에 이름이 있으면 — #7F5CFE가 아닌 color/brand/primary — 에이전트가 코드 토큰에 매핑하고, 다크 모드를 올바르게 구현하고, 실제 디자인 시스템에 참여하는 출력을 생성할 수 있습니다.

문제는 이렇습니다: 현재 사용 중인 대부분의 Figma 파일에는 Variables가 설정되어 있지 않습니다. figmascope는 두 경우를 모두 처리합니다. 이 글에서는 그 방법을 설명합니다.

Variables가 실제로 무엇인가

Figma Variable은 컬렉션에 바인딩된 명명된 스칼라입니다. 컬렉션은 모드별로 변수를 구성합니다 — "라이트"와 "다크"가 정식 예시입니다. 컬렉션의 모든 변수는 모드별로 다른 값을 가질 수 있습니다: color/surface/background는 라이트에서 #FFFFFF이고 다크에서 #0D0D0D입니다. 바인딩이 전파됩니다: color/surface/background를 참조하는 모든 채우기가 모드를 전환할 때 업데이트됩니다.

Variables는 색상, 숫자, 문자열, 또는 불리언일 수 있습니다. 실제로 가장 영향력 있는 것은 색상과 숫자입니다 — 이것은 일반적인 디자인 시스템의 대부분의 토큰 표면을 커버합니다: 색상 팔레트, 간격 스케일, 테두리 반경, 폰트 크기, 고도 값.

Figma는 REST API를 통해 Variables를 localVariables 컬렉션으로 노출합니다. 각 변수에는 ID, 이름, 유형, 그리고 모드별 값이 있습니다. Variables를 참조하는 컴포넌트 속성은 변수 ID가 있는 boundVariables 필드를 포함합니다. 이것은 추출 파이프라인을 통해 깔끔하게 전달되는 구조화된 데이터입니다.

행복한 경로: Variables가 있는 경우

Figma 파일에 Variables가 있으면 figmascope가 API에서 읽고 W3C 디자인 토큰 커뮤니티 그룹 호환 구조를 따르는 tokens.json을 구성합니다. 각 토큰에는 $value와 $type이 있습니다. 색상 토큰은 선택적 알파가 있는 hex 값을 얻습니다. 간격 토큰은 px 단위 힌트가 있는 숫자 값을 얻습니다. 토큰 이름은 변수의 컬렉션 및 이름 경로를 따릅니다:

{
  "color": {
    "brand": {
      "primary": { "$value": "#7F5CFE", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#FFFFFF", "$type": "color" }
    }
  },
  "spacing": {
    "4": { "$value": 4, "$type": "number" },
    "8": { "$value": 8, "$type": "number" },
    "16": { "$value": 16, "$type": "number" }
  }
}

화면별 IR이 구성될 때, boundVariables 참조가 있는 모든 채우기는 해결된 hex 대신 토큰 이름을 얻습니다. 노드는 다음을 포함합니다:

"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]

#7F5CFE가 아닙니다. 토큰 이름입니다. 에이전트는 이를 읽고 대상 프레임워크의 토큰 소비 패턴이 무엇이든 background-color: var(--color-brand-primary) 또는 Color.brandPrimary를 생성합니다. 이것이 원하는 출력입니다: 디자이너가 색상을 업데이트하는 순간 깨지지 않고 디자인 시스템에 연결된 코드.

시맨틱 명명은 잘 유지되는 코드와 드리프트하는 코드의 차이입니다. 소스의 hex 값은 부채입니다. 토큰 참조는 계약입니다. Variables는 Figma 파일이 픽셀만이 아닌 계약을 표현할 수 있게 하는 것입니다.

현실: 대부분의 파일에는 Variables가 없습니다

Variables는 Figma Professional 플랜 이상이 필요합니다. 설정한 디자이너가 필요합니다 — 컬렉션을 생성하고, 변수를 명명하고, 모든 컴포넌트 속성에 수동으로 바인딩하는 것을 의미합니다. 성숙하고 잘 유지되는 디자인 시스템 파일에서는 완료되어 있습니다. 스타트업의 제품 Figma, 프리랜서의 클라이언트 파일, 또는 Variables 기능 이전의 파일에서는 일반적으로 없습니다.

figmascope는 그 파일들에도 유용하도록 설계되었습니다. 우아하게 저하됩니다: Variables가 없을 때 빈도 기반 토큰 추론으로 폴백합니다.

폴백: 빈도에서 추론

추론 알고리즘은 다음과 같이 작동합니다:

  1. 모든 내보낸 프레임의 모든 리프 노드를 순회합니다.
  2. 모든 채우기 색상, 간격 값, 테두리 반경을 수집합니다.
  3. 각 고유 값의 발생 횟수를 계산합니다.
  4. 빈도 임계값 이상으로 나타나는 값은 추론된 토큰으로 승격됩니다.
  5. 각 토큰은 값에서 파생된 이름을 얻습니다: color.7f5cfe, spacing.16, radius.8.

출력 tokens.json은 Variables 경로와 구조적으로 유사하게 보이지만, 이름은 시맨틱이 아닌 값에서 파생됩니다:

{
  "color": {
    "7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
    "f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
  },
  "spacing": {
    "16": { "$value": 16, "$type": "number" },
    "8": { "$value": 8, "$type": "number" }
  }
}

IR에서 이 값을 사용하는 노드는 토큰 참조를 얻습니다: "tokenRef": "color.7f5cfe". 하드코딩된 리터럴이 아닙니다. 참조 — 단지 명명된 것이 아닌 추론된 토큰에 대한 참조.

에이전트는 여전히 토큰 참조 코드를 생성합니다. var(--color-7f5cfe)는 var(--color-brand-primary)만큼 읽기 좋지 않지만, 여전히 토큰입니다 — 찾아서 교체하고, 이름을 바꾸고, 사용을 감사할 수 있습니다. 매직 넘버가 아닌 값에 대한 명명된 핸들입니다.

tokensSource 필드

모든 figmascope 번들에는 번들의 내용과 생성 방법을 문서화하는 _meta.json이 포함됩니다. tokensSource 필드에는 세 가지 가능한 값이 있습니다:

이것이 중요한 이유는 소비하는 에이전트(및 번들을 읽는 개발자)에게 토큰 이름을 얼마나 신뢰해야 하는지 정확히 알려주기 때문입니다. figma-variables 번들은 디자인 시스템의 진실의 원천입니다. inferred-from-frequency 번들은 정식이 되기 전에 디자이너 이름 검토가 필요한 유용한 구조적 스캐폴드입니다. none 번들은 나중에 토큰화해야 하는 하드코딩된 값이 있는 시작점입니다.

솔직한 메타데이터는 과소평가됩니다. 추론임을 표시하지 않고 조용히 추론하는 도구는 잘못된 자신감을 만듭니다. figmascope는 추론 체인을 명시적으로 표면화하여 무엇으로 작업하는지 알 수 있게 합니다.

빈도 추론이 없는 것보다 나은 이유

빈도 추론의 대안은 모든 채우기 노드에서 해결된 리터럴 값을 출력하는 것입니다 — 그 색상을 사용하는 모든 채우기 노드에서 #7F5CFE. 이것은 리팩터링하기 어렵고, 감사하기 어렵고, 결국 디자인 시스템이 추가될 때 연결하기 어려운 코드를 생성합니다.

빈도 추론은 최소한 디자인이 실제로 사용하는 값 집합을 추출합니다. #7F5CFE가 디자인 전체에서 47번 나타난다면, 그것은 신호입니다: 이것은 기본 색상이지 액센트가 아닙니다. 토큰 이름은 그것을 알지 못합니다 — 단지 color.7f5cfe일 뿐 — 하지만 빈도 데이터가 이야기를 말해줍니다. 추론된 토큰이 주어진 에이전트는 어떤 값이 기본이고 어떤 것이 일회성인지 합리적으로 추측할 수 있습니다.

더 실용적으로: 빈도 추론은 버전 간에 diff 가능한 tokens.json을 제공합니다. 디자이너가 반복 색상을 변경한 후 동일한 파일을 두 번 내보내면, diff는 토큰 값이 변경되었음을 보여줍니다. 추론 없이는 여러 IR 파일에 흩어진 모든 개별 리터럴 변경을 추적해야 합니다.

디자이너가 여전히 해야 할 것

빈도 추론은 호환성 레이어이지 Variables의 대안이 아닙니다. 올바른 경로는 디자이너가 디자인 시스템에 참여하는 모든 값에 Variables를 채택하는 것입니다: 브랜드 색상, 중립 스케일, 간격 스케일, 테두리 반경, 고도, 타이포그래피. 이것들이 자리 잡으면 figmascope 번들은 스캐폴드 품질 토큰에서 프로덕션 품질 토큰으로 이동합니다.

Variables는 또한 번들의 테마를 해제합니다: 토큰당 여러 모드 값. 라이트/다크 모드가 있는 파일은 미디어 쿼리 오버라이드가 있는 CSS 사용자 정의 속성이나 플랫폼별 테마 객체에 직접 공급되는 모드별 값이 있는 tokens.json을 생성합니다. 이것은 단일 디자인 스냅샷에서 추론하는 것이 불가능합니다 — Variables를 통해 표현된 명시적인 디자이너 의도가 필요합니다.

업그레이드 경로는 점진적입니다. 팀은 오늘 추론 품질 토큰으로 시작하고, 디자인 시스템이 성숙함에 따라 점진적으로 Variables를 채택하고, 자동으로 더 나은 번들을 얻을 수 있습니다. tokensSource 필드는 그 진행 상황에서 어디에 있는지 추적합니다.

전체 토큰 파이프라인

구체적으로 보면, figmascope가 IR의 각 채우기에 사용하는 전체 해결 순서는 다음과 같습니다:

  1. 노드에 boundVariables.fills 참조가 있습니까? 있으면 변수 이름과 모드 제로 값으로 해결합니다. 토큰 소스: figma-variables.
  2. 해결된 값이 추론된 빈도 토큰에 있습니까(임계값 이상)? 있으면 추론된 토큰 이름에 매핑합니다. 토큰 소스: inferred-from-frequency.
  3. 그렇지 않으면: 해결된 hex 값을 직접 사용합니다. 토큰 참조 없음. 토큰 소스: none.

단계는 순서대로 시도됩니다. 가장 높은 품질의 소스가 이깁니다. _meta.json의 tokensSource 필드는 전체 번들의 지배적인 경로를 반영합니다.

이것은 부분적으로 Variables가 있는 파일 — 일부 컴포넌트에는 바인딩이 있고 다른 것들에는 없는 — 이 혼합 번들을 생성함을 의미합니다. 있는 곳에는 명명된 토큰, 없는 곳에는 추론된 토큰. 이것이 올바른 동작입니다: 사용 가능한 모든 구조화된 정보를 사용하고, 없는 곳에는 우아하게 폴백하고, 각 값이 어떤 경로를 취했는지에 대해 솔직합니다.

figmascope 앱에서 번들을 내보내 파일이 어떤 tokensSource를 생성하는지 확인하세요. 그런 다음 Claude Code 또는 Cursor와 함께 번들을 사용하여 정확하고 토큰 참조된 코드를 생성하세요.