Arsitektur Token

Token desain Majalengka disusun mengikuti standar spesifikasi terbuka W3C Design Tokens Community Group (DTCG). Format JSON ini memastikan token dapat dibaca langsung oleh Figma Tokens Studio serta dapat dikompilasi ke CSS Variables, TypeScript, Tailwind, atau UnoCSS.

Konvensi Penamaan

Setiap variabel token mengikuti pola:

--mjl-{kategori}-{peran}-{varian}-{state}

Contoh Nyata

• --mjl-color-surface-canvas: Warna latar belakang kanvas halaman.
• --mjl-color-action-primary-default: Warna tombol primer keadaan default.
• --mjl-color-action-primary-hover: Warna tombol primer saat kursor melayang (hover).
• --mjl-space-4: Jarak spasi baku 16px.
• --mjl-radius-md: Radius lengkungan sudut 10px.

Struktur Berkas Sumber DTCG

packages/tokens/src/
├── global/          # color.json, typography.json, spacing.json, elevation.json
└── semantic/        # light.json, dark.json

Dari JSON Semantik ke CSS Variable

semantic/light.json dan semantic/dark.json adalah satu-satunya sumber token semantik — tidak ada nilai yang ditulis manual di skrip build. Aturan konversinya:

{
  "action": {
    "primary": {
      "bg": { "$type": "color", "$value": "{color.primary.700}" },
      "fg": { "$type": "color", "$value": "#FFFFFF" }
    }
  }
}

Build (bun run build:tokens) akan gagal bila:

• sebuah referensi menunjuk token yang tidak ada, atau
• dark.json tidak punya kunci yang persis sama dengan light.json. Mode gelap wajib mendefinisikan ulang semua token, karena CSS variable yang berisi var() dihitung di elemen tempat ia dideklarasikan — token yang terlewat akan tetap bernilai mode terang.

Grup color.* di file semantik berisi alias nama lama (--mjl-color-surface-*, --mjl-color-text-*, dst.) agar kode yang sudah ada tetap jalan. Untuk kode baru, pakai token fungsional --mjl-bg-*, --mjl-text-*, --mjl-border-*, dan --mjl-action-*.

Output kompilasi menghasilkan:

1. @majalengka/tokens/css (dist/tokens.css): Seluruh token global + token semantik mode terang dan gelap.
2. @majalengka/tokens/css/dark (dist/tokens-dark.css): Hanya blok override tema gelap ([data-theme="dark"], [data-mode="dark"], .dark). Muat setelah tokens.css.
3. @majalengka/tokens (dist/index.js): Typed JavaScript exports untuk framework berbasis JavaScript/TypeScript.