Yapay zeka kodlama asistanları artık arayüzlerin tamamını inşa edebiliyor. Yapamadıkları şey ise zevkinizi tahmin etmek. Design.md dosyası bu boşluğu daraltır: Marka sesinizi, token'larınızı ve kurallarınızı kayıt altına alan, yapay zekayı ürününüzün diline yönlendiren sade bir markdown dokümanıdır. Bu yazıda böyle bir dosyaya neler yazıldığını, bu formatın neden ortaya çıktığını, kendi dosyanızı nasıl yazacağınızı ve dosyanın sınırının nerede olduğunu bulacaksınız.

Kısa cevap: Design.md, yapay zeka kodlama asistanlarına ürününüzün tasarım kurallarını anlatan bir markdown dosyasıdır. Renkleri, tipografiyi, boşlukları, bileşen kurallarını, ses tonunu ve yapılmaması gerekenleri kısa kurallar hâlinde yazar. Asistan her görevde bu dosyayı okur ve kurallara çoğunlukla uyar. Ama bir kural dosyası yön verir, garanti vermez; garantiyi repo'daki tasarım sisteminin kendisi verir.

Design.md dosyası nedir?

Design.md, reponuzda tutulan ve ürününüzün nasıl görünmesi, nasıl hissettirmesi ve nasıl konuşması gerektiğini hem insanların hem de yapay zeka kodlama asistanlarının okuyabileceği bir dille anlatan bir markdown dosyasıdır. Genellikle renk token'larını, tipografiyi, boşlukları (spacing), bileşen kurallarını, ses tonunu ve açık yap/yapma kurallarını kapsar. Onu, somut çıktılar yerine talimatlara damıtılmış bir tasarım sistemi olarak düşünebilirsiniz.

Geleneksel tasarım dokümantasyonu Figma kütüphanelerinde, Storybook ortamlarında, Notion wiki'lerinde ve PDF marka kılavuzlarında yaşar. Hepsi faydalı. Ama hiçbiri, kodunuzu yazan yapay zeka asistanının görebileceği bir yerde değil. Bir geliştirici "bir ayarlar sayfası ekle" diye prompt yazdığında model, kod tabanını ve talimat dosyalarını görür; Figma değişkenlerinizi ya da marka sunumunuzu değil. Tasarım niyeti modelin okuduğu bir dosyada yer almıyorsa model doğaçlama yapar. Dört farklı mavi tonu ve üç farklı köşe yuvarlaklığı (border radius) olan bir ürünle karşı karşıya kalmanızın sebebi de bu doğaçlamadır.

Design.md bu sorunu, tasarım niyetini repoda birinci sınıf bir öğe hâline getirerek hafifletir: git ile versiyonlanır, pull request'lerde incelenir ve her görevde yapay zekanın bağlamına yüklenir. Tasarım kararları, ekip içinde ağızdan ağıza aktarılan bilgi olmaktan çıkar. Çalıştırılabilir dokümantasyona dönüşür.

Design.md neden yapay zeka kodlama asistanlarıyla birlikte ortaya çıktı?

Çünkü yapay zeka asistanları Figma'yı değil, dosyaları okur. Claude Code, Cursor ve Copilot gibi araçlar eksiksiz özellikler üretebilecek hâle geldikçe ekipler yeni bir talimat dosyası türü keşfetti (CLAUDE.md, AGENTS.md, .cursor/rules); design.md de bu ailenin tasarıma odaklanan kardeşi. Bu konvansiyonun var olmasının nedeni basit: Bağlam, bu araçları yönlendirebileceğiniz tek direksiyondur.

Ekosistemin genelinde örüntü tutarlı:

  • CLAUDE.md, Claude Code'a oturumun başında otomatik olarak yüklenen, proje geneline dair talimatlar verir (build komutları, mimari notlar, kodlama standartları).
  • AGENTS.md, aynı fikir için yeni yeni yerleşen, birden fazla ajanın okuyabildiği, araçlar arası bir konvansiyondur.
  • Cursor kuralları (.cursor/rules), talimatları Cursor içindeki dosya kalıplarına ve davranışlara göre kapsamlandırır.

