Design Token dengan Tailwind: Theme yang Selamat dari Rebrand

Seorang klien pernah meminta saya mengganti warna brand mereka. Permintaan sederhana — kecuali warna lama itu di-hardcode di 340 tempat di seluruh codebase: utility class, nilai hex di CSS, inline style, satu-dua SVG, dan beberapa konfigurasi chart. Yang seharusnya edit satu baris menjadi seminggu penuh grep, regresi, dan QA di setiap halaman. Proyek itulah alasan saya sekarang menyiapkan design token sejak hari pertama, bahkan untuk landing page.

Artikel ini adalah arsitektur token yang saya pakai dengan Tailwind — diperbarui untuk v4, di mana directive @theme menjadikan CSS variable mekanisme theming native. Tujuannya satu ujian yang jujur: jika warna brand, skala tipografi, atau ritme spacing berubah, berapa baris yang Anda edit? Jawaban yang benar adalah satu per keputusan.

Token Adalah Keputusan yang Diberi Nama

Lepaskan semua tooling-nya dan design token hanyalah keputusan desain yang diberi nama: nilai 0.75rem tidak berarti apa-apa, tapi radius-card sama dengan 0.75rem adalah pernyataan bahwa card di sistem ini punya pembulatan segini. Nama membawa niat; nilai adalah detail implementasi. Pembalikan itu adalah inti permainannya — kode harus bergantung pada niat, jangan pernah pada nilai mentah.

Mode kegagalan kebanyakan codebase Tailwind adalah melewatkan penamaan dan memakai palet langsung. Class text-orange-500 tidak mengatakan aksen brand; ia mengatakan oranye persis ini, selamanya. Utility palet Tailwind adalah primitif, dan primitif di kode komponen adalah nilai hardcode dengan ergonomi lebih baik. Mereka terasa seperti sistem, dan justru itulah yang membuat mereka berbahaya saat rebrand.

Arsitektur Tiga Tier

Setiap sistem token yang selamat dari kontak dengan rebrand berakhir dengan tiga tier yang sama, apa pun sebutan timnya:

Tailwind v4: @theme Adalah Mesin Token Anda

Tailwind v4 memindahkan theming dari konfigurasi JavaScript ke dalam CSS itu sendiri. Variable yang dideklarasikan di dalam directive @theme bukan custom property CSS biasa — masing-masing menginstruksikan Tailwind untuk menghasilkan utility class. Deklarasikan token warna dan Anda otomatis mendapat utility bg, text, border, dan fill untuknya; deklarasikan sebagai alias dari primitif dan seluruh rantainya tetap hidup:

/* app/globals.css — Tailwind v4 token architecture */
@import "tailwindcss";

@theme {
  /* TIER 1 — primitives: raw values, never used in components */
  --color-orange-500: oklch(0.71 0.19 41);
  --color-slate-900: oklch(0.21 0.04 266);
  --spacing: 0.25rem;            /* one base unit drives the scale */
  --font-sans: var(--font-inter);

  /* TIER 2 — semantic: the only names components may use */
  --color-brand: var(--color-orange-500);
  --color-surface: var(--color-slate-900);
  --color-text-muted: oklch(0.71 0.03 264);
  --radius-card: 0.75rem;

  /* TIER 3 — component tokens, only when a component
     genuinely needs its own knob */
  --color-button-primary-bg: var(--color-brand);
}

/* Components now write: bg-brand, bg-surface, text-text-muted,
   rounded-card — and a rebrand edits ONE line:
   --color-brand: var(--color-blue-600);              */

Perhatikan apa yang dihasilkan struktur ini: komponen hanya pernah melihat nama tier dua. Class di JSX terbaca seperti bahasa desain — bg-surface, text-text-muted, rounded-card — dan pemetaan dari bahasa ke piksel hidup di tepat satu file. Saat portfolio ini perlu aksen oranyenya dituning demi kontras di latar gelap, editnya satu nilai oklch. Setiap card, tombol, link, dan focus ring mengikuti.

Penamaan yang Selamat dari Rebrand

Sistem token tidak mati karena kekurangan tooling; mereka mati karena nama yang mengkodekan hal yang salah. Empat aturan menjaga nama tetap jujur:

Token di Luar CSS: Format DTCG dan Style Dictionary

@theme milik Tailwind sempurna saat web app adalah satu-satunya konsumen. Begitu token harus memberi makan aplikasi React Native, Android native, template email, atau library Figma, Anda butuh sumber kebenaran yang agnostik terhadap tool. Itulah yang diberikan format Design Tokens Community Group: skema JSON di mana setiap token mendeklarasikan nilai bertipe dengan prefiks dolar, dirancang khusus untuk interoperabilitas antara tool desain dan build system. Style Dictionary kemudian mengompilasi JSON itu menjadi apa pun yang dimakan tiap platform:

// tokens/color.tokens.json — DTCG format, the tool-agnostic source
{
  "color": {
    "brand": {
      "$type": "color",
      "$value": "#FF6F20",
      "$description": "Primary brand accent"
    },
    "surface": {
      "$type": "color",
      "$value": "#0F172A"
    }
  }
}

// style-dictionary.config.js — fan out to every platform
export default {
  source: ["tokens/**/*.tokens.json"],
  platforms: {
    css:   { transformGroup: "css",  files: [{ destination: "tokens.css",  format: "css/variables" }] },
    ts:    { transformGroup: "js",   files: [{ destination: "tokens.ts",   format: "javascript/es6" }] },
    android: { transformGroup: "android", files: [{ destination: "colors.xml", format: "android/colors" }] }
  }
}

Untuk proyek Next.js solo, lapisan ini berlebihan — @theme saja sudah jumlah arsitektur yang tepat. Saya meraih setup DTCG-plus-Style-Dictionary saat platform kedua muncul atau saat desainer memelihara token di Figma dengan plugin yang mengekspor format tersebut. Keputusan arsitekturnya sama seperti biasa: satu sumber kebenaran, dikompilasi keluar, tidak pernah dipelihara paralel.

Simulasi Kebakaran Rebrand: Checklist

Anda tidak tahu sistem token Anda bekerja sampai Anda mensimulasikan peristiwa yang menjadi alasan keberadaannya. Punya saya menjalani latihan ini sebelum design system dirilis:

1. Ubah primitif warna brand utama dan jangan arahkan ulang apa pun. Setiap permukaan ber-brand harus mengikuti; yang tidak mengikuti adalah kebocoran yang harus diperbaiki.
2. Tukar token font stack. Heading, body, dan chrome UI harus berubah bersama, dengan kabel variable next/font tetap utuh.
3. Naikkan unit dasar spacing satu langkah. Ritme layout harus menskala dengan koheren, bukan rusak di lima komponen yang meng-hardcode piksel.
4. Balik theme antara gelap dan terang dengan hanya menukar nilai semantik — primitif tak tersentuh di kedua mode.
5. Grep komponen untuk class bernomor palet dan nilai hex mentah. Hitungannya harus nol; aturan CI menjaganya tetap nol.

Kesimpulan

Design token bukan kemewahan perusahaan besar — mereka adalah beda antara rebrand yang selesai sore itu juga dan yang memakan satu sprint. Tailwind v4 menurunkan biaya melakukannya dengan benar menjadi nyaris nol: blok @theme terstruktur dengan primitif, alias semantik, dan disiplin menjauhkan nama palet dari komponen. Siapkan sejak hari pertama. Grep 340 kemunculan adalah wujud dari menunggu.