Figma Variables hadir pada tahun 2023 sebagai jawaban platform yang sudah lama ditunggu untuk design token. Fitur ini kuat: koleksi nilai primitif yang diberi nama — warna, angka, string, boolean — yang dapat Anda ikat ke properti apa pun di komponen mana pun. Ubah variabelnya, setiap instance diperbarui. Tambahkan koleksi mode gelap, setiap pengikatan variabel bertukar secara otomatis.

Untuk AI codegen, Variables bukan hanya berguna. Mereka adalah mekanisme yang mengubah file Figma dari mockup yang sempurna secara piksel menjadi spesifikasi yang dapat diimplementasikan agen Anda dengan benar. Ketika warna memiliki nama — color/brand/primary, bukan #7F5CFE — agen dapat memetakannya ke token kode, mengimplementasikan mode gelap dengan benar, dan menghasilkan output yang berpartisipasi dalam design system Anda yang sebenarnya.

Inilah masalahnya: sebagian besar file Figma yang aktif digunakan saat ini tidak memiliki Variables yang disiapkan. figmascope menangani kedua kasus tersebut. Artikel ini menjelaskan caranya.

Apa sebenarnya Variables itu

Figma Variable adalah skalar bernama yang terikat pada koleksi. Koleksi mengatur variabel berdasarkan mode — "Light" dan "Dark" adalah contoh kanonik. Setiap variabel dalam koleksi dapat memiliki nilai berbeda per mode: color/surface/background adalah #FFFFFF di Light dan #0D0D0D di Dark. Pengikatan merambat: setiap fill yang mereferensikan color/surface/background diperbarui saat Anda beralih mode.

Variables dapat berupa warna, angka, string, atau boolean. Dalam praktiknya, yang paling berdampak adalah warna dan angka — yang mencakup sebagian besar area permukaan token dalam design system yang umum: palet warna, skala spacing, border radii, ukuran font, nilai elevasi.

Figma mengekspos Variables melalui REST API-nya sebagai koleksi localVariables. Setiap variabel memiliki ID, nama, tipe, dan nilai-per-mode. Properti komponen yang mereferensikan variabel membawa bidang boundVariables dengan ID variabel. Ini adalah data terstruktur yang berjalan bersih melalui pipeline ekstraksi.

Jalur yang menyenangkan: Variables ada

Ketika file Figma memiliki Variables, figmascope membacanya dari API dan membangun tokens.json mengikuti struktur yang kompatibel dengan W3C Design Tokens Community Group. Setiap token memiliki $value dan $type. Token warna mendapatkan nilai hex dengan alpha opsional. Token spacing mendapatkan nilai numerik dengan petunjuk satuan px. Nama token mengikuti jalur koleksi dan nama variabel:

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

Ketika per-screen IR dibangun, setiap fill yang memiliki referensi boundVariables mendapatkan nama token alih-alih hex yang diselesaikan. Node membawa:

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

Bukan #7F5CFE. Nama token. Agen membaca ini dan menghasilkan background-color: var(--color-brand-primary) atau Color.brandPrimary atau apa pun pola konsumsi token framework target. Itulah output yang Anda inginkan: kode yang terhubung ke design system Anda, bukan kode yang akan rusak saat desainer memperbarui warna.

Penamaan semantik adalah perbedaan antara kode yang bertahan dengan baik dan kode yang menyimpang. Nilai hex dalam sumber adalah liabilitas; referensi token adalah kontrak. Variables adalah yang membuat file Figma mampu mengekspresikan kontrak, bukan hanya piksel.

Kenyataannya: sebagian besar file tidak memiliki Variables

Variables memerlukan paket Figma Professional atau lebih tinggi. Mereka memerlukan desainer yang telah menyiapkannya — yang berarti membuat koleksi, memberi nama variabel, dan secara manual mengikatnya ke setiap properti komponen. Pada file design system yang matang dan terpelihara dengan baik, ini sudah dilakukan. Pada Figma produk startup, file klien freelancer, atau file apa pun yang dibuat sebelum fitur Variables, biasanya tidak.

figmascope dirancang agar berguna untuk file-file itu juga. Ia terdegradasi dengan anggun: ketika Variables tidak ada, ia kembali ke inferensi token berbasis frekuensi.

Fallback: inferred-from-frequency

Algoritma inferensi bekerja seperti ini:

  1. Telusuri setiap node leaf di setiap frame yang diekspor.
  2. Kumpulkan semua warna fill, nilai spacing, dan border radii.
  3. Hitung kemunculan setiap nilai unik.
  4. Nilai yang muncul di atas ambang frekuensi dipromosikan ke token yang disimpulkan.
  5. Setiap token mendapatkan nama yang diturunkan dari nilai: color.7f5cfe, spacing.16, radius.8.

Output tokens.json terlihat secara struktural mirip dengan jalur Variables, tetapi namanya diturunkan dari nilai daripada semantik:

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

Dalam IR, node yang menggunakan nilai ini mendapatkan referensi token: "tokenRef": "color.7f5cfe". Bukan literal yang di-hardcode. Referensi — hanya ke token yang disimpulkan daripada yang diberi nama.

