design.md untuk AI Coding Agent: Biar Desain Tidak Amburadul

Kenapa AI coding agent sering membuat UI terasa acak?

AI coding agent semakin sering dipakai untuk membuat fitur, memperbaiki bug, dan membangun antarmuka. Namun banyak tim melihat masalah yang sama: hasil UI tidak konsisten. Satu halaman terlihat modern, halaman lain seperti template lama. Spasi berubah-ubah. Warna tombol berbeda. Komponen dibuat ulang padahal sudah ada.

Masalahnya bukan selalu karena AI tidak bisa desain. Sering kali AI tidak diberi konteks desain yang cukup. Developer manusia memahami rasa visual produk setelah melihat banyak halaman, membaca design system, atau berdiskusi dengan designer. AI coding agent tidak otomatis punya pemahaman itu.

File design.md membantu mengisi celah tersebut. File ini menjadi panduan desain ringkas di repository. Isinya menjelaskan gaya visual, layout, warna, tipografi, komponen, copy, dan hal yang harus dihindari. Dengan file ini, agent tidak hanya menebak arti kata “modern”.

Apa itu design.md?

design.md adalah dokumen markdown yang menjelaskan prinsip dan aturan desain proyek. Nama filenya bisa berbeda, tetapi design.md mudah dipahami karena langsung menunjukkan fungsinya. File ini ditujukan untuk manusia dan AI.

Berbeda dari design system lengkap, design.md tidak harus berisi ratusan komponen. Untuk tim kecil, cukup satu dokumen yang menjawab pertanyaan penting: produk harus terasa seperti apa, layout apa yang dipakai, warna apa yang benar, komponen mana yang wajib digunakan, dan pola apa yang dilarang.

Bayangkan design.md sebagai briefing designer yang selalu tersedia di repo. Setiap kali agent diminta membuat dashboard, form, landing page, atau halaman pricing, ia bisa membaca panduan ini lebih dulu.

Hasilnya tidak otomatis sempurna, tetapi peluang UI menjadi konsisten jauh lebih besar.

Kenapa penting untuk AI coding agent?

AI coding agent bekerja berdasarkan konteks. Jika konteksnya hanya “buat halaman dashboard yang modern”, agent akan menebak. Kata modern bisa berarti minimalis, glassmorphism, SaaS gelap, editorial, playful, atau enterprise.

Dengan design.md, instruksi menjadi konkret. Misalnya: gunakan background off-white, kartu putih, border tipis, radius 16px, heading tebal, aksen lime hanya untuk aksi utama, dan hindari gradient ramai. Instruksi seperti ini jauh lebih mudah dieksekusi.

File ini juga mencegah agent membuat sistem baru. Tanpa arahan, agent mungkin menambah warna baru, membuat button variant baru, atau mengubah spacing sembarangan. design.md dapat menulis aturan: gunakan komponen Button yang sudah ada, jangan membuat class warna baru jika token tersedia, dan jangan mengubah layout global tanpa alasan.

Bagi tim yang sering memakai AI untuk coding, design.md adalah investasi kecil dengan dampak besar.

Isi utama design.md yang efektif

Bagian pertama adalah identitas visual. Tulis tiga sampai lima kata sifat yang menggambarkan rasa produk, misalnya bersih, profesional, ramah pemula, cepat, editorial. Jangan terlalu banyak kata karena arahan akan kabur.

Bagian kedua adalah prinsip layout. Jelaskan lebar kontainer, grid, jarak antar section, dan pola responsif. Contoh: kontainer maksimal 1120px, padding desktop 80px, padding mobile 20px, dan hindari lebih dari dua kolom di mobile.

Bagian ketiga adalah warna. Tulis token warna, bukan hanya deskripsi. Contoh: background #f8f9fb, text utama #0b0e13, muted #5b6472, border #e6e8ee, accent #c4f24e. Jelaskan kapan accent boleh dipakai.

Bagian keempat adalah tipografi. Sebutkan font heading dan body jika ada. Jelaskan ukuran, weight, line-height, dan aturan panjang teks.

