design.md vs Design Tokens untuk Alur Kerja UI AI

Nama saya Dora. Sebagian besar waktu kerja saya dihabiskan di dalam coding agent dan alat UI berbasis AI — Cursor, Claude Code, Stitch, dan sejenisnya — membangun dan membangun ulang antarmuka lebih cepat dari yang sempat saya dokumentasikan. Sekitar sebulan lalu, saya mulai melihat file yang sama muncul di hampir setiap repo yang saya sentuh: DESIGN.md. Nama yang sama, bentuk yang sama — YAML di atas, prosa di bawah. Pada proyek ketiga, saya sadar ini bukan kebetulan. Ini adalah sesuatu yang menggantikan apa yang dulu banyak dari kita kirimkan sebagai tokens.json.

Jadi saya membangun ulang salah satu library komponen saya sendiri dua kali — sekali dengan file token bergaya DTCG klasik, sekali dengan DESIGN.md — lalu menjalankan coding agent yang sama pada keduanya. Ini adalah bagian dari perbandingan yang tidak saya temukan tertulis: bukan tentang apa itu masing-masing format, melainkan apa yang sebenarnya dioptimalkan oleh masing-masing format, dan mana yang seharusnya ada di stack Anda sekarang.

design.md vs Design Tokens Tradisional

Apa yang dioptimalkan oleh masing-masing format

Design token, dalam pengertian klasiknya, adalah sebuah metodologi. Istilah ini diciptakan di Salesforce sekitar tahun 2014 untuk memecahkan masalah skalabilitas yang sangat spesifik: bagaimana Anda menjaga keputusan warna tetap sinkron di web, iOS, Android, dan empat codebase tanpa membuat empat tiket? Jawabannya adalah pasangan nama-nilai yang agnostik terhadap platform, disimpan dalam JSON atau YAML, lalu ditransformasi saat build time menjadi apa pun yang dibutuhkan setiap platform. Metodologi itu kini dikodifikasi oleh Design Tokens Community Group di W3C, dan per akhir 2025, format DTCG telah memiliki spesifikasi v1 yang stabil.

Token mengoptimalkan untuk distribusi deterministik. Kode hex masuk, kode hex yang sama keluar di setiap platform, setiap build, selamanya. Tidak ada ambiguitas. Tidak ada narasi juga — file token memberi tahu Anda primary: #1A1C1E tetapi tidak menjelaskan mengapa warna itu ada atau kapan sebaiknya tidak digunakan.

DESIGN.md, yang dibuat open-source oleh Google Labs pada April 2026, mengoptimalkan sesuatu yang berbeda: memberi coding agent cukup konteks untuk membuat keputusan yang tidak dicakup oleh file token. Ini adalah satu file markdown dengan YAML front matter untuk token dan prosa di bawahnya untuk alasan di baliknya. File yang sama, dua audiens — bagian deterministik untuk parser, bagian naratif untuk LLM mana pun yang membaca repo.

Itulah pembedaan yang sesungguhnya. Bukan “lama vs baru.” Bukan “JSON vs Markdown.” Ini nilai vs nilai plus alasan dalam satu file yang sama.

Mengapa AI agent menciptakan kebutuhan yang baru

Ketika seorang manusia mengimplementasikan desain, celah antara “token mengatakan #1A1C1E” dan “halaman kosong ini membutuhkan nada bicara tertentu” diisi oleh manusia itu sendiri. Mereka sudah melihat file Figma. Mereka hadir dalam workshop brand. Mereka tahu tombol sekunder seharusnya terasa tenang, bukan asertif.

Coding agent tidak memiliki semua itu. Ia hanya memiliki apa yang Anda masukkan ke dalam repo dan apa yang bisa disimpulkannya dari nama file. Jadi ketika Anda memintanya menghasilkan sebuah layar yang tidak sepenuhnya dispesifikasikan oleh file token — edge case, komponen baru, keputusan tata letak — ia akan menebak atau kembali ke apa yang paling sering dilihatnya saat training. Inilah asal muasal estetika “AI beige” yang banyak dikeluhkan orang: bukan model yang buruk, hanya konteks yang kurang.

Inilah yang dipecahkan oleh DESIGN.md. Spesifikasi resmi di GitHub menyatakannya secara eksplisit — token memberi agent nilai yang tepat, prosa memberi tahu mereka mengapa nilai-nilai itu ada dan bagaimana cara menerapkannya. Format ini mengharapkan kedua bagian tersebut.

Di Mana design.md Memberikan Nilai

Konteks naratif yang persisten