Üçü de aynı soruya yanıt verir: Makineye, yalnızca koddan çıkaramayacağı şeyleri nasıl anlatırız? Bu soruyu ilk olarak mühendislik ekipleri, test ve mimariye dair konvansiyonlarla yanıtladı. Şimdi sıra tasarım ekiplerinde. Design.md'ye çoğu zaman doğrudan CLAUDE.md içinden, Read design.md before writing any UI code gibi tek bir satırla referans verilir; böylece asistan arayüze her dokunduğunda tasarım sözleşmesi de yüklenir.

Devrede ikinci bir etken daha var: Yapay zeka, bir tasarım kararı ile yayına çıkan kod arasındaki mesafeyi yok denecek kadar kısalttı. Bir model saniyeler içinde prompt'tan bileşene geçebildiğinde darboğaz artık uygulama hızı değildir. Darboğaz, niyetin aktarılmasıdır. Markdown tasarım dokümanları niyeti bir dil modeline aktarmanın en yüksek bant genişliğine sahip yoludur, çünkü dil modelleri (şaşırtıcı olmayan bir şekilde) dil konusunda çok iyidir.

Design.md neden yetmez? Olasılıksal kural dosyası ile repo'daki tasarım sistemi

Design.md son dönemde yapay zekanın markaya uymasının çözümü olarak sıkça anılıyor. Faydalı bir dosya, ama çözüm değil. Nedeni, ajanların bir kural dosyasını nasıl kullandığında.

Kural dosyası olasılıksaldır. Ajan design.md'yi okur ve ona göre davranmaya çalışır; çoğu zaman uyar. Ama yapay zeka ajanları design.md gibi kural dosyalarını %100 uygulamaz. "Ekran başına tek vurgu rengi" yazsanız da, uzun bir görevin ortasında ajan ikinci bir vurgu butonu ekleyebilir. "8px ölçek" yazsanız da, bir yerde 14 piksellik bir boşluk çıkabilir. Dosya ne kadar iyi yazılırsa yazılsın, ajanın davranışı bir olasılık olarak kalır.

Repo'daki tasarım sistemi belirlenimcidir. Sistem gerçek bileşenler, token'lar ve tipler olarak kodda durduğunda ajan onu yorumlamaz; içe aktarır ve kullanır. Button bileşeni yalnızca tanımlı varyantları kabul ediyorsa ajan yeni bir varyant uyduramaz. Renkler token olarak tanımlıysa ve kod incelemesi doğrudan yazılmış renk kodunu kabul etmiyorsa, yanlış renk ekrana çıkamaz. Repo'daki tasarım sistemini ajan okur, uydurmaz.

Kısacası design.md ajana ne yapması gerektiğini anlatır; koddaki sistem ise ajanın neyi yapabileceğini belirler. Bu yüzden design.md'yi tek başına bir çözüm olarak değil, repo'daki tasarım sisteminin yanında duran bir rehber olarak düşünün: Kodda ifade edilemeyen ses tonunu, gerekçeleri ve sanat yönetimini anlatır. Sistemi markadan ayrıştırıp repo'da yaşatmanın yolunu tasarım sisteminizi yapay zekaya nasıl hazırlarsınız yazımızda anlattık.

Design.md dosyasında neler yer almalı?

Projeye yabancı ama yetkin bir tasarımcının, soru sormadan markaya uygun bir ekranı yayına alabilmesi için ihtiyaç duyacağı her şey. Pratikte bu; marka sesi, design token'lar, bileşen kuralları, sanat yönetimi anahtar kelimeleri ve açık yap/yapma listeleri anlamına gelir. Dosyayı net görüşlü ve kısa tutun: Şişirilmiş bir design.md'yi insanlar göz ucuyla okuyup geçer, modelin bağlamında da etkisi sulanır.

Güçlü bir design.md şunları kapsar:

Marka sesi ve tonu. Ürünün nasıl konuştuğu. Cümle uzunluğu, resmiyet düzeyi, mizah politikası, başlıklar ve butonlar için büyük harf kullanım kuralları. "Her yerde yalnızca ilk harf büyük (sentence case). Ünlem işareti yok. Onay mesajları ne kadar heyecanlı olduğumuzu değil, ne olduğunu söyler."

