DESIGN.md Nedir? Yapısı, Örneği ve Yapay Zekâ Araçlarında Kullanımı

DESIGN.md nedir?

DESIGN.md, bir markanın görsel kimliğini yapay zekâ kodlama araçlarına anlatan bir Markdown dosyasıdır. İki katmandan oluşur: dosyanın başında makinenin doğrudan okuyabildiği tasarım token'ları (renkler, yazı tipleri, boşluklar, köşe yarıçapları), altında ise bu değerlerin neden seçildiğini ve nasıl uygulanacağını anlatan düz metin. Biçim Google Stitch ekibi tarafından tanıtıldı ve açık bir spesifikasyon olarak yayımlandı.

Kısacası README.md bir projeyi insanlara anlatıyorsa, DESIGN.md de markayı yapay zekâya anlatır.

DESIGN.md neden gerekli?

Claude, Cursor ya da v0 gibi araçlardan “bir fiyatlandırma sayfası yap” istediğinde, markanı bilmedikleri için genel geçer bir tasarım üretirler: varsayılan mavi butonlar, standart bir yazı tipi, rastgele boşluklar. Her istekte “ana rengimiz şu, başlıklarda şu fontu kullan” diye tarif etmek hem yorucudur hem de tutarsız sonuç verir; bir ekranda doğru olan renk bir sonrakinde kaybolur.

DESIGN.md bu sorunu kalıcı olarak çözer:

• Tek kaynak: Renk, tipografi ve bileşen kuralları bir kez yazılır, her istekte yeniden anlatılmaz.
• Kesin değerler: “Koyu mavi” yerine #1A1C1E; araç tahmin etmez.
• Gerekçe: Metin kısmı, token'ların ne zaman ve neden kullanılacağını anlatır; araç yeni bir bileşen tasarlarken bile markanın mantığını sürdürür.
• Taşınabilirlik: Düz bir Markdown dosyası olduğu için proje dosyalarını okuyabilen her araçla çalışır.

DESIGN.md dosyasının yapısı

Spesifikasyona göre bir DESIGN.md iki katmandan oluşur.

1. YAML ön bilgi: token'lar

Dosyanın en üstünde --- çizgileri arasında duran bu bölüm, bağlayıcı (normatif) değerleri içerir:

Üst düzey anahtarlar name, colors, typography, rounded, spacing ve components'tir. Bileşenler, diğer token'lara referans vererek tanımlanır; örneğin birincil butonun arka planı {colors.tertiary} olabilir.

2. Markdown gövde: gerekçe

Token'ların altındaki bölümler ## başlıklarla yazılır. Hepsi zorunlu değildir, ama kullanılanlar şu sırayla gelmelidir:

Aynı başlığın iki kez kullanılması dosyayı geçersiz kılar; tanınmayan başlıklar ise korunur ve hata sayılmaz.

Örnek bir DESIGN.md

Aşağıdaki kısa örnek, spesifikasyondaki örneğin sadeleştirilmiş hâlidir:

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Mimari minimalizm ve gazete ciddiyeti: yüksek kaliteli mat bir yüzey hissi.

## Colors