Agen masih menghasilkan kode yang direferensikan token. var(--color-7f5cfe) tidak se-mudah dibaca seperti var(--color-brand-primary), tetapi tetap merupakan token — Anda dapat melakukan find-and-replace, Anda dapat mengubah namanya, Anda dapat mengaudit penggunaannya. Ini adalah pegangan bernama pada nilai, bukan angka ajaib.

Bidang tokensSource

Setiap bundle figmascope menyertakan _meta.json yang mendokumentasikan apa yang ada dalam bundle dan bagaimana ia diproduksi. Bidang tokensSource memiliki tiga kemungkinan nilai:

Ini penting karena memberi tahu agen yang mengonsumsi (dan pengembang yang membaca bundle) seberapa banyak harus mempercayai nama token. Bundle figma-variables adalah sumber kebenaran untuk design system Anda. Bundle inferred-from-frequency adalah perancah struktural yang berguna yang memerlukan tinjauan penamaan desainer sebelum menjadi kanonik. Bundle none adalah titik awal dengan nilai yang di-hardcode yang perlu ditokenisasi nanti.

Metadata yang jujur sangat dihargai. Alat yang menyimpulkan secara diam-diam tanpa menandainya sebagai inferensi menciptakan kepercayaan palsu. figmascope memperlihatkan rantai inferensi secara eksplisit sehingga Anda tahu apa yang sedang Anda kerjakan.

Mengapa inferensi frekuensi lebih baik daripada tidak sama sekali

Alternatif untuk inferensi frekuensi adalah menghasilkan nilai literal yang diselesaikan di mana-mana — #7F5CFE di setiap node fill yang menggunakan warna itu. Ini menghasilkan kode yang lebih sulit di-refactor, lebih sulit diaudit, dan lebih sulit dihubungkan ke design system ketika akhirnya ditambahkan.

Inferensi frekuensi minimal mengekstrak set nilai yang sebenarnya digunakan desain. Jika #7F5CFE muncul 47 kali di seluruh desain, itu adalah sinyal: ini adalah warna primer, bukan aksen. Nama token tidak mengetahui itu — ini hanya color.7f5cfe — tetapi data frekuensi menceritakan kisahnya. Agen yang diberi token yang disimpulkan dapat membuat tebakan yang masuk akal tentang nilai mana yang primer dan mana yang satu kali.

Lebih praktis lagi: inferensi frekuensi memberi Anda tokens.json yang dapat di-diff di seluruh versi. Jika Anda mengekspor file yang sama dua kali setelah desainer mengubah warna yang berulang, diff menunjukkan nilai token berubah. Tanpa inferensi, Anda akan mengejar setiap perubahan literal individual yang tersebar di beberapa file IR.

Apa yang masih harus dilakukan desainer

Inferensi frekuensi adalah lapisan kompatibilitas, bukan pengganti Variables. Jalur yang tepat adalah desainer mengadopsi Variables untuk semua nilai yang berpartisipasi dalam design system: warna merek, skala netral, skala spacing, border radii, elevasi, tipografi. Setelah itu tersedia, bundle figmascope berubah dari token berkualitas perancah menjadi token berkualitas produksi.

Variables juga membuka tema dalam bundle: beberapa nilai mode per token. File dengan mode Light/Dark menghasilkan tokens.json dengan nilai per-mode yang langsung dimasukkan ke properti CSS kustom dengan penggantian media query, atau objek tema khusus platform. Ini tidak mungkin disimpulkan dari satu snapshot desain — ini memerlukan maksud desainer yang eksplisit, diekspresikan melalui Variables.

Jalur peningkatan bersifat inkremental. Tim dapat mulai dengan token berkualitas inferensi hari ini, mengadopsi Variables secara bertahap seiring design system matang, dan mendapatkan bundle yang lebih baik secara otomatis seiring melakukannya. Bidang tokensSource melacak di mana Anda berada dalam kemajuan itu.

Pipeline token secara lengkap

Untuk membuatnya konkret, inilah urutan resolusi lengkap yang digunakan figmascope untuk setiap fill dalam IR:

  1. Apakah node memiliki referensi boundVariables.fills? Jika ya, resolusikan ke nama variabel dan nilai mode-zero. Sumber token: figma-variables.
  2. Apakah nilai yang diselesaikan ada dalam token frekuensi yang disimpulkan (di atas ambang)? Jika ya, petakan ke nama token yang disimpulkan. Sumber token: inferred-from-frequency.
  3. Jika tidak: gunakan nilai hex yang diselesaikan secara langsung. Tidak ada referensi token. Sumber token: none.

Langkah-langkah dicoba secara berurutan. Sumber berkualitas tertinggi menang. Bidang tokensSource di _meta.json mencerminkan jalur dominan untuk bundle secara keseluruhan.

Ini berarti file yang sebagian menggunakan Variables — di mana beberapa komponen memiliki pengikatan dan yang lain tidak — menghasilkan bundle campuran. Token bernama di mana mereka ada, token yang disimpulkan di mana mereka tidak. Itu adalah perilaku yang tepat: gunakan setiap potongan informasi terstruktur yang tersedia, mundur dengan anggun di mana itu hilang, dan jujur tentang jalur mana yang ditempuh setiap nilai.

Ekspor bundle Anda dari aplikasi figmascope untuk melihat tokensSource mana yang dihasilkan file Anda. Kemudian gunakan bundle dengan Claude Code atau Cursor untuk generasi kode yang akurat dan direferensikan token.