Renk token'ları. Hex değerleri ve kullanım kurallarıyla birlikte adlandırılmış token'lar. Tek başına bir hex kodu modele bir rengin ne olduğunu söyler; kural ise onu ne zaman kullanacağını. "--accent yalnızca birincil aksiyonlar içindir, asla dekorasyon için kullanılmaz."

Tipografi. Font aileleri, tip ölçeği (type scale), ağırlıklar ve eşleştirme kuralları. Yalnızca boyutların listesini değil, satır yüksekliğini ve her kademenin ne zaman kullanılacağını da ekleyin.

Boşluk ve yerleşim. Boşluk ölçeği (4px ya da 8px taban), konteyner genişlikleri, grid davranışı, border-radius değerleri. Modeller gelişigüzel padding değerleri uydurmakla ünlüdür; tanımlanmış bir ölçek bunu azaltır, kodda token olarak tanımlanmış bir ölçek ise önler.

Bileşen kuralları. İsimlendirme kalıpları, varyant yapısı, durum gereksinimleri (hover, focus, disabled, loading, empty, error) ve yeni bir şey inşa etmeden önce hangi temel bileşenlere (primitive) başvurulacağı.

Sanat yönetimi anahtar kelimeleri. Bir estetiği özetleyen sıfatlar: "editoryal, ölçülü, cömert beyaz alan, gradyan yok, glassmorphism yok." Bu kelimeler üretken çıktıyı çoğu ekibin tahmin ettiğinden daha fazla yönlendirir. Modelin varsayılan olarak sıradan SaaS morunu seçmesiyle sizin gerçek estetik anlayışınızı yakalaması arasındaki farkı bu kelimeler yaratır.

Yap/yapma listeleri. Kaldıraç etkisi en yüksek bölüm. Açık yasaklar ("asla saf siyah #000 kullanma", "%8 opaklığın üzerinde gölge (drop shadow) yok", "gövde metnini ortaya hizalama"), markaya aykırı en yaygın hataları her biri tek bir satırla önler.

Design.md nasıl yazılır? 5 adımda

Aşağıdaki adımlar ve şablon iyi bir design.md yazmanıza yardım eder. Unutmayın: Dosya yön verir, garanti vermez; en iyi sonucu, repo'daki bileşenler ve token'larla birlikte kullanıldığında verir.

Design.md yazmak için sıfırdan başlamanız gerekmez. Çoğu ekipte gereken bilgi zaten bir yerlerde duruyor; iş, onu modelin okuyabileceği kısa kurallara çevirmek.

1. Mevcut kaynakları toplayın. Marka kılavuzu, Figma değişkenleri, tasarım sistemi dokümantasyonu, varsa UX yazım kılavuzu. Bu aşamada yeni karar vermeyin; yalnızca elinizde olanı bir araya getirin. Çelişen kaynaklar çıkarsa (iki farklı ana renk gibi) bunları not edin, dosyayı yazarken netleştirirsiniz.

2. Token'ları düz metne dökün. Renk, tipografi ve boşluk değerlerini tablo ya da liste olarak yazın. Her değerin yanına bir kullanım kuralı ekleyin: "--accent yalnızca birincil aksiyonlar için." Kuralı olmayan bir değer, modele neyin var olduğunu söyler ama ne zaman kullanılacağını söylemez.

3. Ses tonunu ve yap/yapma listesini yazın. Ürünün nasıl konuştuğunu birkaç somut kuralla anlatın. Ardından en sık gördüğünüz hataları tek satırlık yasaklara çevirin. Bu liste kısa ama en çok işe yarayan bölüm olur.

4. Dosyayı CLAUDE.md ya da AGENTS.md içinden çağırın. Design.md'yi ayrı bir dosya olarak tutun ve ana talimat dosyanızdan tek bir satırla referans verin. Claude Code'da bu, CLAUDE.md içine @design.md yazmak kadar basittir; diğer araçlarda dosya yolunu belirten bir satır yeterlidir.

5. Bir ekran ürettirin, sapmaları dosyaya geri yazın. Asistandan gerçek bir ekran isteyin ve sonucu tasarımcı gözüyle inceleyin. Yanlış bir renk, fazladan bir gölge ya da tutarsız bir buton metni görürseniz düzeltmeyi yalnızca koda değil, design.md'ye de bir kural olarak yazın. Dosya bu döngüyle olgunlaşır; ilk sürümün eksiksiz olması gerekmez.