Hal yang saya perhatikan dalam 48 jam pertama pengujian: agent yang sama, dengan brief yang sama, menghasilkan output yang terasa berbeda ketika konteks prosa hadir. Bukan “warna yang sedikit lebih baik.” Pilihan tata letak berbeda, register salinan berbeda, kepadatan komponen berbeda. Nilai token identik di kedua jalankan — yang berubah adalah apakah agent memiliki paragraf yang mengatakan “suara brand bersifat tenang dan editorial; utamakan ruang putih daripada dekorasi.”

Inilah bagian yang tidak dibawa oleh pipeline token tradisional. File JSON DTCG dapat mendeskripsikan --color-primary dengan tepat, tetapi tidak dapat memberi tahu agent bahwa warna utama itu dimaksudkan untuk digunakan secara hemat. DESIGN.md membawa penilaian itu ke setiap pass generasi, secara persisten, tanpa siapa pun harus mengetiknya ulang ke dalam prompt.

Ini berhasil.

Konsistensi multi-layar yang lebih baik untuk workflow generasi

Dalam uji kedua saya, saya menghasilkan delapan layar untuk aplikasi yang sama selama dua hari. Dengan konteks hanya token, layar 5–8 mulai menyimpang — palet sama, tetapi bahasa tata letak menjadi lebih longgar. Dengan DESIGN.md yang hadir, penyimpangan itu jauh lebih kecil. Tidak nol. Lebih kecil.

Menurut saya alasannya: bagian prosa berfungsi sebagai jangkar ulang setiap kali agent membaca file. Token saja memberi agent cukup untuk benar pada nilai-nilai individual. Narasi memberinya cukup untuk konsisten di seluruh keputusan yang tidak diantisipasi oleh token. Untuk generasi sekali pakai, celah itu tidak masalah. Untuk output multi-layar dan iterasi yang berkelanjutan, celah itu terakumulasi.

Di sinilah DESIGN.md juga bekerja dengan baik bersama stack instruksi agent yang lebih luas — sebagian besar setup sekarang mereferensikannya dari AGENTS.md bersama file SKILL.md, sehingga sistem desain berada di lapisan konteks yang sama dengan instruksi persisten agent lainnya.

Di Mana Token Tradisional Masih Unggul

Dua skenario, keduanya nyata.

Distribusi lintas platform di luar web. Jika Anda mengirimkan sistem desain yang sama ke iOS, Android, aplikasi React Native, dan situs pemasaran, pipeline DTCG melalui Style Dictionary atau Terrazzo masih merupakan jalur yang paling mudah. YAML milik DESIGN.md dapat diekspor ke DTCG JSON melalui CLI resmi @google/design.md, tetapi pertanyaan sumber kebenaran masih penting — jika grafik token Anda besar, multi-tema, dan dikonsumsi oleh tooling non-AI, mempertahankan DTCG sebagai format kanonik adalah setup yang lebih bersih.

Sistem desain matang dengan tata kelola yang sudah mapan. Token bukan sekadar format file. Ini adalah metodologi dengan praktik yang terakumulasi selama sekitar satu dekade — lapisan primitif, lapisan semantik, aliasing, theming, seluruh taksonomi yang diuraikan oleh Nathan Curtis dalam Tokens in Design Systems. Jika tim Anda sudah beroperasi dengan cara itu, DESIGN.md tidak menggantikannya. DESIGN.md berada di atasnya, atau di sampingnya, sebagai lapisan konteks untuk agent. Token tetap menjadi sumber kanonik; markdown menjadi terjemahan yang menghadap AI.

Kesalahan yang akan terjadi adalah membaca DESIGN.md sebagai pengganti pipeline token. Bukan begitu. Ini adalah lapisan berbeda dengan konsumen yang berbeda.

Kerangka Keputusan untuk Tim yang Membangun Pipeline UI berbasis AI

Saya selalu kembali ke empat pertanyaan saat memutuskan apa yang akan dimasukkan ke dalam repo:

