Token di Tailwind, Variabel CSS, dan CSS-in-JS

Output platform CSS dari Style Dictionary menghasilkan berkas properti kustom CSS: --color-primary-500: #3b82f6; --spacing-4: 16px; dan seterusnya. Variabel ini didefinisikan pada :root, sehingga tersedia secara global. Inilah dasar untuk semua penggunaan token dalam aplikasi.

Impor berkas token CSS yang dihasilkan ke dalam lembar gaya global atau komponen tata letak akar: @import './tokens/tokens.css'. Dalam Next.js, impor berkas tersebut di app/layout.tsx atau styles/globals.css. Setelah diimpor, setiap aturan CSS dan komponen dalam aplikasi dapat merujuk ke properti kustom tersebut.

Rujuk variabel CSS dalam lembar gaya komponen atau CSS Modules: background-color: var(--color-primary-500); dan padding: var(--spacing-4);. Jika nilai token berubah dalam sumber JSON, pembangunan ulang Style Dictionary akan memperbarui berkas CSS, dan semua komponen yang menggunakan variabel tersebut otomatis mencerminkan nilai baru.

Properti kustom CSS memungkinkan penggantian tema saat aplikasi berjalan. Untuk mode gelap, timpa nilai token di bawah pemilih tema: [data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }. Menetapkan document.documentElement.setAttribute('data-theme', 'dark') akan langsung mengganti semua nilai token tanpa memuat ulang atau membangun ulang aplikasi.

Perluas tema Tailwind dalam tailwind.config.js untuk menggunakan nilai token: theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }. Impor hasil JS dari Style Dictionary ke dalam konfigurasi Tailwind untuk memastikan kelas Tailwind (bg-primary-500) selalu menggunakan nilai token acuan.

Untuk tema yang dapat diganti saat aplikasi berjalan dalam Tailwind, konfigurasikan warna agar merujuk ke variabel CSS: 'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'. Variabel CSS Anda harus menyimpan komponen RGB tanpa pembungkus rgb() (--color-primary-rgb: 59 130 246). Tailwind kemudian menangani utilitas opasitas secara otomatis.

Pustaka CSS-in-JS menggunakan objek tema JavaScript. Berikan hasil JS Style Dictionary sebagai nilai penyedia tema: <ThemeProvider theme={tokens}>. Komponen mengakses token melalui const theme = useTheme() dan theme.color.primary[500]. Style Dictionary menghasilkan objek token bertipe; penyedia tema mendistribusikannya.

Plugin stylelint-no-hardcoded-colors dan aturan ESLint khusus dapat memastikan tidak ada nilai heksadesimal yang ditulis langsung dalam lembar gaya atau berkas komponen. Jika pengembang menulis color: #3b82f6 alih-alih color: var(--color-primary-500), pemeriksa kode akan melaporkannya. Dengan demikian, sistem token tetap menjadi satu-satunya sumber warna.

Ketika nama kelas Tailwind dibuat secara dinamis dari nama token saat runtime, proses pembersihan Tailwind dapat menghapus kelas tersebut karena nama-nama itu tidak muncul sebagai string statis dalam kode sumber. Tambahkan pola kelas dinamis ke safelist dalam tailwind.config.js: safelist: [{ pattern: /bg-primary-/ }].

Plugin Figma Tokens mengekspor nilai token Figma langsung ke format JSON Style Dictionary. Alurnya: desainer memperbarui warna dalam Figma Variables, mengekspornya melalui plugin, menyimpan JSON yang diperbarui ke repositori, skrip prapembangunan menjalankan Style Dictionary, lalu hasil CSS dan JS yang diperbarui digunakan dalam aplikasi React. Desain dan kode tetap sinkron.

Properti kustom CSS memiliki lingkup pada elemen tempat properti tersebut didefinisikan dan semua turunannya. Hal ini memungkinkan penimpaan tema tingkat komponen: komponen kartu dapat menetapkan --color-background: var(--color-surface-elevated) pada elemen akarnya, dan semua turunannya menggunakan warna permukaan yang ditinggikan tanpa meneruskan properti melalui banyak komponen.

Apa keunggulan utama menggunakan properti kustom CSS (variabel) untuk token desain dibandingkan nilai Tailwind statis?

Style Dictionary menghasilkan properti kustom CSS untuk impor global dan objek JS untuk integrasi Tailwind serta CSS-in-JS. Variabel CSS memungkinkan penggantian tema saat aplikasi berjalan melalui penimpaan [data-theme]. Tailwind memperluas konfigurasinya dengan nilai token dari hasil JS; untuk tema yang mendukung opasitas, konfigurasikan Tailwind agar merujuk ke variabel CSS RGB. Aturan pemeriksaan kode menegakkan penggunaan warna yang hanya berasal dari token, sehingga nilai yang ditulis langsung tidak masuk ke basis kode.