Gerçek bir design.md neye benzer?

İşte Things'te müşteri projelerinde kullandığımız yapıda, kısaltılmış ve açıklamalı bir örnek:

# Design.md: Atlas Dashboard

## Voice
- Confident, plain, brief. Sentence case everywhere.
- Buttons are verbs: "Save changes", not "Submit".
- Errors say what happened + what to do next. Never blame the user.

## Color
| Token        | Value     | Use for                          |
|--------------|-----------|----------------------------------|
| --ink        | #16181D   | Primary text. Never pure black.  |
| --paper      | #FAFAF7   | App background. Never pure white.|
| --accent     | #2D5BFF   | Primary actions ONLY.            |
| --danger     | #C93B2E   | Destructive actions + errors.    |
- One accent per view. If two elements compete, demote one.

## Type
- UI: Inter. Editorial surfaces (marketing, empty states): Tiempos.
- Scale: 13 / 15 / 18 / 24 / 32. Body is 15/1.6.
- Weight 600 max in UI. No 700+ except marketing headlines.

## Space & shape
- 8px scale: 8, 16, 24, 32, 48, 64. Nothing in between.
- Radius: 8px inputs/cards, 999px pills. Nothing else.
- Shadows: single layer, ≤8% opacity, or none.

## Components
- Check src/components/ui before creating anything new.
- Every interactive element needs hover, focus-visible,
  disabled, and loading states. No exceptions.
- Empty states get an illustration + one action. Never just text.

## Art direction
Editorial, calm, generous whitespace, quietly confident.
NOT: playful, gradient-heavy, glassmorphic, dense.

## Never
- Pure #000 or #FFF. Center-aligned body text.
- More than one accent-colored button per view.
- Placeholder text as a label substitute.

Bu dosyayı işe yarar kılan şeye dikkat edin: Her değere bir kural eşlik ediyor, tablolar bir envanter gibi değil kısıtlar gibi okunuyor ve "Never" listesi olası hataları doğrudan karşılıyor. Dosyanın tamamı, kodla birlikte yapay zekanın bağlam penceresine rahatça sığıyor.

Design.md şablonu (kopyalayın)

Aşağıdaki boş şablon, yukarıdaki örnekle aynı başlıkları kullanıyor. Kopyalayıp reponuzun köküne design.md adıyla kaydedin ve yorum satırlarının yerine kendi kurallarınızı yazın.

# Design.md: <!-- buraya ürün adı -->

## Voice
<!-- buraya ürünün nasıl konuştuğu: resmiyet düzeyi, cümle uzunluğu, büyük harf kuralı -->
<!-- buraya buton metinleri için kural (ör. "Butonlar fiildir") -->
<!-- buraya hata mesajları için kural -->

## Color
| Token | Value | Use for |
|-------|-------|---------|
| <!-- buraya token adı --> | <!-- buraya hex --> | <!-- buraya ne zaman kullanılır --> |
<!-- buraya renk kullanımına dair genel kural (ör. ekran başına tek vurgu rengi) -->

## Type
<!-- buraya font aileleri ve hangisinin nerede kullanıldığı -->
<!-- buraya tip ölçeği ve gövde metni satır yüksekliği -->
<!-- buraya ağırlık sınırları -->

## Space & shape
<!-- buraya boşluk ölçeği (ör. 4px ya da 8px taban) -->
<!-- buraya border-radius değerleri -->
<!-- buraya gölge kuralı -->

## Components
<!-- buraya yeni bileşen yazmadan önce bakılacak klasör -->
<!-- buraya zorunlu durumlar (hover, focus, disabled, loading, empty, error) -->
<!-- buraya boş durum ekranları için kural -->

## Art direction
<!-- buraya estetiği anlatan 4-6 sıfat -->
<!-- buraya "NOT:" ile istenmeyen estetikler -->

## Never
<!-- buraya en sık yapılan hataları tek satırlık yasaklar olarak yazın -->

Design.md, yapay zekanın ürettiği arayüzü markaya nasıl yaklaştırır?

