---
title: "Design.md Nedir? Markdown Tasarım Dokümanları Yapay Zeka Destekli Ürün Ekiplerini Nasıl Güçlendirir?"
description: "Design.md dosyası nedir, içine ne yazılır, markdown tasarım dokümanları yapay zekanın ürettiği arayüzü nasıl markaya uygun tutar? Açıklamalı tam örnekle."
date: "2026-07-27"
updated: "2026-07-27"
lang: "tr"
tags: ["tasarım sistemleri", "yapay zeka destekli geliştirme", "tasarım dokümantasyonu", "design token"]
seoTitle: "Design.md Nedir? Yapay Zeka için Tasarım Dokümanı — Things"
translationKey: "what-is-design-md-ai-design-documentation"
---

# Design.md Nedir? Markdown Tasarım Dokümanları Yapay Zeka Destekli Ürün Ekiplerini Nasıl Güçlendirir?

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 kapatır: Marka sesinizi, token'larınızı ve kurallarınızı kayıt altına alan, böylece yapay zekanın ürettiği her ekranın ürününüze aitmiş gibi görünmesini sağlayan 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ı ve kendi dosyanızı nasıl yazacağınızı bulacaksınız.

## 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 çözer: 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](https://things.com.tr/blog/tasarim-ekipleri-icin-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 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 buna son verir.

**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.

## 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:

```markdown
# 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, yapay zekanın ürettiği arayüzü markaya nasıl uygun tutar?

Örtük zevki açık kısıtlara dönüştürür ve bu kısıtları her bir üretimde uygular. 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 zaten bilir. Tutarlılık, pull request'i o gün kimin incelediğine bağlı olmaktan çıkar.

Birikimli etki, herhangi bir tekil ekrandan daha önemlidir. Aynı design.md'ye dayanarak üretilen on özellik tek bir ürün gibi görünür. Onsuz üretilen on özellik ise on ayrı ürün gibi. 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: Figma'dan dışa aktarılan design token'lar kod tabanını besler, bileşen kütüphanesi bunları uygular, design.md ise kullanımı yönetir (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](https://things.com.tr/blog/yapay-zeka-ile-tasarimdan-koda). 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](https://things.com.tr/studyo)'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](https://things.com.tr/blog/yapay-zeka-tasarim-is-akisi-kurma) yüklenir.

Biz [bir ajans değil, bir stüdyoyuz](https://things.com.tr/blog/ux-tasarim-ortagi-nasil-secilir) 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](https://things.com.tr/hizmetler) 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 yapay zekanın göz ardı edemeyeceği kısıtlara dönüşür. Mühendislerimiz bir asistana prompt yazdığında asistan zaten müşterinin sesiyle yazar ve müşterinin sisteminin sınırları içinde kalır. Ustalık dokümanda, hız araçlarda. Design. Code. 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'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.

---

## 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 marka ve sistem bilgisini işleyen bir dokümantasyona dönüştürmesine yardımcı olur ve ü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](mailto:hello@things.ist) · [things.com.tr](https://things.com.tr/)