Bagian kelima adalah komponen. Daftar komponen yang sudah ada: Button, Card, Input, Badge, Navbar, Modal, Table. Sertakan larangan membuat ulang jika komponen tersedia.

Bagian keenam adalah aturan copy. UI bisa rusak oleh teks yang terlalu panjang. Tulis gaya bahasa: jelas, tidak hype, tidak terlalu teknis, dan menggunakan kalimat aktif.

Bagian ketujuh adalah anti-pattern. Ini sangat penting untuk AI. Tulis larangan seperti jangan pakai shadow berat, jangan pakai gradient ungu-biru generik, jangan menambah tiga font baru, dan jangan menaruh teks kecil di gambar ramai.

Contoh struktur sederhana

Struktur awal bisa seperti ini:

### Design Guide

## Visual Direction
Produk harus terasa bersih, premium, ramah pemula, dan praktis. Hindari gaya korporat kaku atau efek futuristik berlebihan.

## Layout
- Max width konten: 1120px.
- Padding section desktop: 72-96px vertikal.
- Padding mobile: 20px horizontal.
- Gunakan satu kolom di mobile.

## Colors
- Background: #f8f9fb.
- Surface: #ffffff.
- Text: #0b0e13.
- Muted: #5b6472.
- Border: #e6e8ee.
- Accent: #c4f24e, hanya untuk aksi utama.

## Components
- Gunakan Button, Card, Input, Badge dari components/ui.
- Jangan membuat variant baru tanpa alasan.

Contoh ini belum lengkap, tetapi sudah cukup untuk mengurangi tebakan agent.

Cara memakai design.md dalam workflow

Langkah pertama, minta agent membaca design.md sebelum bekerja. Instruksinya: “Sebelum mengubah UI, baca design.md dan ikuti aturan desain. Jangan menambah token warna baru kecuali diperlukan.”

Langkah kedua, minta agent menjelaskan rencana singkat. Cukup daftar perubahan: komponen apa yang dipakai, layout apa yang diubah, dan aturan desain mana yang relevan.

Langkah ketiga, minta implementasi kecil. Jangan meminta redesign seluruh aplikasi sekaligus. Mulai dari satu halaman atau satu komponen agar review mudah.

Langkah keempat, lakukan review visual. Jalankan aplikasi, ambil screenshot, dan bandingkan dengan design.md. Cek kontras, spacing, alignment, hierarki, dan konsistensi komponen. Build yang sukses belum tentu UI bagus.

Langkah kelima, perbarui design.md. Jika ada pola baru yang bagus, tambahkan. Jika ada kesalahan berulang, tulis sebagai anti-pattern.

Prompt yang bisa dipakai

Untuk halaman baru:

“Baca design.md terlebih dahulu. Buat halaman settings untuk aplikasi SaaS ini. Gunakan komponen UI yang sudah ada. Jaga layout maksimal 1120px, gunakan card putih, border tipis, dan spacing sesuai panduan. Jangan menambah warna baru.”

Untuk audit UI:

“Baca design.md, lalu audit halaman dashboard ini. Fokus pada spacing, hierarchy, warna, dan konsistensi komponen. Jangan ubah logic bisnis. Beri rencana perbaikan singkat, lalu implementasikan perubahan paling penting.”

Untuk mencegah perubahan berlebihan:

“Ikuti design.md. Hindari redesign total. Perbaiki hanya bagian yang diperlukan agar form lebih jelas dan konsisten. Jangan menambah animasi, gradient, atau library baru.”

Prompt seperti ini membuat agent bekerja dalam pagar yang jelas.

Hubungan dengan design system

Jika tim sudah punya design system lengkap di Figma, design.md bukan pengganti. Ia adalah jembatan antara design system dan kode. Banyak AI coding agent belum tentu memahami seluruh file Figma, tetapi dapat membaca aturan ringkas di repo.

Jika tim belum punya design system, design.md bisa menjadi versi awal. Mulai dari warna, tipografi, spacing, dan komponen inti. Setelah produk berkembang, file ini bisa menjadi dasar design tokens atau dokumentasi komponen yang lebih formal.