Siapa yang akan membaca file ini? Jika konsumen utamanya adalah pipeline build yang menghasilkan CSS, Swift, dan Kotlin, Anda ingin token dalam format kanonik. Jika konsumen utamanya adalah coding agent yang menghasilkan UI sesuai permintaan, Anda ingin DESIGN.md. Jika keduanya, Anda menyimpan keduanya — dan membiarkan YAML file markdown mencerminkan sebagian token.
Seberapa sering permukaan UI Anda diregenerasi? Tim dengan frekuensi rendah (produk stabil, sesekali layar baru) mendapatkan sebagian besar nilainya dari token. Tim dengan frekuensi tinggi (prototipe cepat, iterasi berbasis agent, layar baru setiap minggu) merasakan celah konteks yang hilang dengan tajam. Semakin tinggi frekuensi regenerasi, semakin besar lapisan prosa membuktikan nilainya.
Berapa banyak platform? Hanya web atau utamanya web dengan generasi berbasis agent — DESIGN.md adalah stack yang lebih sederhana. Tiga platform atau lebih dengan kehadiran native yang serius — utamakan token, dengan DESIGN.md sebagai artefak hilir.
Apakah alasannya sudah terdokumentasi di suatu tempat? Jika panduan brand, dokumen suara, dan filosofi komponen Anda berada di halaman Notion yang tidak akan pernah dibaca oleh agent, DESIGN.md adalah langkah leverage tunggal tertinggi yang dapat Anda lakukan kuartal ini. Anda tidak membuat dokumentasi baru — Anda memindahkan dokumentasi yang sudah ada ke dalam file yang benar-benar dibuka oleh agent.

Itulah kerangka kerja saya. Milik Anda mungkin berbeda. Yang ingin saya tekankan: jangan memilih format karena ia baru. Pilih karena siapa yang akan membaca file tersebut.

FAQ

Apakah design.md pengganti design token?

Tidak. DESIGN.md adalah pembungkus yang berisi design token (dalam YAML front matter) ditambah alasan di baliknya (dalam prosa markdown). Token di dalamnya masih merupakan design token dalam pengertian konvensional. Jika Anda sudah memiliki file token berformat DTCG, DESIGN.md tidak menggantikannya — ia berada sebagai artefak paralel untuk AI agent, atau Anda dapat membuat markdown mengekspor DTCG JSON saat diperlukan.

Mengapa AI agent membutuhkan lebih dari sekadar token numerik?

Karena sebagian besar permintaan pembuatan UI tidak sepenuhnya dispesifikasikan oleh grafik token. “Buat halaman pricing” membutuhkan ratusan keputusan mikro — hierarki, kepadatan, nada, apa yang harus ditekankan — yang tidak dicakup oleh file token mana pun. Tanpa konteks naratif, agent mengisi celah tersebut dengan apa yang dilihatnya dalam data training, yang menghasilkan tampilan generik yang dimiliki oleh sebagian besar UI yang dihasilkan AI. Prosa dalam DESIGN.md adalah yang menutup celah tersebut.

Workflow mana yang paling diuntungkan dari design.md?

Tiga pola yang menurut saya paling menguntungkan:

Builder solo dan tim kecil yang menggunakan Cursor, Claude Code, atau Stitch untuk mengirimkan UI lebih cepat dari yang bisa mereka tulis secara manual.
Tim sistem desain yang memelihara beberapa produk internal di mana konsistensi di seluruh layar yang dihasilkan AI menjadi masalah nyata.
Agensi dan tim kontrak yang menginginkan satu file drop-in yang mengkodekan bahasa desain klien untuk coding agent mana pun.

Jika workflow Anda sebagian besar dikode secara manual dengan bantuan AI sesekali, nilai marginalnya berkurang.

Kapan infrastruktur design token klasik masih cukup?

Ketika Anda tidak menghasilkan UI dengan agent, atau ketika jangkauan platform Anda jauh melampaui web. Native mobile berat, produk white-label multi-tema, praktik design ops yang matang — ini semua masih mendapatkan lebih banyak dari ekosistem DTCG daripada dari file markdown. Keduanya tidak saling eksklusif, tetapi jika Anda harus memilih satu untuk diinvestasikan, jawabannya tergantung pada di mana sebenarnya gesekan generasi Anda berada.

Kesimpulan

Versi jujurnya: DESIGN.md bukanlah pergeseran paradigma. Ini adalah solusi terfokus untuk celah yang spesifik — coding agent yang kekurangan alasan yang tidak dibawa oleh file token. Untuk workflow di mana celah itu nyata, keuntungannya langsung terasa dan jelas. Untuk workflow di mana tidak, token tradisional masih melakukan pekerjaan dengan baik.

Saya sudah dua bulan menggunakan DESIGN.md di setiap proyek generasi AI yang saya jalankan. Ini tetap ada dalam workflow, yang merupakan satu-satunya uji yang saya percaya. File token pun tidak ke mana-mana — mereka masih melakukan apa yang selalu mereka lakukan, hanya sekarang dengan file saudara untuk audiens yang membutuhkan lebih dari sekadar angka.

Coba sendiri di sebuah proyek. Dua hari akan memberi tahu Anda lebih banyak dari yang bisa dilakukan artikel ini.

Postingan sebelumnya：