Figma Variables ra mắt vào năm 2023 như là câu trả lời đã chờ đợi lâu của nền tảng cho design tokens. Tính năng này mạnh mẽ: các collection có tên của các giá trị nguyên thủy — màu sắc, số, chuỗi, boolean — mà bạn có thể ràng buộc với bất kỳ thuộc tính nào trong bất kỳ component nào. Thay đổi biến, mọi instance cập nhật. Thêm collection dark mode, mọi ràng buộc biến tự động hoán đổi.

Đối với AI codegen, Variables không chỉ hữu ích. Chúng là cơ chế chuyển đổi file Figma từ mockup hoàn hảo pixel thành thông số mà agent của bạn có thể triển khai chính xác. Khi một màu có tên — color/brand/primary, không phải #7F5CFE — agent có thể ánh xạ nó đến một code token, triển khai dark mode chính xác, và tạo ra output tham gia vào design system thực tế của bạn.

Đây là vấn đề: hầu hết các file Figma đang được sử dụng tích cực ngày nay không có Variables được thiết lập. figmascope xử lý cả hai trường hợp. Bài đăng này giải thích cách thức.

Variables thực sự là gì

Một Figma Variable là một scalar có tên được ràng buộc với một collection. Các collection tổ chức các biến theo mode — "Light" và "Dark" là ví dụ tiêu biểu. Mọi biến trong một collection có thể có các giá trị khác nhau theo mode: color/surface/background là #FFFFFF trong Light và #0D0D0D trong Dark. Ràng buộc lan truyền: mọi fill tham chiếu color/surface/background cập nhật khi bạn chuyển mode.

Variables có thể là màu sắc, số, chuỗi, hoặc boolean. Trên thực tế, có tác động nhất là màu sắc và số — bao gồm hầu hết bề mặt token trong một design system điển hình: bảng màu, thang spacing, border radii, cỡ chữ, giá trị elevation.

Figma hiển thị Variables qua REST API của nó như một collection localVariables. Mỗi biến có ID, tên, loại, và các giá trị theo mode. Các thuộc tính component tham chiếu các biến mang một trường boundVariables với ID biến. Đây là dữ liệu có cấu trúc di chuyển sạch sẽ qua pipeline extraction.

Con đường hạnh phúc: Variables có mặt

Khi một file Figma có Variables, figmascope đọc chúng từ API và xây dựng một tokens.json theo cấu trúc tương thích W3C Design Tokens Community Group. Mỗi token có $value và $type. Color token nhận giá trị hex với alpha tùy chọn. Spacing token nhận giá trị số với gợi ý đơn vị px. Tên token theo đường dẫn collection và name của biến:

{
  "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" }
  }
}

Khi per-screen IR được xây dựng, mọi fill có tham chiếu boundVariables nhận tên token thay vì hex đã giải quyết. Node mang:

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

Không phải #7F5CFE. Tên token. Agent đọc điều này và tạo ra background-color: var(--color-brand-primary) hoặc Color.brandPrimary hoặc bất cứ điều gì là mẫu tiêu thụ token của framework mục tiêu. Đó là output bạn muốn: code được kết nối với design system của bạn, không phải code sẽ hỏng ngay khi designer cập nhật một màu.

Đặt tên ngữ nghĩa là sự khác biệt giữa code già đi tốt và code bị trôi dạt. Một giá trị hex trong source là một trách nhiệm; một tham chiếu token là một hợp đồng. Variables là điều làm cho các file Figma có khả năng thể hiện hợp đồng, không chỉ là pixel.

Thực tế: hầu hết các file không có Variables

Variables yêu cầu gói Figma Professional trở lên. Chúng yêu cầu một designer đã thiết lập chúng — có nghĩa là tạo các collection, đặt tên biến, và thủ công ràng buộc chúng với mọi thuộc tính component. Trên một file design system trưởng thành, được duy trì tốt, điều này đã được thực hiện. Trên một file Figma sản phẩm của startup, file khách hàng freelancer, hoặc bất kỳ file nào trước tính năng Variables, thường thì chưa.

figmascope được thiết kế để hữu ích cho các file đó cũng vậy. Nó giảm cấp nhẹ nhàng: khi Variables vắng mặt, nó rơi xuống suy luận token dựa trên tần suất.

Fallback: inferred-from-frequency

Thuật toán suy luận hoạt động như sau:

  1. Duyệt mọi leaf node trong mọi frame được xuất.
  2. Thu thập tất cả màu fill, giá trị spacing, và border radii.
  3. Đếm số lần xuất hiện của mỗi giá trị duy nhất.
  4. Các giá trị xuất hiện trên ngưỡng tần suất được thăng cấp thành inferred token.
  5. Mỗi token nhận tên có nguồn gốc từ giá trị: color.7f5cfe, spacing.16, radius.8.

Output tokens.json trông có cấu trúc tương tự như đường dẫn Variables, nhưng tên có nguồn gốc từ giá trị thay vì ngữ nghĩa:

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

Trong IR, các node sử dụng các giá trị này nhận tham chiếu token: "tokenRef": "color.7f5cfe". Không phải literal hardcoded. Tham chiếu — chỉ là các inferred token thay vì có tên.