Jangan menunggu sempurna. Panduan sederhana yang dipakai konsisten lebih berguna daripada design system ideal yang tidak pernah dibaca agent.

Kesalahan umum

Kesalahan pertama adalah terlalu abstrak. “Buat modern dan elegan” tidak cukup. Tambahkan ukuran, warna, contoh, dan larangan.

Kesalahan kedua adalah terlalu panjang. Jika file puluhan halaman, agent bisa melewatkan detail. Buat ringkas dan mudah dipindai.

Kesalahan ketiga adalah tidak sesuai kode. Jika panduan menyebut komponen Button tetapi repo tidak punya Button, agent akan menebak. Pastikan panduan mencerminkan kode saat ini.

Kesalahan keempat adalah tidak diperbarui. Saat produk berubah, panduan lama bisa menyesatkan.

Kesalahan kelima adalah tidak menyebut anti-pattern. AI sering mengulang gaya umum dari internet. Larangan jelas membantu menghindari hasil generik.

Checklist sebelum meminta AI membuat UI

Cek apakah design.md ada dan terbaru. Pastikan token warna jelas. Pastikan komponen yang harus dipakai disebutkan. Batasi scope tugas. Minta agent tidak mengubah logic bisnis. Siapkan review visual setelah implementasi.

Checklist sederhana ini mencegah banyak revisi. Tanpa checklist, orang sering menyalahkan AI karena hasilnya buruk, padahal instruksinya terlalu bebas.

Kesimpulan

design.md adalah cara praktis memberi AI coding agent arahan desain yang jelas. File ini menjaga konsistensi UI, mengurangi tebakan, mencegah gaya acak, dan membuat review lebih objektif.

Mulailah dengan satu halaman panduan: arah visual, layout, warna, tipografi, komponen, copy, dan anti-pattern. Minta agent membacanya sebelum mengubah UI. Setelah itu, review secara visual dan perbarui panduan ketika ada pelajaran baru. AI coding agent bisa mempercepat frontend, tetapi kualitasnya sangat bergantung pada konteks. design.md memberi konteks itu dengan format sederhana dan mudah dipelihara.

FAQ

Apa itu design.md untuk AI coding agent?

design.md adalah dokumen arahan desain yang memberi konteks visual, layout, komponen, tone, warna, spacing, dan batasan UI kepada AI coding agent sebelum ia menulis kode.

Kenapa AI coding agent sering menghasilkan desain yang berantakan?

Biasanya karena instruksi desain terlalu umum. Jika hanya diminta “buat modern dan clean”, agent akan menebak sendiri hierarchy, spacing, warna, dan komponen. Hasilnya sering tidak konsisten.

Apa isi minimal design.md?

Isi minimalnya adalah tujuan halaman, audiens, style direction, layout utama, prioritas konten, komponen yang boleh dipakai, warna, typography, spacing, responsive behavior, dan contoh hal yang harus dihindari.

Apakah design.md menggantikan designer?

Tidak. design.md membantu mengubah arahan desain menjadi spesifikasi yang bisa dieksekusi agent. Untuk produk penting, designer tetap dibutuhkan untuk taste, sistem, dan review.

Kapan design.md perlu diperbarui?

Perbarui saat brand berubah, komponen baru ditambahkan, responsive behavior berubah, atau agent mulai mengulang kesalahan visual yang sama.

Baca Selanjutnya

Untuk membuat workflow AI coding dan desain lebih rapi, lanjutkan ke:

• Claude Code: cara kerja AI coding agent — memahami cara agent coding bekerja.
• Claude untuk riset dokumen panjang — memakai AI untuk memahami konteks besar.
• Cara menggunakan Claude Artifacts — membuat prototype dan dokumen interaktif.
• Anti AI Slop: desain dan konten AI terasa manusia — menjaga kualitas visual dan copy.
• Intent Engineering vs Prompt Engineering — menyusun tujuan sebelum menulis instruksi.