- **Primary (#1A1C1E):** Başlıklar ve ana metin için koyu mürekkep.
- **Tertiary (#B8422E):** Etkileşimin tek sürücüsü; yalnızca aksiyonlarda kullanılır.
- **Neutral (#F7F5F2):** Saf beyazdan yumuşak, sıcak zemin.

Bu dosyayı okuyan bir araç, başlıkları koyu mürekkep renginde Public Sans ile yazar, sıcak açık bir zemin kullanır ve aksiyon butonlarını kiremit tonunda üretir.

DESIGN.md, AGENTS.md ve CLAUDE.md arasındaki fark

Bu dosyalar birbirinin yerine geçmez, birbirini tamamlar. Pratikte CLAUDE.md ya da AGENTS.md içinden DESIGN.md'ye bir referans vermek, aracın tasarım kurallarını her oturumda okumasını sağlar. Araç araç adımlar için Claude Code, Cursor ve v0'da DESIGN.md kullanımı rehberine bak.

DESIGN.md nasıl oluşturulur?

Üç yol var:

1. Elle yazmak: Marka kılavuzundaki değerleri spesifikasyondaki yapıya aktarırsın. Kontrol sende olur ama token'ları ve metni tutarlı tutmak zaman alır.
2. Mevcut markandan çıkarmak: MakeMyMD sihirbazında logonu ya da PDF marka kılavuzunu yüklersin; renk paleti ve (PDF'teki gömülü) yazı tipleri çıkarılır, kalan kararları sihirbaz adım adım sorar. Dosyaların tarayıcında işlenir, sunucuya gönderilmez.
3. Hazır bir sistemden başlamak: Tasarım sistemleri kütüphanesindeki bir markanın DESIGN.md'sini “Fork'la & Özelleştir” ile kopyalayıp kendi renklerine ve fontlarına uyarlarsın.

Hangi yolu seçersen seç, sonuç aynı biçimde DESIGN.md, CSS değişkenleri, Tailwind teması ve JSON token olarak dışa aktarılabilir. Bu formatların farkı için Design token nedir? rehberine bakabilirsin.

DESIGN.md nasıl doğrulanır?

Google'ın açık kaynak aracı, dosyayı spesifikasyona göre denetler:

npx @google/design.md lint DESIGN.md

Denetim; çözülemeyen token referanslarını (broken-ref), tanımlı olmayan birincil rengi (missing-primary), WCAG AA eşiğinin (4.5:1) altında kalan metin/arka plan çiftlerini (contrast-ratio) ve bölüm sırası hatalarını bildirir. İki sürümü karşılaştırmak için diff, token'ları Tailwind ya da W3C DTCG biçimine aktarmak için export komutu kullanılır:

npx @google/design.md diff DESIGN.md DESIGN-v2.md
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

Biçim henüz “alpha” sürümünde; spesifikasyon ve araçlar geliştirilmeye devam ediyor.

İyi bir DESIGN.md için 7 ipucu

1. Tek bir vurgu rengi seç. Aksiyon rengini net tanımla; birden çok “ana renk” aracın kararsız kalmasına yol açar.
2. Renklerin rolünü yaz. #B8422E tek başına bir değerdir; “yalnızca birincil aksiyonlarda” demek onu bir kurala çevirir.
3. Tipografiyi ölçek olarak ver. Başlık, gövde ve etiket boyutlarını ayrı token'lar olarak tanımla.
4. Bileşenleri token referansıyla bağla. Buton rengini hex olarak tekrar yazma, {colors.tertiary} gibi referans ver; renk değişince her şey birlikte değişir.
5. Kontrastı kontrol et. Metin/zemin çiftlerinin WCAG AA'yı geçtiğinden emin ol; lint komutu bunu otomatik yapar.
6. Kaçınılacakları da yaz. “Gradyan kullanma”, “köşeleri 8px'ten fazla yuvarlama” gibi yasaklar, aracın markadan sapmasını en çok önleyen kısımdır.
7. Kısa tut. Araçların dikkat penceresi sınırlı; gereksiz tekrardan kaçın, her bölümü birkaç net cümleyle anlat.

Sık sorulan sorular

DESIGN.md dosyası nereye konur?

Projenin kök klasörüne, README.md ile aynı yere. Araçların çoğu kök klasördeki dosyaları okur; CLAUDE.md ya da AGENTS.md içinden DESIGN.md'ye referans vermek okunmasını garanti eder.

DESIGN.md sadece Google Stitch'te mi çalışır?

Hayır. Biçim Stitch ekibi tarafından tanıtıldı ama sıradan bir Markdown dosyası olduğu için Claude Code, Cursor, v0, GitHub Copilot gibi proje dosyalarını okuyabilen her araçla kullanılabilir.

DESIGN.md ile marka kılavuzu arasındaki fark nedir?

Marka kılavuzu insanlar için hazırlanır ve genellikle görsel ağırlıklı bir PDF'tir. DESIGN.md aynı kuralları yapay zekâ araçlarının okuyabileceği kesin değerlere ve kısa gerekçelere dönüştürür. MakeMyMD, PDF marka kılavuzundan DESIGN.md üretmeye yardımcı olur.

DESIGN.md oluşturmak ücretli mi?

Hayır. Dosyayı elle yazabilir ya da MakeMyMD sihirbazıyla ücretsiz oluşturabilirsin.

Türkçe DESIGN.md yazılabilir mi?

Evet. Token adları ve değerleri İngilizce kalıp kodla uyumlu olur, ama gerekçe bölümlerini Türkçe yazabilirsin; yapay zekâ araçları Türkçe açıklamaları da anlar.