Arsitektur Token Multi-Tema dan Multi-Merek

Tema mengubah mode warna dari merek yang sama (versi terang dan gelap dari produk yang sama). Merek adalah identitas visual yang berbeda — komponen sistem desain yang sama ditampilkan dengan warna, tipografi, dan jarak yang berbeda untuk melayani produk atau pelanggan yang berbeda. Keduanya menggunakan arsitektur token yang sama, tetapi pada tingkat abstraksi yang berbeda.

Token primitif adalah palet lengkap nilai mentah yang tersedia bagi sistem. Token ini mencakup setiap tingkat warna (color-blue-50 hingga color-blue-900), setiap unit jarak, dan setiap ukuran fon. Token primitif tidak pernah digunakan langsung dalam komponen — token ini hanya dirujuk oleh token semantik. Palet ditentukan sekali dan digunakan bersama oleh semua tema dan merek.

Token semantik menyatakan maksud: color-background-page, color-text-primary, color-action-primary. Setiap token semantik merujuk ke nilai token primitif yang sesuai dengan tema saat ini. Komponen dibuat hanya berdasarkan token semantik. Di sinilah pemberian tema berlangsung.

Dalam tema terang: color-background-page merujuk ke color-white, color-text-primary merujuk ke color-gray-900, dan color-action-primary merujuk ke color-blue-500. Pemetaan ini ditentukan dalam berkas token khusus tema yang menimpa lapisan semantik untuk konteks terang.

Dalam tema gelap: color-background-page merujuk ke color-gray-950, color-text-primary merujuk ke color-gray-50, dan color-action-primary merujuk ke color-blue-400 (sedikit lebih terang untuk meningkatkan kontras pada latar belakang gelap). Hanya pemetaan semantik yang berubah — palet primitif dan semua komponen tetap tidak berubah.

Merek A menggunakan biru sebagai warna utama (color-action-primary: {color-blue-500}). Merek B menggunakan hijau (color-action-primary: {color-green-500}). Komponen tombol membaca var(--color-action-primary) — komponen tersebut sama sekali tidak mengetahui merek mana yang sedang aktif. Penimpaan merek hanya mengubah pemetaan token semantik, bukan kode komponen.

Properti khusus CSS membuat penggantian tema saat aplikasi berjalan menjadi sangat mudah. Simpan tema saat ini dalam atribut data: document.documentElement.setAttribute('data-theme', 'dark'). Aturan CSS menimpa token semantik di bawah [data-theme="dark"]. Peramban langsung menyelesaikan semua referensi var() ke nilai baru — tidak diperlukan perenderan ulang dengan JavaScript sama sekali.

Untuk merek berbeda yang disajikan sebagai penerapan terpisah, gunakan pemberian tema saat pembuatan: buat berkas token CSS terpisah untuk setiap merek dengan Style Dictionary, lalu muat CSS merek yang sesuai saat aplikasi dimulai. Pendekatan ini sesuai ketika merek ditentukan pada saat penerapan (domain, subdomain, atau instans dengan label merek berbeda), bukan saat interaksi pengguna.

Sistem multimerek dan multitema memerlukan matriks dua dimensi: Merek A Terang, Merek A Gelap, Merek B Terang, Merek B Gelap. Properti khusus CSS menangani hal ini dengan elegan melalui pemilih bertingkat: [data-brand="a"][data-theme="dark"] menimpa token semantik untuk kombinasi khusus tersebut. Empat kombinasi berarti empat blok CSS, bukan empat basis kode.

Seiring sistem desain berkembang, token ditambahkan, diganti nama, atau dihapus. Kelola versi token di repositori yang sama dengan kode. Saat menghentikan penggunaan token, pertahankan nama lama sebagai alias yang menunjuk ke nama baru selama satu siklus rilis, tambahkan komentar penghentian, dan perbarui kode yang menggunakannya. Koordinasikan perubahan token antara desain dan rekayasa perangkat lunak melalui catatan perubahan terstruktur.

Tata kelola menentukan siapa yang dapat menambahkan atau mengubah token serta proses peninjauan yang diwajibkan. Token primitif memerlukan persetujuan tim desain. Token semantik memerlukan peninjauan dari tim desain dan rekayasa. Token komponen dapat dikelola oleh pemilik komponen. Tanpa tata kelola ini, token duplikat akan muncul dan jaminan "satu-satunya sumber kebenaran" menjadi tidak berlaku.

Mengapa komponen harus merujuk token semantik, bukan token primitif?

Tema mengubah mode warna dalam sebuah merek; merek adalah identitas visual yang berbeda. Token primitif adalah palet mentah, sedangkan token semantik menyatakan makna dan memungkinkan penerapan tema. Komponen hanya menggunakan token semantik. Mode gelap dan penggantian merek hanya mengubah pemetaan token semantik—komponen tidak berubah. Penerapan tema saat runtime menggunakan properti khusus CSS dengan pemilih [data-theme]; pencitraan merek saat build menghasilkan CSS terpisah untuk setiap merek. Tata kelola dan pemberian versi token menjaga konsistensi sistem seiring perkembangannya.