Masalah besar saat memakai AI untuk bikin UI bukan cuma soal kualitas visual, tetapi soal konsistensi. Hari ini layout terasa modern, besok warna berubah sendiri, lusa button radius-nya beda lagi. Kalau kamu memakai vibe coding untuk UI, file seperti DESIGN.md bisa jadi salah satu alat paling berguna untuk menjaga arah desain tetap waras.
Artikel ini ditulis ulang dalam bahasa Indonesia dari artikel Nick Babich tentang best practices DESIGN.md, lalu saya tarik ke konteks yang lebih relevan untuk workflow vibe coding, Claude Code, Cursor, dan AI-assisted UI generation.
DESIGN.md?DESIGN.md adalah file teks sederhana yang menjelaskan identitas visual produk dan memberi panduan desain yang persisten ke AI tool. Tujuannya bukan sekadar menyimpan warna dan font, tetapi membantu AI memahami bagaimana produk seharusnya terlihat dan terasa.
Dalam praktik vibe coding, file ini sangat berguna karena AI tidak lagi harus “menebak” style dari nol. Ia bisa merujuk ke keputusan desain yang sudah ada: token warna, tipografi, spacing, radius, sampai aturan komponen.
DESIGN.md penting untuk vibe coding?Vibe coding sering cepat di awal, tetapi justru mudah goyah saat sesi sudah panjang. Prompt UI bisa berubah arah, inspirasi desain berganti, dan AI cenderung menghasilkan layout aman yang terasa generik. DESIGN.md membantu mengurangi drift itu.
Kalau dijalankan dengan benar, file ini membuat AI lebih paham:
brand dan rasa visual produk,
peran tiap token, bukan hanya nilainya,
kapan sebuah style boleh dipakai,
bagaimana komponen dibangun dari aturan yang sama.
Singkatnya, DESIGN.md membuat AI tidak asal “desain modern”, tetapi bekerja dari sistem yang memang kamu tentukan.
DESIGN.mdArtikel sumber menjelaskan bahwa DESIGN.md umumnya terdiri dari dua lapisan utama:
YAML frontmatter untuk token seperti warna, tipografi, corner radius, dan spacing.
Markdown body untuk menjelaskan brand, style, warna, tipografi, spacing, shape, dan komponen.
Bagian YAML menyimpan keputusan atomik. Bagian markdown menjelaskan maksud dan aturan pemakaiannya. Kombinasi keduanya penting: token memberi nilai yang presisi, sementara body memberi konteks manusiawi yang bisa dipahami AI.
Ini best practice yang paling penting. Token seperti primary, surface, atau text-muted bukan cuma nama teknis. Token adalah keputusan tentang peran visual dalam sistem.
Karena AI membaca nama token dan membuat asumsi dari situ, penamaan token sebaiknya berbasis fungsi, bukan sekadar penampakan. Hindari nama seperti blue atau gray-1 jika yang sebenarnya kamu maksud adalah warna untuk aksi utama, background surface, atau border halus.
Nama berbasis peran seperti ini biasanya lebih sehat:
primary
surface
surface-dim
border-subtle
text-muted
radius-card
Saat menulis atau merapikan token, ini juga momen bagus untuk audit visual. Sering kali kamu akan menemukan warna duplikat, token yang tidak benar-benar dipakai, atau nilai yang sebenarnya tidak lagi relevan dengan sistem desain produk.
Nilai mentah seperti HEX color belum cukup membantu AI. Yang lebih berguna adalah rantai logika lengkapnya:
raw value → intent → reasoning → constraints
Contohnya, kalau kamu punya token primary, jangan berhenti di “warna utama brand”. Jelaskan juga:
dipakai untuk elemen apa,
kenapa dipakai di sana,
kapan tidak boleh dipakai.
Bagian terakhir ini sangat penting. Constraint membantu AI tahu kapan harus menahan diri. Misalnya: warna utama boleh dipakai untuk primary button dan selected state, tetapi jangan dipakai untuk background luas karena terlalu dominan.
Dalam vibe coding, reasoning seperti ini membantu AI menjaga konsistensi antar layar. Tanpa reasoning, AI bisa tahu warna apa yang dipakai, tetapi tidak tahu kenapa dan sampai batas mana ia boleh mendorongnya.
Bagian komponen seharusnya menjadi lapisan akhir, bukan titik awal. Setelah token dan reasoning jelas, baru kamu jelaskan bagaimana button, input, card, modal, navbar, atau table disusun dari sistem tersebut.
Kesalahan umum adalah menjelaskan komponen hanya di default state. Padahal AI juga perlu tahu bagaimana state lain harus terlihat:
hover,
active,
disabled,
loading,
focus.
Kalau bagian ini tidak dijelaskan, AI akan mengisi kekosongan dengan default masing-masing tool atau framework. Hasilnya: UI terlihat “cukup oke”, tetapi tidak terasa seperti satu sistem yang utuh.
DESIGN.md di workflow vibe codingSupaya file ini benar-benar terasa manfaatnya, gunakan ia sebagai sumber konteks yang dirujuk berulang, bukan file dokumentasi pasif.
Workflow yang masuk akal biasanya seperti ini:
Rapikan token inti dari produk atau design system yang sudah ada.
Tulis reasoning dan batasan untuk warna, typography, spacing, dan shapes.
Tambahkan aturan komponen yang paling sering dipakai.
Referensikan DESIGN.md saat minta AI membuat atau mengubah UI.
Review hasil AI dan perbarui file jika ada drift yang terus berulang.
Dengan pola ini, DESIGN.md menjadi semacam guardrail visual. Ia membantu sesi vibe coding UI tetap konsisten walau dikerjakan lewat banyak prompt dan iterasi.
Yang sebaiknya ditulis:
keputusan visual yang benar-benar penting,
nama token yang berbasis fungsi,
reasoning pemakaian style,
batasan kapan style tidak dipakai,
aturan komponen dan state penting.
Yang sebaiknya dihindari:
deskripsi terlalu abstrak tanpa token konkret,
token berdasarkan penampilan saja,
aturan komponen tanpa konteks tujuan visual,
dokumen terlalu panjang yang isinya berulang.
Tujuan akhirnya sederhana: siapa pun yang membaca file itu, manusia atau AI, langsung paham karakter visual produk dan tahu bagaimana menerapkannya.
Karena masalah UI hasil AI sering bukan di kemampuan membuat elemen, tetapi di kemampuan menjaga arah. AI bisa cepat membuat landing page, dashboard, atau tool UI. Yang lebih sulit adalah memastikan semuanya tetap selaras dengan identitas produk.
DESIGN.md membantu menjembatani dua dunia: sistem desain dan implementasi AI. Itu sebabnya file seperti ini sangat cocok untuk tim atau solo builder yang sering membuat UI lewat vibe coding, baik di tool desain maupun langsung di repo.
DESIGN.md hanya berguna untuk tool desain seperti Google Stitch?Tidak. Konsepnya juga relevan untuk Claude Code, Cursor, dan workflow AI-assisted coding lain yang perlu konteks visual dan aturan desain.
Tidak harus. Kamu bisa mulai dari token inti, beberapa prinsip brand, dan aturan untuk komponen yang paling sering dipakai. Versi kecil yang jelas jauh lebih berguna daripada design system besar yang tidak pernah dirujuk.
Tidak. DESIGN.md membantu mengurangi drift, tetapi review manusia tetap penting untuk memastikan kualitas, konteks produk, dan pengalaman pengguna tetap terjaga.
Artikel ini ditulis ulang dalam bahasa Indonesia dengan merujuk pada artikel sumber di UX Planet: DESIGN.md Best Practices.
Kalau kamu sering bikin UI dengan bantuan AI, DESIGN.md layak dianggap sebagai file inti, bukan tambahan opsional. File ini membantu AI memahami bukan hanya apa yang harus dibuat, tetapi bagaimana produk seharusnya terasa secara visual. Semakin jelas token, reasoning, constraint, dan aturan komponennya, semakin kecil kemungkinan AI menghasilkan UI yang rapi tapi terasa generik.