Style Dictionary: Mentransformasi dan Menghasilkan Token

Style Dictionary (dibuat oleh Amazon) adalah alat untuk membangun sistem yang menerima definisi token desain dalam format JSON dan menghasilkan keluaran dalam format target apa pun: properti khusus CSS, modul ES JavaScript, variabel Sass, konstanta Swift untuk iOS, sumber daya XML Android, dan format khusus apa pun yang Anda tentukan. Satu sumber kebenaran, banyak keluaran.

Instal dengan npm install --save-dev style-dictionary. Inisialisasi struktur proyek dengan npx style-dictionary init, yang membuat config.json (atau config.js) dan direktori tokens/. Konfigurasi tersebut memberi tahu Style Dictionary tempat menemukan berkas token dan tempat menulis keluarannya.

Style Dictionary menggunakan struktur JSON bertingkat dengan simpul daun yang memiliki properti value. Sebagai contoh: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. Jalur menuju nilai (color, primary, 500) menjadi nama token setelah transformasi, biasanya diformat sebagai color-primary-500 atau --color-primary-500.

Jalankan npx style-dictionary build --config config.json (atau style-dictionary build jika dikonfigurasi dalam skrip package.json). Style Dictionary membaca semua berkas token dari sumber yang dikonfigurasi, menerapkan transformasi, lalu menulis keluaran ke tujuan yang dikonfigurasi. Kesalahan dalam format token dilaporkan bersama nama dan jalur berkas.

config.json menentukan platform: css (menghasilkan berkas CSS dengan properti khusus), js (menghasilkan objek JS), dan scss (menghasilkan variabel Sass). Setiap platform menentukan direktori keluaran, nama berkas, format (templat), dan transformasi (fungsi pemrosesan nama dan nilai) yang akan diterapkan.

Style Dictionary menyertakan transformasi bawaan: name/cti/kebab mengonversi jalur bertingkat menjadi color-primary-500, name/cti/camel menghasilkan colorPrimary500, size/rem mengonversi nilai piksel menjadi rem, dan color/hex menormalkan warna ke format heksadesimal. Transformasi dapat dirangkai dan diterapkan secara berurutan.

Anda dapat mendaftarkan transformasi khusus dengan StyleDictionary.registerTransform(). Sebagai contoh, transformasi yang mengonversi nilai piksel menjadi titik iOS, atau yang menambahkan awalan khusus perusahaan ke semua nama token. Transformasi khusus memberi Anda kendali penuh atas cara nilai diproses sebelum dikeluarkan.

Format khusus menentukan templat berkas keluaran. StyleDictionary.registerFormat() menerima kamus token yang telah ditransformasi dan mengembalikan teks — isi berkas. Anda dapat menghasilkan token sebagai tipe TypeScript, objek tema React, ekstensi konfigurasi Tailwind, atau format lain yang diperlukan oleh tumpukan teknologi Anda.

Setelah proses pembuatan selesai, impor keluaran CSS dalam lembar gaya global Anda: @import './tokens/tokens.css'. Impor keluaran JS dalam komponen atau konfigurasi Tailwind: import tokens from './tokens/tokens.js'. CSS memberi Anda properti khusus untuk penggantian tema saat aplikasi berjalan; JS memberi Anda konstanta bertipe untuk Tailwind dan logika JavaScript.

Style Dictionary mendukung referensi token menggunakan kurung kurawal: { "value": "{color.primary.500}" }. Ini membuat rujukan alternatif token semantik — token semantik tersebut merujuk ke token primitif. Saat proses pembuatan, Style Dictionary menyelesaikan referensi dan menghasilkan nilai akhir (atau referensi variabel CSS, bergantung pada format Anda).

Jalankan Style Dictionary sebagai skrip npm prebuild agar token selalu dibuat ulang sebelum aplikasi dibuat. Tambahkan "prebuild": "style-dictionary build" ke package.json. Ini memastikan setiap perubahan pada berkas JSON token tercermin dalam keluaran CSS dan JS sebelum proses pembuatan React dijalankan.

Apa tujuan transformasi dalam Style Dictionary?

Style Dictionary mengonversi JSON token menjadi format keluaran apa pun: variabel CSS, modul JS, Sass, iOS, dan Android. JSON token menggunakan objek bertingkat dengan simpul daun value. Transformasi memproses nama dan nilai (camelCase, px-to-rem); format menentukan templat keluaran. Referensi token ({color.primary.500}) memungkinkan pembuatan alias semantik. Otomatiskan dengan skrip prebuild agar token selalu terbaru sebelum proses pembuatan React.