Atlassian’ın DESIGN.md Yayında - Taşınabilir tasarım bağlamını sahada test ederken öğrenilenler

• Yapay zekanın ürettiği arayüzlerin marka kimliği olmadan genelleşip "slop" haline gelmesi sorununu çözmek için geliştirilen taşınabilir bir Markdown formatı; tasarım sisteminin temel öğelerini tek bir dosyada toplayıp prompt’a ekleme yaklaşımı
• DESIGN.md, makine tarafından okunabilen tasarım token’ları ile insan ve ajanların okuyabildiği tasarım gerekçesi (rationale) olmak üzere iki bölümden oluşuyor; sistemin tüm teknik spesifikasyonunu değil niyeti (intent) taşıyor
• Team '26 keynote demosunda Figma Make ile pano oluşturma sürecine uygulandığında renk, aralık, biçim ve tipografi Atlassian sistemine hizalandı; tek seferlik prototiplemede iyi performans gösterdi
• Ancak production kod tabanında, kurum içi MCP sunucusu·skills yaklaşımına kıyasla yaklaşık %92 daha fazla token tüketti, üretim süresi uzadı ve çalıştırmalar arasında token tüketimi yaklaşık 2,7 kat değişerek verimlilik düştü
• Taşınabilirlik ve sadelik gibi özgün güçlü yanları ise platformlar arası taşıma, müşteri temalandırması, yeni ortamlarda prototipleme için değer sunuyor; zengin tasarım sistemi araçlarının yerine geçmekten çok onları tamamlayan bir unsur olarak konumlanıyor

---

Arka plan - AI UI’nin "slop" sorunu

• Yapay zeka UI ürettiğinde sonuçlar; degrade butonlar, büyük harfli başlıklar, genel kart düzenleri, gereksiz hover animasyonları gibi benzer kalıplara kayma eğiliminde oluyor; işlev çalışsa da görsel kimlik eksik kalıyor
• Tasarım topluluğu bu tür çıktıları "slop" diye adlandırıyor; işlevsel ama kasıtlı tasarım kararları içermeyen çıktılar
• Bunun nedeni marka, bileşen ve desenlere dair bağlam eksikliği; yapay zeka eğitim verisinin ortalamasına dönerek varsayılan çıktı üretiyor → "Generic in, generic out"
• Atlassian tasarım sistemi ekibi, AI çağı için bir bağlam motoru kuruyor ve ADS MCP sunucusu ile ayrıntılı AI skills üzerinden ajanlara zengin tasarım bağlamı sağlıyor
  • Bunun sayesinde AI token maliyetlerinin düştüğü ve binlerce ürün geliştiricisinin ürettiği çıktılarda doğruluk ile kalitenin arttığı görüldü

DESIGN.md’ye genel bakış

• Google’ın kendi Stitch tasarım aracı için tasarladığı açık kaynak Markdown formatı; ekibin marka ve UI desenlerini taşıyan taşınabilir bir anlık görüntü
• Dosya prompt’a eklendiğinde üretilen çıktının şirketin kendi ürünü gibi görünmeye başlaması gibi basit bir çalışma mantığı var

• Nedir (What it is)

  • Tasarım sisteminin yalnızca temel öğelerini açıklayan taşınabilir bir Markdown dosyası
  • İlk bölüm, makine tarafından okunabilen tasarım token’larını sıralıyor
  • İkinci bölüm ise insanlar ve ajanlar için renk, aralık, düzen, elevation, bileşenler gibi konularda tasarım gerekçesini açıklıyor