Agent vẫn tạo code được tham chiếu token. var(--color-7f5cfe) không dễ đọc như var(--color-brand-primary), nhưng nó vẫn là một token — bạn có thể tìm-và-thay thế nó, bạn có thể đổi tên nó, bạn có thể kiểm tra việc sử dụng của nó. Đó là một handle có tên trên một giá trị, không phải một magic number.

Trường tokensSource

Mọi bundle figmascope bao gồm một _meta.json ghi lại những gì trong bundle và cách nó được tạo ra. Trường tokensSource có ba giá trị có thể:

Điều này quan trọng vì nó cho agent tiêu dùng (và developer đọc bundle) biết chính xác mức độ tin tưởng tên token. Bundle figma-variables là nguồn sự thật cho design system của bạn. Bundle inferred-from-frequency là scaffold cấu trúc hữu ích cần xem xét đặt tên designer trước khi trở thành chính tắc. Bundle none là điểm khởi đầu với các giá trị hardcoded cần được tokenize sau.

Metadata trung thực bị đánh giá thấp. Các công cụ suy luận âm thầm mà không đánh dấu nó là suy luận tạo ra sự tự tin giả. figmascope hiển thị chuỗi suy luận một cách rõ ràng để bạn biết mình đang làm việc với gì.

Tại sao frequency inference tốt hơn là không có gì

Lựa chọn thay thế cho frequency inference là xuất các giá trị literal đã giải quyết ở khắp mọi nơi — #7F5CFE trong mọi fill node sử dụng màu đó. Điều này tạo ra code khó tái cấu trúc hơn, khó kiểm tra hơn, và khó kết nối với design system hơn khi một design system cuối cùng được thêm vào.

Frequency inference ít nhất trích xuất tập hợp các giá trị mà thiết kế thực sự sử dụng. Nếu #7F5CFE xuất hiện 47 lần trên thiết kế, đó là tín hiệu: đây là màu chính, không phải màu phụ. Tên token không biết điều đó — nó chỉ là color.7f5cfe — nhưng dữ liệu tần suất kể câu chuyện. Agent được cung cấp các inferred token có thể đưa ra đoán hợp lý về giá trị nào là chính và giá trị nào là một lần.

Thực tế hơn: frequency inference cho bạn một tokens.json có thể diff qua các phiên bản. Nếu bạn xuất cùng file hai lần sau khi designer thay đổi một màu lặp lại, diff hiển thị giá trị token thay đổi. Không có suy luận, bạn sẽ phải truy đuổi mọi thay đổi literal riêng lẻ rải rác trên nhiều file IR.

Những gì designer nên vẫn làm

Frequency inference là một lớp tương thích, không phải thay thế cho Variables. Con đường đúng đắn là designer áp dụng Variables cho tất cả các giá trị tham gia vào design system: brand color, neutral scale, spacing scale, border radii, elevation, typography. Khi những thứ đó đã đúng chỗ, bundle figmascope đi từ token chất lượng scaffold đến token chất lượng sản xuất.

Variables cũng mở khóa theming trong bundle: nhiều giá trị mode mỗi token. Một file với các mode Light/Dark tạo ra tokens.json với các giá trị theo mode trực tiếp đưa vào CSS custom properties với media query override, hoặc các theme object dành riêng cho nền tảng. Điều này không thể suy luận từ một snapshot thiết kế đơn lẻ — nó yêu cầu ý định rõ ràng của designer, được thể hiện qua Variables.

Con đường nâng cấp là dần dần. Một nhóm có thể bắt đầu với token chất lượng inference ngày hôm nay, áp dụng Variables dần dần khi design system trưởng thành, và nhận được bundle tốt hơn tự động khi họ làm vậy. Trường tokensSource theo dõi vị trí của bạn trong tiến trình đó.

Pipeline token đầy đủ

Để làm cụ thể, đây là thứ tự giải quyết đầy đủ mà figmascope sử dụng cho mỗi fill trong IR:

  1. Node có tham chiếu boundVariables.fills không? Nếu có, giải quyết đến tên biến và giá trị mode-zero. Token source: figma-variables.
  2. Giá trị đã giải quyết có mặt trong inferred frequency token (trên ngưỡng) không? Nếu có, ánh xạ đến tên inferred token. Token source: inferred-from-frequency.
  3. Nếu không: sử dụng giá trị hex đã giải quyết trực tiếp. Không có tham chiếu token. Token source: none.

Các bước được thử theo thứ tự. Nguồn chất lượng cao nhất thắng. Trường tokensSource trong _meta.json phản ánh con đường chủ yếu cho bundle tổng thể.

Điều này có nghĩa là một file có Variables một phần — nơi một số component có ràng buộc và một số thì không — tạo ra một bundle hỗn hợp. Named token nơi chúng tồn tại, inferred token nơi chúng không tồn tại. Đó là hành vi đúng: sử dụng mọi mảnh thông tin có cấu trúc có sẵn, giảm cấp nhẹ nhàng nơi nó thiếu, và trung thực về con đường mỗi giá trị đã đi.

Xuất bundle của bạn từ ứng dụng figmascope để xem tokensSource nào file của bạn tạo ra. Sau đó sử dụng bundle với Claude Code hoặc Cursor để tạo code chính xác, được tham chiếu token.