Google Labs'in Stitch projesinde önerdiği DESIGN.md formatı ilgimi çektiği için birkaç gün boyunca spesifikasyonu inceledim; sadece kendime saklamak yazık olur diye bunu Korece olarak, 28 bölümlük bir müfredat biçiminde derledim. Aynı konuyu çalışanların en baştan İngilizce spesifikasyonu didiklemesine gerek kalmasın diye ve benim gibi "tasarım sistemini AI'a nasıl okutabiliriz" sorusunu taşıyanların tek seferde gözden geçirebilmesi için bu çalışmayı hazırladım.
DESIGN.md, tasarım sistemini tek bir Markdown dosyasıyla ifade etmeyi amaçlayan bir formattır. Renk, tipografi, spacing, radius, component token gibi değerler YAML frontmatter içinde makinenin okuyabileceği biçimde yer alır; altındaki Markdown bölümünde ise "neden bu rengi kullanıyoruz", "bu buton stili hangi durumlarda kullanılmalı", "hangi desenlerden kaçınılmalı" gibi tasarım karar ölçütleri yazılır. Yani bu, basit bir stil rehberinden ziyade Claude Code, Cursor, Codex gibi AI kodlama ajanlarının her seferinde başvuracağı "tasarım sisteminin kaynak dosyası"na daha yakındır.
Arka plan — derlerken yeniden fark ettiğim değişim
• Eski soru: "Tasarım sistemini Figma içinde nasıl iyi düzenleriz?"
• Bugünün sorusu: "AI kodlama araçları tasarım sistemimizi nasıl okuyacak?", "Yeni bir sayfa oluştururken AI'ın markamızın renk, aralık ve component kurallarını izlemesi için ne gerekli?"
• Claude Design, Claude Code, Figma MCP gibi akışlarla birlikte tasarım sisteminin yalnızca Figma içinde kalmayıp kod tabanına girmesi, PR'larda incelenmesi ve AI ajanlarının "sürekli bağlamı" haline gelmesi yönündeki değişim
DESIGN.md formatının özü (spesifikasyonu okurken etkileyici bulduğum kısımlar)
• YAML (makine için) + Markdown (insan ve AI için) çift yapısı — token'ları makine parse eder, gövde metni ise insanın karar gerekçelerini bıraktığı katmandır
• Doğru olan token'lardır, gövde metni ise gerekçedir — ikisi çeliştiğinde hangisine güvenileceği önceden tanımlandığı için yapı temiz
• 8 bölümün sırası sabit — colors, typography, spacing, components gibi bölümler tasarım sisteminin mental model'i gibi çalışıyor
• lint / diff / export / spec CLI — bozuk referanslar, yetersiz kontrast, sahipsiz token'lar, bölüm sırası ihlali gibi maddeleri otomatik denetliyor
• DTCG, Tailwind ve Figma değişkenleriyle birlikte çalışabilirlik politikası ayrıca belirtilmiş
Müfredat yapısı (28 bölüm, 7 modül)
• M1 format felsefesi · 3 bölüm — bu formatın çözmeye çalıştığı sorun, çift yapı, token/gövde metni önceliği
• M2 token şeması · 5 bölüm — tüm şema / renk / uzunluk ve birimler / font / token referansları
• M3 bölüm yapısı · 6 bölüm — 8 bölüm sırası ve her bölümün tasarım ilkeleri
• M4 gerçek örnekleri okuma · 3 bölüm — Atmospheric Glass, Paws & Paths, Totality Festival örnekleri
• M5 CLI · 4 bölüm — lint, diff, export, spec
• M6 lint kuralları · 4 bölüm — broken-ref, contrast, orphaned, section-order dahil 8 kural
• M7 genişletilebilirlik · 2 bölüm — bilinmeyen içeriklerin ele alınma politikası, DTCG ve Tailwind ile ilişkisi
• Son özet · 1 bölüm — 27 bölüm özeti + pratiğe taşınabilecek 10 ilke
Derlerken aklımdan geçenler
• AI ne kadar çok UI üretirse tasarım sisteminin o kadar daha önemli hale geleceğini hissettim. Sorun artık "AI tasarımı iyi yapıyor mu" değil, "ekip AI'ın uyması gereken ölçütleri ne kadar açık bırakmış" noktasına kayıyor gibi görünüyor
• DESIGN.md, bu ölçütleri Notion ya da PDF yerine kod tabanının içine koymaya çalışan pratik bir girişim. Aynı zamanda tasarımcının çıktısının PR düzeyinde inceleme konusu olması anlamına da geliyor
• Tasarım sistemi kuranlar ya da AI kodlama araçlarıyla UI üretirken "çıktılar neden her seferinde bu kadar farklı" diye düşünenler için birlikte bakmaya değer olacağını düşündüğümden paylaşıyorum. Yanlış anlayıp derlediğim bir kısım varsa yorumlarda bildirirseniz düzeltirim.
2 yorum
Merak ettiğim bir şey var: DESIGN.md’yi tasarımı üretmek için verilen talimatlar olarak düşünürsek, sonuçta ilk birkaç sayfa ya da tek bir sayfa, bir mood board oluşturmak için kullanılıyor. Sonrasında kod ile talimat.md arasında bir uyumsuzluk ortaya çıkıp sürekli çift yönlü senkronizasyon gerekmiyor mu?
Nihayetinde sonraki tasarımda source of truth olarak kodu kabul edip değişkenler veya isimler gibi şeyleri tutarlı biçimde yeniden kullanmak gerekiyor. DESIGN.md’yi sürekli güncelleyip SSoT olarak yönetmezseniz, sonunda token’ları sürekli hardcode etmek gibi bir duruma düşülmüyor mu diye düşünüyorum. Gerçek kullanımda böyle bir sorun olup olmadığını merak ediyorum.
DESIGN.md => kod yönünü otomatikleştirmek kolay ama tersine, kodda yeni ortaya çıkan kalıpların DESIGN.md'ye taşınması otomatik olmuyor; biri bunu doğrudan takip etmek zorunda kalıyor. Zaman geçtikçe kodun içinde ufak tefek hardcode'lar birikiyor ama bunların belgeye yansımaması da üst üste ekleniyor.
Yine de bu formatın felsefesinin kendisi zaten "tasarım sistemini kod tabanının içinde sürekli geliştirip yaşatmak" yönünde olduğu için, bunun bir eksiden çok amaçlanmış bir işletim biçimine yakın olduğunu düşünüyorum. Notion ya da PDF'de sabitlenip kalan rehberleri PR düzeyinde inceleme konusu hâline getirdiği ölçüde, insanların bunu düzenli olarak elden geçirme sorumluluğunu da beraberinde getiren bir yapı gibi görünüyor. Kendi projemizde uyguladık; uygulamadan öncesine kıyasla ekran tutarlılığı belirgin biçimde arttı ve bu faydayı hissedince manuel inceleme de yük gibi gelmedi. Sonuçta mesele, yapay zekanın uyması gereken ölçütleri ekibin ne kadar net biçimde geride bıraktığı; bu ölçütleri canlı tutacak dokunuşun ise insanlarda kaldığı bir yapı olarak özetlemeye başladım.