Apa Itu design.md untuk Coding Agent?

Nama saya Dora. Minggu lalu saya meminta Claude Code untuk menambahkan tiga layar baru ke proyek sampingan. Pada layar kedua, radius tombol sudah bergeser, font judul secara diam-diam berubah, dan warna abu-abu “sekunder” menjadi abu-abu yang berbeda. Struktur prompt yang sama. Model yang sama. Sesi yang sama. Hasilnya hanya berhenti peduli dengan apa yang sudah ada sebelumnya.

Inilah gesekan yang design.md untuk coding agent coba hilangkan. Ini adalah file markdown biasa yang menyimpan design system Anda dalam bentuk yang dapat dibaca oleh AI agent setiap kali ia menghasilkan UI — bukan sebagai prompt sekali pakai, melainkan sebagai konteks persisten. Stitch membacanya. Claude Code membacanya. Cursor membacanya. Apa pun yang mengambil file konteks dari root repo juga akan membacanya.

Apa Itu design.md dan Mengapa Google Labs Menerbitkannya

Format file dan peran design-system

File DESIGN.md adalah dua lapisan yang digabungkan dalam satu dokumen. Bagian atas adalah YAML front matter — warna, tipografi, spasi, sudut membulat, komponen — ditulis sebagai token terstruktur. Di bawahnya adalah prosa markdown yang menjelaskan untuk apa token-token tersebut dan bagaimana menggunakannya. Token memberikan nilai yang tepat kepada agent. Prosa menjelaskan mengapa nilai-nilai tersebut ada.

Berikut kira-kira tampilan front matter-nya, diambil dari spesifikasi DESIGN.md resmi di GitHub:

yaml

---
version: alpha
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
---

Di bawahnya, terdapat ## Overview, ## Colors, ## Typography dalam markdown biasa. Urutan bagian sudah ditetapkan — Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts. Bagian dapat dilewati, tetapi yang ada harus muncul dalam urutan tersebut. Judul bagian yang duplikat adalah error dan file akan ditolak.

Sintaks referensi token berasal dari W3C Design Tokens Format Module — path dengan kurung kurawal seperti {colors.primary}. Referensi harus menunjuk ke nilai primitif (bukan grup), kecuali di dalam bagian components di mana referensi komposit ke token tipografi diizinkan. Nilai warna hanya dalam format hex SRGB pada spesifikasi saat ini. Display P3 dan Oklch — keduanya didukung oleh spesifikasi stabil W3C DTCG 2025.10 — belum didukung oleh DESIGN.md, yang ditandai secara terbuka di repo dengan penanda version: alpha. Penting diketahui jika Anda mengelola token wide-gamut.

Format ini dilengkapi dengan CLI — @google/design.md di npm. npx @google/design.md lint menjalankan tujuh aturan terhadap file yang diparse. Dua yang paling sering saya temui: broken-ref (tingkat keparahan error) menangkap referensi token yang tidak dapat diselesaikan, dan contrast-ratio (peringatan) memeriksa pasangan backgroundColor/textColor komponen terhadap minimum 4,5:1 WCAG AA. Tiga lagi — missing-primary, orphaned-tokens, dan aturan struktural — memunculkan masalah yang sering diperkenalkan sebagian besar tim dalam seminggu setelah mengedit file. CLI juga memiliki diff (regresi tingkat token antar versi) dan export (konfigurasi Tailwind v3, CSS @theme Tailwind v4, atau JSON W3C DTCG).

Mengapa konteks visual persisten penting untuk coding agent

Masalahnya sederhana. Agent yang menghasilkan UI tidak memiliki memori tentang design system Anda kecuali Anda memberinya sesuatu yang terstruktur untuk dibaca. Anda bisa mendeskripsikan palet dalam prompt, mendapatkan tombol, lalu meminta kartu dan melihat logika spasi diatur ulang. Model tidak buruk dalam menulis kode. Ia hanya tidak memiliki jangkar.

design.md adalah jangkar tersebut. Stitch meneruskannya sebagai konteks pada setiap permintaan generasi. Claude Code dan Cursor mengambilnya dengan cara yang sama seperti mereka mengambil CLAUDE.md atau AGENTS.md — sebuah file di root repo yang dibaca agent sebelum menjawab. Framing Google dalam pengumuman open-source adalah bahwa ini memungkinkan agent “mengetahui dengan tepat untuk apa sebuah warna” daripada menebak maksud dari sebuah prompt.