• Ne değildir (What it isn't)

  • Production’da tasarım sisteminin nasıl çalıştığına dair tam teknik spesifikasyon ya da sistemin eksiksiz ayrıntıları değildir
  • Mevcut kod kütüphanelerini, kodlama standartlarını koruyan linter’ları veya Figma’daki ayrıntılı tasarım spesifikasyonlarını içermez
  • Spesifikasyon, bu formatı sistemin tüm ayrıntılarından ziyade niyeti (intent) yakalama olarak tanımlar

Kendi DESIGN.md dosyasını oluşturmak

• Atlassian, MCP sunucusu, yapılandırılmış içerik hattı ve çeşitli ajan skills aracılığıyla tasarım sistemini AI tarafından tüketilebilir hale getirmek için zaten hazırlık yapmış durumdaydı
• Kendi DESIGN.md dosyasını, MCP ve ajan skills’i çalıştıran aynı yapılandırılmış içerik hattından üretti
• Formatı yaygın vibe coding araçlarında test etti ve mevcut kılavuzlarda yer almayan sık hatalar için daha katı yönergeler ekledi

Team '26’daki test

• Bir ay önce Anaheim’da tamamlanan Team '26 keynote demosu uygun bir test örneği olarak kullanıldı
• Keynote’taki demolardan birinde Figma Make, Teamwork Graph kullanarak özel bir pano oluşturdu; hedef, kurum içi MCP sunucularına ve araçlarına bağlı kalmadan tek seferde tasarım dilini hizalamaktı
• DESIGN.md uygulandığında genel "slop" görünümünden; renk, aralık, biçim ve tipografide beklenen değerleri kullanan ve bileşenlerde sistemle hizalı elevation uygulayan, tanınabilir bir Atlassian çıktısına geçildi
• Dosyanın yüksek seviyeli yönergeleri ve spesifikasyonları, Tailwind ve Shadcn gibi yaygın kütüphaneleri özelleştirerek UI’yi sıfırdan üretmek için uygun bulundu

Production kullanımındaki trade-off’lar

• Production kod tabanı; mevcut token ve bileşen kütüphaneleri, sıkı lint kuralları ve tip denetimi bulunan bir ortam olarak, her şeyi sıfırdan kurulan izole ortamlardan oldukça farklı
• Kullanıcı giriş ekranı gibi basit görevlerde DESIGN.md tek tasarım kılavuzu olarak kullanıldığında yaklaşık %92 daha fazla token tüketimi, daha uzun üretim süresi ve çalıştırmalar arasında yaklaşık 2,7 kat token tüketim farkı kaydedildi
  • Ancak bunun kesin bir sonuç olmadığı; modele, prompt’a, tasarım sistemine, ortama ve bağlam kalitesine göre değişebileceği özellikle belirtiliyor

• Sınır 1 - Bağlam isteğe göre değil, tek seferde veriliyor

  • MCP sunucusu, ads_plan gibi tool call’larla yalnızca belirli bileşenler için gereken yönergeleri isteğe bağlı olarak getiriyor
  • Böylece yüzlerce ikon ve geniş semantik tasarım token setleri gibi ağır bölümlerde gereksiz öğelerin yüklenmesi önleniyor
  • DESIGN.md ise her seferinde tamamını yükleyerek başlıyor; bu da en baştan yüksek maliyet, daha yavaş yanıt ve az sayıda turda bağlamın kesilmesi nedeniyle daha düşük doğruluk anlamına gelebiliyor

• Sınır 2 - Dosyayı kısa tutmak bağlam kaybına yol açıyor

  • Tasarım sistemi; binlerce görünüm, Figma dosyası ve frontend bileşeni arasında paylaşılan dilin sıkıştırılmış hali olan karmaşık bir yapı
  • İsteğe bağlı MCP ve skills bunu yaklaşık 2.5 MB’lık yönergelere damıtıyor; DESIGN.md ise tek seferde yüklendiği için çok daha fazla küçültme gerektiriyor
  • Ortaya çıkan dosya 80 KB, yaklaşık 19.800 LLM token’ı büyüklüğünde (frontmatter hariç yaklaşık 10.700) ve topluluktaki örneklere kıyasla büyük sayılıyor
  • Bu boyuta inebilmek için 50’den fazla bileşene ait kullanım yönergelerinin önemli kısmı çıkarıldı, temel yönergeler büyük ölçüde azaltıldı ve az kullanılan bazı tasarım token’ları silindi
  • Bağlam eksikliği nedeniyle production kalitesini hedefleyen ajanların doğruluğunun düştüğü ya da kendi başlarına bağlam toplamaya çalıştıkları; spesifikasyonda olmayan kullanım yönergelerini bulmak için doğrudan bileşen implementasyonlarını okuma eğilimi gösterdikleri gözlemlendi

• Sınır 3 - Spesifikasyon, tasarım sisteminin iç yapısını açığa çıkarıyor

  • DESIGN.md, tasarım sistemini nesir halinde yeniden yazan taşınabilir bir anlık görüntü; amacı sistemi sıfırdan kopyalayıp uygulamak için ilkeler, spesifikasyonlar ve yönergeler sunmak
  • Yerleşik production ortamlarında bu bilgi gereksiz olabiliyor ya da ajanları teknik borç (tech debt) üretmeye yönlendirebiliyor; özellikle bileşenlerde bu daha belirgin
  • Buton stilinin tüm ayrıntılarını (backgroundColor, textColor, borderColor vb.) okuyup yorumlamak yerine mevcut bileşeni import edip kullanmak daha doğru
    • Örnek: import Button from '@atlaskit/button'; ardından <Button appearance="primary" spacing="compact" />
  • Paylaşılan bileşenleri kullanmak bakım açısından kritik; buton tek bir yerde değiştirildiğinde tüm kod tabanına yansıyor ve kod inceleme ile bakım kolaylaşıyor
  • DESIGN.md, kod yönergelerini bilinçli olarak dışarıda bırakıp yalnızca yeniden uygulama spesifikasyonu sunduğu için testlerde mevcut sistemi kullanmaktan çok bileşenleri yeniden üretmeye daha fazla yöneltti
  • MCP sunucusu ve skills, teknik temele dayanan daha iyi bir soyutlama seviyesi sunuyor; yeniden uygulama kılavuzu değil, mevcut sistemi kullanma kılavuzu işlevi görüyor
  • Bu yaklaşım, token harcamadan kodlama standartlarını zorlayan lint kuralları ile birleştiğinde ajanlar için olumlu bir geri besleme döngüsü oluşturuyor

DESIGN.md’nin en faydalı olduğu durumlar

• Yüksek seviyeli sanatsal yön (High-level artistic direction)

  • En basit DESIGN.md, sistemin görsel yönüne ve hissine odaklanır; eğer bu henüz belgelenmemişse yararlı bir çıktı olabilir
  • Ancak frontmatter, kod tabanında zaten bulunan bilgileri tekrar ediyor

• Alışılmadık ortamlarda hızlı prototipleme

  • Blue-sky prototipleme veya yeni araç testlerinde, tüm teknik yığını kurma ya da mevcut bileşen kısıtlarıyla uğraşma zorunluluğu olmadan marka uyumlu UI üretmeyi destekliyor

• Tasarım araçlarıyla birlikte çalışabilirlik (Interoperability)

  • Bazı AI araçları, tasarım diline göre ayarlanmış hazır bileşenleri özelleştirerek UI oluşturuyor; DESIGN.md bu tür araçlara uygun seviyede yönerge sağlıyor

• Uyarlanabilir UI için müşteri temalandırması (Customer theming)

  • Raporlar, grafikler ve panolar gibi dinamik arayüz üretimi gereken ürünlerde müşterilerin kendi markalarını kolayca tanımlamasını sağlayarak AI çıktısının müşteri markasına aitmiş gibi hissettirmesine yardımcı oluyor
  • Yönetici veya marka ekiplerinin iş araçlarına yükleyebileceği bir seçenek olarak düşünülebilir
• Tüm bu kullanım senaryolarının ortak noktası, mevcut tasarım sistemi çıktılarının kullanılamadığı veya pratik olmadığı ortamlarda ajan tarafından üretilen UI olması

Başlangıç ve standarda katkı

• Atlassian, standarda sadece tepki vermek yerine onu şekillendirmek amacıyla kendi DESIGN.md dosyasını atlassian.design/DESIGN.md adresinde yayımladı
• Şirketin dosyası mevcut standarttan bazı yönleriyle ayrılıyor, bileşen render etme için standart dışı özellikler içeriyor ve standart temalandırmayı desteklemediği için ayrı bir dark mode varyantı da sunuluyor
• Geri bildirimlerin GitHub’da paylaşılması isteniyor; bazı öneriler şimdiden spesifikasyona yansımış durumda ve sektör genelinde katılım teşvik ediliyor

Sonuç

• DESIGN.md, tasarım sisteminin anlık görüntüsü olarak faydalı bir taşınabilir format, ancak daha zengin tasarım sistemi araçlarının yerine geçen bir çözüm değil
• Ajan MCP veya skills destekliyorsa daha düşük maliyetle daha iyi sonuç veriyor
• Platformlar arası taşıma, müşteri temalandırması ve blue-sky prototiplemede iyi yapılandırılmış bir DESIGN.md anlamlı iyileştirme sağlayabiliyor
• Tasarım sistemleri yapay zeka tarafından okunabilir hale geldikçe tüm ekosistem bundan fayda görüyor