DESIGN.md — format file tunggal sistem desain untuk alat coding AI (ringkasan berbahasa Korea)

Format DESIGN.md yang diusulkan Google Labs dalam proyek Stitch terasa menarik, jadi setelah beberapa hari membedah spesifikasinya, saya merasa sayang kalau hanya saya sendiri yang melihatnya lalu selesai. Karena itu, saya merangkumnya dalam bahasa Korea dalam bentuk kurikulum 28 bab. Saya mengerjakannya dengan semangat agar orang yang mempelajari topik yang sama tidak perlu menelusuri spesifikasi berbahasa Inggris dari awal, dan agar orang 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 file Markdown. Nilai seperti warna, tipografi, spacing, radius, dan component token ditempatkan dalam YAML frontmatter dalam bentuk yang bisa dibaca mesin, lalu di bawahnya pada Markdown dituliskan kriteria pengambilan keputusan desain seperti "mengapa warna ini digunakan", "dalam situasi apa gaya tombol ini dipakai", dan "pola apa yang harus dihindari". Dengan kata lain, ini bukan sekadar style guide, melainkan lebih dekat ke "file sumber asli sistem desain" yang akan dirujuk terus-menerus oleh agen coding AI seperti Claude Code, Cursor, dan Codex.

Latar belakang — perubahan yang saya cermati kembali saat merangkum

• Pertanyaan dulu: "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 tinggal hanya di dalam Figma, tetapi masuk ke codebase, ditinjau di 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 mesin, sementara isi utama menjadi lapisan tempat manusia meninggalkan dasar pertimbangannya
• Token adalah jawaban, isi utama adalah alasannya — rapi karena prioritas sudah ditentukan lebih dulu tentang mana yang dipercaya ketika keduanya tidak selaras
• Urutan 8 section bersifat tetap — section seperti colors, typography, spacing, dan components itu sendiri berperan sebagai mental model sistem desain
• lint / diff / export / spec CLI — memeriksa otomatis hal-hal seperti referensi rusak, rasio kontras yang kurang, orphan token, dan pelanggaran urutan section
• Kebijakan interoperabilitas dengan DTCG, Tailwind, dan variabel Figma dijelaskan secara terpisah

Susunan kurikulum (28 bab, 7 modul)

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

Pikiran yang muncul saat merangkum

• Semakin banyak UI dibuat oleh AI, semakin penting pula sistem desain. Masalahnya tampaknya bergeser dari "apakah AI pandai mendesain" menjadi "seberapa jelas tim meninggalkan standar yang harus diikuti AI"
• DESIGN.md adalah upaya praktis untuk menempatkan standar itu di dalam codebase, bukan di Notion atau PDF. Ini juga berarti output desainer menjadi objek review dalam satuan PR
• Saya membagikan ini karena rasanya akan bermanfaat bagi yang sedang membangun sistem desain, atau yang membuat UI dengan alat coding AI dan pernah merasa "mengapa hasilnya selalu berbeda-beda". 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.