Saya menguji ini pada kedua proyek. Prosedur: letakkan DESIGN.md di root, regenerasikan lima layar yang sama yang sebelumnya bergeser (landing, pricing, sign-up, dashboard, settings), lalu hitung pelanggaran token terhadap front matter. Dengan file tersebut, Claude Code menghasilkan 5/5 layar menggunakan nilai hex primary dan tertiary yang tepat serta rounded.sm yang dideklarasikan. Cursor menghasilkan 4/5 — dashboard terus mengganti rounded.sm (4px) dengan rounded.md (8px) pada kartu, yang tidak secara eksplisit dilarang dalam prosa DESIGN.md. Menambahkan baris “Do’s and Don’ts” — “sudut kartu menggunakan rounded.sm, jangan pernah rounded.md” — memperbaikinya pada regenerasi berikutnya.

Masalah Nyata yang Dipecahkan dalam Generasi UI dengan AI

Konsistensi antar layar dan iterasi

Yang rusak dalam sesi sebelumnya bukan kualitas satu layar. Setiap layar individual terlihat bagus. Layar dua tidak tahu apa yang sudah diputuskan layar satu. Setiap generasi dimulai dari interpretasi yang sedikit berbeda tentang “brand Anda.”

Inilah mode kegagalan yang ditargetkan design.md. Bukan “buat UI lebih indah” — buat UI yang sama di berbagai generasi. Token bersifat normatif. Ketika front matter menyatakan tertiary: “#B8422E”, agent tidak punya ruang untuk menginterpretasikannya sebagai “oranye hangat.” Itu nilai hex tersebut atau salah, dan lint akan mengatakan demikian.

Untuk alur kerja berfrekuensi tinggi — lima, sepuluh, dua puluh layar seminggu dengan seseorang yang memeliharanya — ini lebih penting daripada kualitas output pertama. Satu inkonsistensi per layar dalam skala besar menjadi pekerjaan pembersihan. Token design system untuk coding agent, yang didefinisikan sekali dalam sebuah file, menghilangkan pekerjaan pembersihan itu sebelum dimulai.

Mengapa prosa plus token lebih kuat daripada token saja

Saya hampir mengabaikan bagian ini. Mengapa menulis paragraf “Boston Clay adalah satu-satunya penggerak interaksi” ketika nilai hex sudah ada di YAML?

Karena agent menggunakan prosa untuk membuat keputusan yang tidak dicakup oleh token. Token mengatakan tertiary adalah #B8422E. Prosa mengatakan warna tersebut hanya untuk interaksi — bukan untuk aksen dekoratif, bukan untuk judul. Ketika prompt ambigu (“tambahkan badge notifikasi”), prosa menentukan apakah badge mendapatkan warna interaksi atau netral. Dalam percobaan Cursor di atas, kendala prosa yang hilang adalah alasan tepat mengapa dashboard bergeser.

Logika yang sama berlaku untuk Do’s and Don’ts — guardrail eksplisit seperti “jangan pernah gunakan drop shadow pada kartu” atau “selalu gunakan sentence case untuk label tombol.” Batasan negatif membawa bobot yang tidak bisa diekspresikan oleh token murni. Ini adalah spesifikasi desain untuk agent, bukan file CSS.

Format ini tidak terikat pada Stitch. Spesifikasinya Apache 2.0, CLI-nya ada di npm, ekspor DTCG berarti token mengalir ke alat apa pun yang membaca standar W3C, dan komunitas sudah bergerak. Koleksi awesome-design-md VoltAgent dari file DESIGN.md yang terinspirasi brand melewati 71.000 bintang GitHub dalam beberapa minggu setelah peluncuran, dan topik design-md di GitHub kini mencantumkan alat ekstraksi, ekstensi Chrome, dan registri SKILL.md pendamping dari luar Google sepenuhnya. Adopsi adalah hal yang memberi tahu Anda bahwa sebuah format itu nyata.

Siapa yang Harus Peduli dengan design.md

Saya jujur tentang batasannya, karena design.md bukan solusi universal.

Ini layak digunakan jika:

Anda menghasilkan UI dengan coding agent setidaknya setiap minggu, di lebih dari satu layar
Anda memiliki design system — bahkan yang tipis sekalipun — yang ingin Anda pertahankan di berbagai generasi
Anda bekerja dengan lebih dari satu agent atau alat dan ingin konteks brand yang sama di semua
Anda lelah menempel “ingat palet kami adalah X, Y, Z” ke setiap prompt

Ini tidak layak digunakan jika:

Anda menghasilkan mockup sekali pakai dan membuangnya
“Design system” Anda adalah apa pun yang dihasilkan agent kali ini
Anda berada dalam alur kerja berbasis Figma dengan pipeline DTCG yang matang melalui Style Dictionary atau sejenisnya — design.md lebih ringan dari yang Anda miliki, dan Anda akan menurunkan levelnya
Anda membutuhkan warna wide-gamut (Display P3, Oklch) hari ini — spesifikasi alpha saat ini hanya mendukung SRGB

Untuk tim produk native AI yang menjalankan design.md bersama file alur kerja AI lainnya (CLAUDE.md, AGENTS.md), file ini cocok dengan bersih. Satu file markdown per kepentingan. Tidak ada build step. Tidak ada skema JSON yang harus diperjuangkan. Biaya mencobanya adalah satu file di root repo dan satu perintah lint.

Untuk platform yang membangun surface generasi berbasis agent — termasuk lapisan generasi AI terpadu yang merutekan permintaan di berbagai model dan membutuhkan konteks brand untuk tetap konsisten di setiap panggilan — design.md adalah hal yang paling mendekati kontrak portabel antara brand dan agent dalam ekosistem ini. Menurut pengumuman Google Labs, format ini dibangun khusus agar dapat diekspor dan diimpor di berbagai alat. Portabilitas itulah intinya.

FAQ

Untuk apa design.md digunakan?

Ini adalah file markdown yang memberikan konteks persisten kepada coding agent tentang design system — warna, tipografi, spasi, komponen, ditambah prosa yang menjelaskan cara menerapkannya. Agent membacanya setiap kali menghasilkan UI, sehingga output tetap konsisten di berbagai layar dan sesi tanpa Anda harus menentukan kembali aturan brand di setiap prompt.

Apakah hanya untuk alur kerja Google Stitch?

Tidak. Format ini berasal dari Stitch tetapi Google membuat spesifikasinya open-source di bawah Apache 2.0. Alat AI apa pun yang membaca file konteks — Claude Code, Cursor, GitHub Copilot, Antigravity, Gemini CLI — dapat menggunakannya. CLI mengekspor ke konfigurasi Tailwind, variabel CSS, atau JSON W3C DTCG, sehingga token mengalir ke perkakas non-agent juga.

Mengapa UI yang dihasilkan AI membutuhkan file design-system?

Karena model tidak memiliki memori tentang brand Anda di antara generasi. Tanpa file ai design system yang terstruktur, setiap prompt menginterpretasikan bahasa desain Anda dari awal. Dengan satu file, token bertindak sebagai kendala keras dan prosa mencakup keputusan penilaian. Perbedaannya paling jelas terlihat dalam skala — lima layar yang dihasilkan dengan design.md mempertahankan gaya; lima layar yang dihasilkan tanpanya akan bergeser.

Tim mana yang harus mencobanya terlebih dahulu?

Tim yang sudah menghasilkan UI dengan coding agent setiap minggu. Developer solo dan tim produk kecil yang menjalankan Claude Code atau Cursor mendapatkan manfaat paling cepat — letakkan file tersebut, regenerasikan, lihat konsistensinya. Organisasi besar dengan pipeline Figma + Style Dictionary yang matang harus memperlakukan design.md sebagai pelengkap, bukan pengganti: gunakan untuk memberikan agent subset sistem yang ada yang mudah dicerna.

Kesimpulan

design.md bukanlah format file yang revolusioner. Ini adalah file markdown dengan YAML di bagian atas. Itulah intinya — format yang paling baik dibaca LLM adalah yang paling banyak dilatih, dan itu adalah teks biasa.

Yang sebenarnya dilakukannya adalah menggeser pertanyaan dari “bagaimana saya mendeskripsikan desain saya dalam prompt ini” menjadi “di mana desain saya berada sehingga setiap agent dapat membacanya.” Satu file, satu lokasi, setiap alat yang mengambilnya mendapatkan jawaban yang sama. Satu hal yang tidak perlu ditentukan ulang. Terdengar kecil. Tapi terakumulasi dengan cepat.

Saya sudah menggunakannya di dua proyek selama seminggu. Ini berhasil. Jangka panjang — apakah tim memelihara file-file ini dengan ketekunan yang sama seperti design system nyata, atau apakah mereka akan membusuk seperti README membusuk — itu masih harus diverifikasi. Jalankan di proyek Anda sendiri. Itu akan memberi tahu Anda lebih banyak daripada apa pun yang saya katakan.

Postingan sebelumnya：