DESIGN.md nedir? Google'ın tasarım sistemi dosyası, nasıl yazılır, lint ile denetim ve Tailwind'e aktarma

Projene bir DESIGN.md dosyası koyarsın; yapay zekâ kodlama ajanı markanın görsel kimliğini oradan okur: üstte makinece okunan renk, yazı tipi, köşe ve boşluk değerleri, altta bu değerlerin neden seçildiğini anlatan düz yazı. Google Labs'in açık biçimi; depo sayfası Apache-2.0 lisanslı ve ücretsiz, aynı depodaki komut satırı aracı npx @google/design.md lint DESIGN.md ile dosyayı denetler (Node.js 18 veya üstü). Biçim hâlâ "alpha" aşamasında ve değişebilir. Resmî belgeler hangi ajanların bu dosyayı okuduğunu saymıyor.

Ne yapar: Markanın görsel kimliğini ajanlara tek dosyada anlatır
Tür: Dosya biçimi + komut satırı aracı
Gerekenler: Node.js 18 veya üstü (yalnız CLI)
Son sürüm: 0.4.0 (27.07.2026)
Durum: Biçim "alpha", değişebilir
Ücret: Ücretsiz, Apache-2.0

DESIGN.md ne işe yarar?

Yapay zekâ ajanına "bu markaya bir sayfa yap" dediğinde renkleri ve yazı tiplerini her seferinde yeniden tahmin eder. DESIGN.md bu bilgiyi tek dosyada tutar: üstte token'lar (renk, yazı tipi, köşe yuvarlaklığı, boşluk gibi adlandırılmış tasarım değerleri), altta bu değerlerin neden seçildiğini ve nasıl kullanılacağını anlatan markdown bölümleri. Resmî belge, token'ların kesin değer, düz yazının bağlam olduğunu söylüyor.

Tasarım sistemini tek dosyada tarif etmekNe alırsın: DESIGN.md dosyasıAyrı kurulum gerekir Dosyayı kurallara karşı denetlemekNe alırsın: JSON bulgu raporuAyrı kurulum gerekir Token'ları Tailwind'e aktarmakNe alırsın: Standart çıktıya JSON ya da CSSAyrı kurulum gerekir

Kime yarar: Aynı müşteri için birden çok ajan ya da araçla çalışıp her sayfada aynı kimliği isteyen ajanslara ve geliştiricilere. Dosya kendi başına arayüz üretmez; onu okuyan bir ajan gerekir.

Aynı konuya yakın ama farklı bir araç: Frontend Design, Claude Code'a tasarım talimatı veren bir eklenti. DESIGN.md ise markanın değerlerini tarif eden bir dosya biçimi. İkisi birbirinin yerine geçmez.

DESIGN.md dosyası ve denetim aracı nasıl kurulur?

Dosyayı oluşturmak için kurulum gerekmez: projeye DESIGN.md adlı bir markdown dosyası koyarsın. Denetim ve dışa aktarma aracını çalıştırmak için Node.js 18 veya üstü gerekir.

Dosyayı denetle› npx @google/design.md lint DESIGN.md

Sürüm yazmazsan npx en yeni sürümü çeker; belirli sürüm için paket adının sonuna @0.4.0 ekle.

Projeye ekle› npm install @google/design.md

Windows'ta kabuğun @ işaretini yanlış yorumlarsa paket adını tırnağa al: npm install "@google/design.md".

Noktasız takma adla› npx -p @google/design.md designmd lint DESIGN.md

README'ye göre PowerShell'de design.md adı Markdown dosya ilişkisiyle karıştığı için komut çıktı vermeyebilir; designmd takma adı aynı programı çalıştırır.

npm error ENOVERSIONS alırsan README'ye göre npm genel kaydı değil kurumsal bir aynayı sorguluyordur; npm config get registry çıktısı https://registry.npmjs.org/ olmalı.

DESIGN.md nasıl yazılır ve kullanılır?

Dosyanın iki katmanı var: --- çizgileri arasında YAML token'ları, altında ## başlıklı markdown bölümleri. Bölümler isteğe bağlı ama varsa şu sırada olmalı: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Renk için herhangi bir CSS rengi, boyut için px, em ya da rem, başka token'a atıf için {colors.primary} yazılır. README'deki örnekten kısaltılmış iskelet:

DESIGN.md iskeleti

› ---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
rounded:
  sm: 4px
spacing:
  md: 16px
---

## Overview

Sade, gazete ciddiyetinde bir görünüm.

## Colors