Örtük zevki açık kurallara dönüştürür ve bu kuralları her üretimde ajanın önüne koyar. Design.md olmadan model, eğitildiği arayüzlerin istatistiksel ortalamasına geri döner: yetkin, sıradan ve hiç şüphesiz size ait olmayan. Design.md ile ise daha tek bir JSX satırı yazılmadan her prompt sizin kurallarınızdan geçer.

İşleyiş basit. Asistan dosyayı yüklediğinde (CLAUDE.md üzerinden otomatik olarak ya da arayüz dosya yollarına kapsamlandırılmış Cursor kurallarıyla), kısıtlarınız sonradan yapılan bir inceleme adımı olmaktan çıkar, doğrudan üretimin bir parçası olur. Bir fiyatlandırma kartı istediğinizde model köşe yuvarlaklığının 8px olduğunu, vurgu renginin yalnızca bir kez kullanıldığını ve CTA'nın bir fiil olduğunu okumuş olur ve çoğu zaman buna uyar. Uymadığı durumları yakalayan ise kod incelemesi ve repo'daki bileşenlerdir.

Birikimli etki, herhangi bir tekil ekrandan daha önemlidir. Aynı design.md'ye dayanarak üretilen on özellik, onsuz üretilen on özellikten çok daha tutarlı görünür. Aynı bileşenleri içe aktaran on özellik ise tek bir ürün gibi görünür. Tasarım geliştiğinde tek bir dosyayı düzenlersiniz ve sonraki tüm üretimler bu değişikliği devralır. Tıpkı bir tasarım sisteminin olması gerektiği gibi, doküman kodun kaynağında durur.

Design.md, tasarım sistemleri ve tasarımdan koda iş akışlarında nereye oturur?

Design.md, bir tasarım sisteminin anlatı katmanıdır: token dosyalarının ve bileşen kütüphanelerinin ifade edemediği "neden ve ne zaman". tokens.json dosyanız neyin var olduğunu tanımlar; design.md'niz ise nasıl kullanılacağını. Yapay zeka asistanlarının ikisine de ihtiyacı vardır ve ikincisine çoğu ekibin fark ettiğinden çok daha fazla ihtiyaç duyarlar.

Olgun bir kurulumda katmanlar düzgünce üst üste oturur: Repo'daki token'lar ve bileşen kütüphanesi neyin mümkün olduğunu belirler, design.md ise kullanımı anlatır (hangi varyant ne zaman kullanılır, boş durum ekranında neler bulunmalı, neler asla yayına çıkmaz). Devir teslim açısından etkisi çok net: Devir teslimin kendisi bu dokümandır. Tasarımcıların mockup'lara not düşmesi ve geliştiricilerin bunları yorumlaması yerine, iki taraf da (ve aralarındaki yapay zeka) aynı sözleşmeyi okur. Anlaşmazlıklar Slack yazışmalarına değil, bir dosyaya açılan pull request'lere dönüşür. Ekibe yeni katılanlar tek bir dokümanı okuyarak işe alışır. Tasarım kalitesinin sessiz katili olan niyet kaybının saklanacak yeri kalmaz.

Things, markdown tasarım dokümanlarını kendi sürecinde nasıl kullanıyor?

Things'te tasarım ve mühendislik paralel ilerler (devir teslim boşluğu yok, kaybolan niyet yok); markdown tasarım dokümanları da bu çizgiyi yapay zeka hızında korumamızı sağlar. Geliştirdiğimiz her üründe sanat yönetimi ve UX metinleri ilk günden itibaren repoda versiyonlanan markdown dosyaları olarak yer alır ve her görevde yapay zeka destekli iş akışlarımıza yüklenir.

Biz bir ajans değil, bir stüdyoyuz ve bu, dokümanların nasıl hazırlandığına da yansıyor. 2018'den bu yana İstanbul ve Elazığ'dan araştırma, UX/UI, tasarım sistemleri ve mühendislik alanlarında 50'den fazla ürünü hayata geçirdik (bu yolda bir Red Dot ödülü de kazandık) ve her projede geçerliliğini koruyan örüntü hep aynı: Araştırma bulguları sanat yönetimi anahtar kelimelerine, marka stratejisi bir ses bölümüne, tasarım sisteminin kuralları da repo'daki bileşenlere ve token'lara dönüşür. Mühendislerimiz bir asistana prompt yazdığında asistan müşterinin sistemini içe aktararak çalışır; design.md ise ona sesi ve gerekçeleri anlatır. Ustalık dokümanda, hız araçlarda. Design. Engineering. Mastery.

