tokens.json Explained — Design Token Bertipe untuk AI Codegen

Setiap ekspor figmascope menyertakan tokens.json. Ini adalah jembatan antara nilai visual Figma dan konstanta bertipe yang dibutuhkan kode Anda. Artikel ini mencakup skema, cara kunci diberi nama, apa yang terjadi ketika file Figma tidak memiliki Variables, dan di mana sistem token secara jujur memiliki kekurangan.

Skema

Struktur tingkat atas memiliki empat bagian:

{
  "spacing": {
    "spacing.4":  { "$value": 4,  "$type": "dimension" },
    "spacing.8":  { "$value": 8,  "$type": "dimension" },
    "spacing.12": { "$value": 12, "$type": "dimension" },
    "spacing.16": { "$value": 16, "$type": "dimension" },
    "spacing.24": { "$value": 24, "$type": "dimension" }
  },
  "radius": {
    "radius.4":  { "$value": 4,  "$type": "dimension" },
    "radius.8":  { "$value": 8,  "$type": "dimension" },
    "radius.12": { "$value": 12, "$type": "dimension" }
  },
  "color": {
    "color.7f5cfe": { "$value": "#7f5cfe", "$type": "color" },
    "color.ffffff": { "$value": "#ffffff", "$type": "color" },
    "color.1a1a2e": { "$value": "#1a1a2e", "$type": "color" }
  },
  "typography": {}
}

Formatnya mirip W3C Design Tokens Community Group: setiap token adalah objek dengan $value dan $type. Ini bukan implementasi W3C DTCG yang ketat — figmascope mendahului publikasi spesifikasi akhir dan tidak mengimplementasikan tipe komposit seperti fontFamily — tetapi cukup dekat sehingga perkakas yang mengenal DTCG dapat mengurainya dengan sedikit adaptasi.

Objek typography yang kosong bukan bug. Ini dijelaskan di bawah.

Penamaan kunci berbasis nilai

Ketika file Figma memiliki Variables, kunci token berasal dari nama Variable yang ditetapkan desainer. spacing.md, color.brand.primary, apa pun yang digunakan sistem desain.

Ketika file Figma tidak memiliki Variables — yang merupakan mayoritas file Figma di dunia nyata — figmascope kembali ke penamaan berbasis nilai. Nilai spacing 16 menjadi spacing.16. Warna #7f5cfe menjadi color.7f5cfe. Corner radius 4 menjadi radius.4.

Ini adalah tradeoff yang disengaja. Nama berbasis nilai tidak cantik tetapi stabil. Nama tersebut diturunkan dari nilai aktual, sehingga dua run berbeda dari file Figma yang sama menghasilkan kunci yang sama. spacing.16 selalu berarti 16dp. Agen dapat mengandalkannya.

Alternatifnya adalah nama posisional seperti spacing.1, spacing.2 dst. Itu rapuh — tambahkan nilai spacing yang lebih kecil dan semuanya bergeser. Nama berbasis nilai tidak bergeser.

Nama berbasis nilai adalah fallback untuk file yang seharusnya memiliki Variables tetapi tidak. Jika sistem desain Anda memiliki 40 nilai spacing yang semuanya membutuhkan nama semantik, dorong desainer untuk menyiapkan Variables. Fallback inferensi ada untuk file di dunia nyata, bukan sebagai pengganti sistem token yang nyata. Anda dapat menjalankan figmascope pada file Anda sendiri untuk melihat jalur sumber mana yang diambil.

Field tokensSource dan artinya

_meta.json menyertakan field tokensSource yang memberi tahu Anda cara token diturunkan:

Peringatan "tokens-inferred-from-frequency" dalam _meta.json mencerminkan ini. Jika Anda melihatnya, cakupan token adalah upaya terbaik.

Ketika tokensSource adalah "inferred-from-frequency", algoritma inferensinya adalah: temukan semua nilai dimensi yang muncul dalam tiga node atau lebih di field padding, gap, atau cornerRadius. Promosikan tersebut ke token spacing atau radius masing-masing. Lakukan hal yang sama untuk warna fill. Nilai yang hanya muncul sekali atau dua kali diperlakukan sebagai satu kali, tidak dipromosikan.

Ini berfungsi dengan baik untuk desain yang konsisten secara internal. Ini berfungsi buruk untuk desain eksplorasi di mana spacing bervariasi bebas. Peringatan _meta.json ada tepat agar agen tahu situasi mana yang dihadapi.

Mengapa tipografi sering kosong

Token tipografi memerlukan Figma Variables dengan tipe FLOAT atau STRING untuk diekstrak secara andal. Gaya teks ada di Figma sebagai gaya bersama, bukan Variables, dan permukaan API untuk gaya berbeda dari Variables API.