- **Primary (#1A1C1E):** Başlıklar ve ana metin.
- **Tertiary (#B8422E):** Yalnız etkileşim rengi.

Ajana dosyayı okutmak"Projedeki DESIGN.md dosyasını oku ve yeni fiyat sayfasını bu tasarım sistemine uygun yap. Dosyada olmayan renk ya da yazı tipi kullanma."Bu bir örnek istemdir; dosyayı hangi ajanın kendiliğinden okuduğu resmî belgede yazmıyor, o yüzden ajana dosyayı açıkça göster.

İş	Komut
Dosyayı denetlemek	`npx @google/design.md lint DESIGN.md`
İki sürümü kıyaslamak	`npx @google/design.md diff DESIGN.md DESIGN-v2.md`
Tailwind v3 ayarına çevirmek	`npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json`
Tailwind v4 CSS temasına çevirmek	`npx @google/design.md export --format css-tailwind DESIGN.md > theme.css`
W3C token dosyasına çevirmek	`npx @google/design.md export --format dtcg DESIGN.md > tokens.json`
Biçim kurallarını ajana vermek için yazdırmak	`npx @google/design.md spec`

Araç JSON çıktı verir. lint hata bulursa çıkış kodu 1 olur; denetim şunlara bakar: kırık token atfı, birincil renk eksikliği, bileşen metin/zemin renk çiftlerinin WCAG AA kontrastı (4.5:1), hiçbir bileşende kullanılmayan renkler ve bölüm sırası.

Dosya ajana talimat gibi okunur. Başkasının markasından çıkarılmış hazır DESIGN.md dosyalarını olduğu gibi kullanma; marka ve telif sorunu çıkabilir. Kendi markan için kendin yaz.

DESIGN.md hangi ajanlarda çalışır?

Komut satırı aracı (lint, diff, export, spec)Var	Node.js 18 veya üstü; npx ile kurmadan çalışır.
Dosyayı okuyan kodlama ajanlarıNet değil	Resmî belge ajan adı saymıyor; "farklı yapay zekâ ajanları ve araçları" arasında kullanılabilen açık bir biçim olarak tarif ediyor.
Tailwind v3 / v4 ve W3C DTCGVar	`export` komutu bu üç biçime çıktı veriyor.

"Belgede yok" çalışmaz demek değildir. Kullandığın ajana dosyayı açıkça okut.

Denetim aracı neyi okur, neye yazar?

Okur

Komuta verdiğin DESIGN.md dosyası (ya da standart girdi). diff iki dosya okur.

Yazar

Standart çıktıya JSON ya da CSS basar; dosyaya yazmak için kabuk yönlendirmesini (>) sen eklersin.

Kurulum betiği

npm kaydında 0.4.0 sürümünde kurulum öncesi ya da sonrası çalışan betik görünmüyor (yalnız yapım betikleri).

Kayıtlı güvenlik uyarısı

15.10.2026 itibarıyla GitHub uyarı listesinde (depo ve genel) ve npm için OSV'de kayıtlı uyarı görünmüyor. Bu güvenli olduğu anlamına gelmez: README projenin Google güvenlik ödül programı kapsamında olmadığını yazıyor ve depoda SECURITY.md yok.

DESIGN.md ücretsiz mi?

Evet. Biçim ve komut satırı aracı Google Labs'in açık depo sayfasında Apache-2.0 lisansıyla yayımlanıyor; belgelerde ücretli plan, hesap ya da anahtar yok. "Yazılım ücretsiz" demek yazdığın dosyayı kullanan ajanın ya da modelin ücretsiz olduğu anlamına gelmez; onların ücreti ayrıdır.

Yapabilirsin

Apache-2.0 koşullarıyla kullanmak, değiştirmek ve dağıtmak (ticari kullanım dahil)

Yasak

Lisans metnini ve bildirimleri kopyalardan çıkarmak

Kaynak: depo lisansı ve README. Bu bir hukuki görüş değildir.

Sık sorunlar ve çözümleri

Ne oluyor	Ne yapmalı
PowerShell'de komut çıktı vermiyor ya da DESIGN.md metin düzenleyicide açılıyor	`npx -p @google/design.md designmd lint DESIGN.md` komutunu kullan.
`npm error ENOVERSIONS`	npm kayıt adresini kontrol et (`npm config get registry`); kurumsal ayna eşitlenmemiş olabilir.
Kullanıcıların bildirdiği `spec` komutu 0.3.0 sürümünde hata veriyor (#153)	GitHub'da açık bildirim; 0.4.0'da düzelip düzelmediği belirsiz; sürüm notlarını kontrol et.
Kullanıcıların bildirdiği `dtcg` dışa aktarımı yazı tipi özelliklerini eksik veriyor (#172)	GitHub'da açık bildirim; çıktıyı başka bir araca vermeden gözle kontrol et.

Sık sorulan sorular

DESIGN.md nedir?

Bir markanın renk, yazı tipi, köşe ve boşluk değerlerini ve bunların nedenini kodlama ajanlarına anlatan açık bir dosya biçimi. Üstte YAML token'ları, altında markdown açıklamaları bulunur.

DESIGN.md ücretsiz mi?

Evet. Google Labs'in açık depo sayfası biçimi ve komut satırı aracını Apache-2.0 lisansıyla yayımlıyor; belgelerde ücretli plan yok. Dosyayı okuyan ajanın ücreti ayrıdır.

DESIGN.md nasıl denetlenir?

Node.js 18 veya üstü varken npx @google/design.md lint DESIGN.md çalıştırılır. Araç kırık token atfı, WCAG kontrastı ve bölüm sırası gibi bulguları JSON olarak verir.

DESIGN.md Tailwind ile kullanılır mı?

README export komutunun Tailwind v3 JSON ayarı, Tailwind v4 CSS teması ve W3C DTCG tokens.json çıktısı verdiğini yazıyor.

Hangi yapay zekâ ajanları DESIGN.md okuyor?

Resmî belgeler ajan adı saymıyor. Biçim farklı ajanlar ve araçlar arasında kullanılsın diye tasarlanmış; kullandığın ajana dosyayı açıkça okutman en güvenlisi.

DESIGN.md biçimi kararlı mı?

Hayır. README biçimin "alpha" sürümünde olduğunu ve şemanın, aracın değişebileceğini yazıyor. Kritik bir iş akışına bağlamadan önce sürümü sabitle (örneğin @0.4.0).

İlgili rehberler

Stitch

Frontend Design Genjutsu

Hallmark

Impeccable

shadcn/ui skill

Kaynaklar

Resmî kaynaklarda net olmayanlar: Hangi kodlama ajanlarının DESIGN.md'yi kendiliğinden okuduğu · Google Stitch ile dosya alışverişinin ayrıntıları · bildirilmiş hataların 0.4.0'da düzelip düzelmediği · Türkçe belge. Her biri ilgili bölümde ne yapabileceğinle birlikte yazılı.