Sıkça Sorulan Sorular

Design.md resmî bir standart mı? Hayır. CLAUDE.md ve AGENTS.md gibi o da bir spesifikasyon değil, bir konvansiyondur. İsim, pratiğin kendisinden daha az önemli: repoda duran, yapay zekanın bağlamına yüklenen ve tasarım kısıtlarını içeren bir markdown dosyası. Bazı ekipler bunu CLAUDE.md'ye dahil eder; daha büyük sistemler ise birbirine bağlantılı dosyalara böler.

Design.md'nin CLAUDE.md'den farkı ne? CLAUDE.md proje geneline dair talimatları kapsar: build komutları, mimari, kodlama standartları. Design.md ise görsel ve sözel kimliğe odaklanır. İkisini ayrı tutun ve design.md'ye CLAUDE.md içinden referans verin; böylece dosya, her backend görevini şişirmeden arayüz çalışmalarında yüklenir.

Bir design.md ne uzunlukta olmalı? Beş dakikada okunabilecek kadar kısa; kabaca bir ila üç sayfa. Her satır modelin dikkati için yarışır; bu yüzden envanter niteliğindeki satırları atın, kuralları koruyun. Bir kural hiçbir hatayı önlemiyorsa silin.

Figma'ya ve bir bileşen kütüphanesine hâlâ ihtiyacım var mı? Evet. Design.md onları tamamlar, yerlerini almaz. Figma tasarımın keşfedildiği, bileşen kütüphanesi tasarımın koda döküldüğü, design.md ise tasarım kurallarının yapay zeka araçları ve ekibe yeni katılanlar için okunur hâle geldiği yerdir.

Design.md tek başına yeterli mi? Hayır. Ajanlar kural dosyalarını %100 uygulamaz; dosya yön verir, garanti vermez. Garanti, repo'daki bileşenlerden, token'lardan ve tiplerden gelir. Design.md bu sistemin yanında, kodda ifade edilemeyenleri anlatan bir rehber olarak en çok işe yarar.

Design.md'nin sahibi kim olmalı? Niyeti tasarımcılar yazar; mühendisler ise dosyanın araçlara bağlı kalmasını sağlar. En sağlıklısı, ortak sahiplenilen ve pull request'lerle güncellenen bir design.md'dir; böylece her tasarım kararı incelenebilir bir iz bırakır.

Design.md Türkçe mi yazılmalı, İngilizce mi? Model iki dili de anlar; asıl önemli olan tutarlılık. Ürününüzün dili Türkçeyse ses tonu kuralları ve örnek metinler Türkçe yazılsın, çünkü model örnekleri taklit eder. Token adları, bileşen adları ve kod örnekleri ise kod tabanıyla aynı olsun diye İngilizce kalsın.

Ürünümüz birden çok dilde yayında. Her dil için ayrı design.md mi gerekir? Genellikle hayır. Token'lar, bileşen kuralları ve sanat yönetimi tüm diller için aynıdır. Farklılaşan ses tonu bölümüdür: Hitap biçimi (sen/siz), resmiyet ve buton metinleri dile göre değişiyorsa, Voice bölümünün altına her dil için kısa bir alt başlık eklemek yeterlidir.

Tasarım sisteminizi yapay zeka çağına taşıyın

Ekibiniz yapay zeka asistanlarıyla ürün çıkarıyor ama tasarım niyetiniz hâlâ sunum dosyalarında duruyorsa, tutarlılığı şansa bırakıyorsunuz demektir. Things, ürün ekiplerinin tasarım sistemini repo'da yaşayan bir sisteme dönüştürmesine ve marka bilgisini bunun yanında okunur kılmasına yardımcı olur; ürünü de buna uygun şekilde inşa eder. Araştırma odaklı, işçiliğe tutkun, tasarım ve mühendislik paralel.

Bize ulaşın: hello@things.ist · things.com.tr

Ekibiniz için design.md ve tasarım sistemi kurulumunda destek isterseniz, kısa bir notla hello@things.ist'e yazın; 48 saat içinde dönüyoruz. Dilerseniz iletişim sayfamızdan da ulaşabilirsiniz.