figmascope v0.4 mengekstrak tipografi ketika Variables mencakupnya. Ia tidak mencoba inferensi berbasis frekuensi untuk tipografi karena token tipografi yang berguna — famili font, tinggi baris, spasi huruf, kombinasi bobot — tidak memiliki nama berbasis nilai yang jelas seperti spacing.16. Kunci fontSize.14 jauh kurang berguna dari typography.body.small, dan menghasilkan nama yang buruk lebih buruk dari tidak menghasilkan nama sama sekali.

Jadi hasilnya jujur: jika file Figma Anda memiliki Variables tipografi, Anda mendapatkan token tipografi. Jika tidak, Anda mendapatkan objek kosong dan agen diberi tahu melalui CONTEXT.md bahwa cakupan tipografi mungkin sebagian.

// _meta.json
{
  "tokensSource": "inferred-from-frequency",
  "warnings": [
    "tokens-inferred-from-frequency"
  ]
}

Agen melihat ini dan tahu untuk bersikap konservatif tentang referensi token tipografi. Ia menghasilkan kode fallback dengan nilai eksplisit dan komentar TODO daripada menciptakan nama token.

Cara agen menggunakan tokens.json

Batasan CONTEXT.md adalah: "Jangan pernah hardcode nilai dp jika token ada dalam ±2dp." Toleransi ±2dp menangani pembulatan. Jika node memiliki paddingLeft: 15 dan spacing.16 ada, agen menggunakan spacing.16. Jika token terdekat adalah spacing.24, tidak ada kecocokan — agen menggunakan nilai literal.

Untuk warna, pencocokan tepat pada nilai hex setelah normalisasi ke 6-digit huruf kecil. #7F5CFE cocok dengan color.7f5cfe.

Untuk corner radius, aturan ±2dp yang sama seperti spacing.

Output praktis untuk target Jetpack Compose terlihat seperti ini:

// Dengan tokensSource figma-variables
Surface(
    shape = RoundedCornerShape(Radius.radius8),
    color = Color.Brand.Primary
) {
    Column(
        verticalArrangement = Arrangement.spacedBy(Spacing.spacing16),
        modifier = Modifier.padding(horizontal = Spacing.spacing24)
    ) { ... }
}

// Dengan tokensSource inferred-from-frequency (output visual sama, referensi token sama)
Surface(
    shape = RoundedCornerShape(Radius.radius8),
    color = Color.color7f5cfe
) { ... }

Nama berbasis nilai kurang terbaca. Namun tetap lebih baik dari nilai hardcoded.

Perbandingan dengan pendekatan ekstraksi token lainnya

Panel "Inspect" native Figma menampilkan nilai per node. Tidak ada file token yang diekspor. Anda harus membuatnya secara manual atau menggunakan plugin seperti Tokens Studio. Keduanya memerlukan usaha desainer dan pemeliharaan berkelanjutan.

figmascope mengekstrak token secara otomatis pada setiap ekspor. Jika file berubah, ekspor ulang dan token mencerminkan keadaan saat ini. Tradeoffnya adalah tanpa Variables, nama berbasis nilai daripada semantik — tetapi Anda mendapatkan file token setiap kali, tanpa plugin atau langkah alur kerja tambahan.

Tokens Studio (sebelumnya integrasi Style Dictionary) mengharuskan desainer menyiapkan plugin, memelihara file JSON dalam file Figma, dan menyinkronkannya. Itu adalah solusi yang tepat untuk sistem desain yang matang. Pendekatan figmascope adalah solusi yang tepat untuk file yang belum sampai ke sana, yang merupakan sebagian besar file.

Ekstraksi token adalah snapshot upaya terbaik dari apa yang ada dalam file. Ini bukan pengganti sistem desain yang mengutamakan token. Ini adalah hal yang Anda gunakan saat membangun menuju satu.

Menghubungkan tokens.json ke basis kode Anda

Struktur JSON cukup flat sehingga menghasilkan objek Kotlin atau modul TypeScript darinya sangat mudah. Skrip sederhana:

// tokens.json → objek Kotlin (disederhanakan)
const tokens = JSON.parse(fs.readFileSync('tokens.json', 'utf-8'));

let output = 'object Spacing {\n';
for (const [key, token] of Object.entries(tokens.spacing)) {
    const name = key.replace('spacing.', 'spacing').replace('.', '_');
    output += `    val ${name} = ${token.$value}.dp\n`;
}
output += '}';
// → val spacing16 = 16.dp

Jika Anda sudah menggunakan pipeline design token, format mirip W3C cukup dekat untuk dimasukkan ke Style Dictionary dengan transformer kustom untuk kunci $value/$type.

Sisa tentang cara token berinteraksi dengan IR dibahas di Per-Screen IR. Untuk cara token berinteraksi dengan konteks agen yang lebih luas, lihat Anatomi CONTEXT.md. Untuk alur kerja ekspor design token end to end, lihat Design Token Export. Untuk mengekspor token dari file Figma Anda sendiri, pergi ke figmascope.dev.