DESIGN.md — Format Berkas Tunggal Sistem Desain untuk Alat Coding AI (Ringkasan dalam Bahasa Korea)

Saya merasa format DESIGN.md yang diusulkan Google Labs dalam proyek Stitch cukup menarik, jadi setelah beberapa hari membedah spesifikasinya, rasanya sayang jika hanya saya baca sendiri. Karena itu saya merangkumnya dalam bahasa Korea dalam bentuk kurikulum 28 bab. Saya mengerjakannya dengan harapan orang-orang yang mempelajari topik yang sama tidak perlu langsung mengais spesifikasi berbahasa Inggris dari awal, dan agar mereka yang punya pertanyaan seperti saya, "bagaimana membuat AI membaca sistem desain", bisa meninjaunya sekaligus.

DESIGN.md adalah format yang mencoba merepresentasikan sistem desain dalam satu berkas Markdown. Nilai seperti warna, tipografi, spacing, radius, dan component token ditempatkan dalam YAML frontmatter dalam bentuk yang bisa dibaca mesin, lalu di bagian Markdown bawahnya dituliskan kriteria pengambilan keputusan desain seperti "mengapa warna ini digunakan", "dalam situasi apa gaya tombol ini dipakai", dan "pola seperti apa yang harus dihindari". Dengan kata lain, ini lebih dekat ke "berkas sumber sistem desain" yang akan dirujuk terus-menerus oleh agen coding AI seperti Claude Code, Cursor, dan Codex, bukan sekadar panduan gaya biasa.

Latar belakang — perubahan yang saya cermati lagi saat merangkum

• Pertanyaan lama: "bagaimana merapikan sistem desain dengan baik di Figma"
• Pertanyaan sekarang: "bagaimana membuat alat coding AI membaca sistem desain kita", "apa yang dibutuhkan agar AI mengikuti aturan warna, jarak, dan komponen brand kita saat membuat halaman baru"
• Seiring arus seperti Claude Design, Claude Code, dan Figma MCP, sistem desain tidak lagi hanya tinggal di dalam Figma, tetapi masuk ke codebase, direview dalam PR, dan menjadi "konteks berkelanjutan" bagi agen AI

Inti format DESIGN.md (bagian yang paling mengesankan saat membaca spesifikasi)

• Struktur ganda YAML (untuk mesin) + Markdown (untuk manusia dan AI) — token diparse oleh mesin, sementara isi utama menjadi lapisan tempat manusia meninggalkan dasar pertimbangannya
• Token adalah jawaban, isi utama adalah alasannya — penetapan prioritas sejak awal tentang mana yang harus dipercaya jika keduanya bertentangan terasa rapi
• Urutan 8 section bersifat tetap — section seperti colors, typography, spacing, components sendiri berperan sebagai mental model sistem desain
• CLI untuk lint / diff / export / spec — memeriksa otomatis hal-hal seperti referensi rusak, rasio kontras yang kurang, token yatim, dan pelanggaran urutan section
• Kebijakan interoperabilitas dengan DTCG, Tailwind, dan variabel Figma dinyatakan secara terpisah

Susunan kurikulum (28 bab, 7 modul)

• M1 filosofi format · 3 bab — masalah yang ingin diselesaikan format ini, struktur ganda, prioritas token dan isi utama
• M2 skema token · 5 bab — keseluruhan skema / warna / panjang·satuan / font / referensi token
• M3 struktur section · 6 bab — urutan 8 section dan prinsip desain tiap section
• M4 membaca contoh nyata · 3 bab — kasus Atmospheric Glass, Paws & Paths, Totality Festival
• M5 CLI · 4 bab — lint, diff, export, spec
• M6 aturan lint · 4 bab — 8 aturan seperti broken-ref, contrast, orphaned, section-order
• M7 ekstensibilitas · 2 bab — kebijakan penanganan hal yang tidak diketahui, hubungan dengan DTCG dan Tailwind
• Ringkasan akhir · 1 bab — rangkuman 27 bab + 10 prinsip untuk dibawa ke praktik kerja

Pemikiran yang muncul saat merangkum

• Semakin banyak UI dibuat oleh AI, semakin terasa bahwa sistem desain justru akan makin penting. Masalahnya tampaknya bergeser dari "apakah AI pandai mendesain" menjadi "seberapa jelas tim meninggalkan standar yang harus diikuti AI"
• DESIGN.md adalah upaya praktis untuk menaruh standar itu di dalam codebase, bukan di Notion atau PDF. Ini juga berarti hasil kerja desainer menjadi objek review pada unit PR
• Saya membagikan ini karena rasanya akan berguna bagi mereka yang sedang membangun sistem desain, atau yang pernah merasa "kenapa hasil UI dari alat coding AI selalu berbeda-beda" saat membuat UI dengan alat coding AI. Jika ada bagian yang saya pahami atau rangkum dengan keliru, beri tahu lewat komentar dan akan saya perbaiki.

[m00nlygreat]

Saya penasaran, apakah DESIGN.md bisa dianggap sebagai kumpulan instruksi untuk menghasilkan desain? Pada akhirnya, beberapa halaman pertama... atau satu halaman, digunakan untuk membuat mood board. Setelah itu, bukankah akan muncul ketidaksesuaian antara kode dan instruksi.md, sehingga keduanya harus terus disinkronkan secara dua arah?

Pada akhirnya, untuk desain berikutnya, kode harus dipandang sebagai source of truth dan hal-hal seperti variabel atau nama perlu digunakan ulang secara konsisten. Kalau DESIGN.md tidak terus diperbarui dan dikelola sebagai SSoT, bukankah pada akhirnya token akan terus di-hardcode? Saya penasaran apakah dalam penggunaan nyata masalah seperti ini tidak muncul.

[neostom432]

DESIGN.md => arah kode memang mudah untuk diotomatisasi, tetapi sebaliknya, pola-pola baru yang muncul di kode tidak otomatis naik ke DESIGN.md, jadi harus diperhatikan langsung oleh manusia. Seiring waktu, hardcoding kecil-kecilan menumpuk di kode, tetapi tidak tercermin di dokumentasi, dan hal seperti itu jadi terakumulasi.

Namun, filosofi format ini sendiri memang lebih ke "terus merawat design system di dalam codebase", jadi menurut saya ini bukan kekurangan, melainkan lebih dekat ke cara operasional yang memang disengaja. Karena panduan yang tadinya dibekukan di Notion atau PDF ditarik menjadi objek review per PR, tampaknya ada struktur di mana tanggung jawab untuk meninjau dan merapikannya secara berkala oleh manusia ikut menyertainya. Kami sudah mencoba menerapkannya di proyek kami, dan dibanding sebelum diterapkan, konsistensi tampilan jelas meningkat; setelah manfaatnya terasa, review manual pun tidak lagi terasa membebani. Pada akhirnya, ini adalah soal seberapa jelas tim meninggalkan standar yang harus diikuti AI, dan saya sampai pada kesimpulan bahwa struktur ini memang membuat manusia tetap memegang peran untuk menjaga standar itu tetap hidup.