Design System Nedir? Design Token'lar (DTCG 2025.10), Component Library ve Dokümantasyon

Sürüm notu: Bu yazıdaki token dosyaları DTCG (Design Tokens Community Group; W3C (web standartlarını yayımlayan kuruluş) bünyesinde token formatını belirleyen topluluk grubu) 2025.10 formatındadır ve Terrazzo 2.10 ile derlenmiştir; Tailwind çıktısı Tailwind CSS 4.3 ile, örnek sayfalar Playwright 1.65 ile Chromium 158'de denenmiştir; script'ler Node.js 24 ile çalıştırılmıştır.

Önce Tahmin Et

Sitedeki serilerin ortak örnek uygulaması Bookstore (bir online kitapçı) için bookstore-web'in tokens.css dosyası dokuz yazı boyunca büyüdü: 03'te type scale, 04'te palet ve semantic renkler, 05'te spacing, 07'de focus ring ve hareket, 09'da yükseklik. Dosyanın içinde artık şöyle bloklar yan yana duruyor:

/* 04: semantic renkler, açık tema */
:root {
  color-scheme: light;
  --color-bg: #ffffff;
  --color-surface: var(--gray-50);
  --color-action: var(--blue-600);
  /* ... */
}

/* 07: focus ring ve hareket */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-focus: var(--blue-300);
  }
}

Dark tema için renkler üç ayrı blokta, üç ayrı yazıda eklendi. Tasarımcı aynı renkleri Figma'da ayrıca tutuyor, Tailwind kullanan admin paneli kendi @theme'inde bir kopyasını daha. Kaç token var ve kaçı yalnız başka bir token'ın takma adı? Yeni bir renk eklemek isteyen biri onu kaç yere yazmalı? "Mavi"yi değiştirmek hangi ekranları etkiler, hangilerini etkilemez? Bu dosyayı elle yazmayı bırakıp bir kaynaktan üretsek, ürettiğimiz CSS'in eskisinin aynısı olduğunu nasıl kanıtlarız?

Önce ölçelim

Bu yazıda dosyayı DTCG formatında JSON token dosyalarına taşıdık ve CSS'i oradan ürettik. Script önce token dosyalarını katman katman sayıyor; sonra hem elle yazılmış hem üretilmiş CSS'i Chromium'a yükleyip her custom property'nin tarayıcıda çözüldüğü değeri açık tema, koyu tema ve azaltılmış hareket için karşılaştırıyor; en sonda semantic renk çiftlerinin kontrastını ve aynı token'ın düz CSS ve Tailwind üzerinden aynı rengi verip vermediğini ölçüyor:

npm run tokens
node scripts/10-tokens.mjs

primitive        79 tokens, 0 aliases (color 55, dimension 14, fontFamily 1, fontWeight 3, number 3, duration 2, cubicBezier 1)
semantic         21 tokens, 15 aliases (color 18, shadow 1, border 1, dimension 1)
component         8 tokens, 6 aliases (color 4, dimension 3, shadow 1)
dark theme       19 tokens, 18 aliases (color 18, shadow 1)
reduced motion    2 tokens, 0 aliases (duration 2)
light: 100 of 101 identical; not in the generated file: --measure
dark: 100 of 101 identical; not in the generated file: --measure
reduced motion: 100 of 101 identical; not in the generated file: --measure
contrast light: 9 of 9 pairs at least 4.5:1, lowest text-muted/surface 4.63:1
contrast dark: 9 of 9 pairs at least 4.5:1, lowest text-muted/surface-raised 4.77:1
button background light: CSS oklch(0.54 0.178 264), Tailwind oklch(0.54 0.178 264), same: true
button background dark: CSS oklch(0.7899 0.1057 264), Tailwind oklch(0.7899 0.1057 264), same: true

Tahminlerin cevabı: 108 token var ve bunların 79'u ham değer, geri kalanların çoğu başka bir token'a verilen bir isim. Dark tema 19 token'ı değiştiriyor ve 18'i yalnız bir alias'ın yönünü çeviriyor. Elle yazılmış 101 custom property'nin 100'ü üretilen dosyada tarayıcıya birebir aynı değeri veriyor; biri, --measure, bilinçli olarak dışarıda kaldı. Bu yazının geri kalanı bu satırların nasıl ortaya çıktığı.

Design System Nedir, Ne Zaman Gerekir?

Design system dört parçadan oluşuyor: token'lar (renk, ölçü, süre gibi kararların adlandırılmış hâli), component'ler (bu token'larla yapılmış button, input, card), kullanım kuralları (hangi component ne zaman, hangi state'lerle kullanılır) ve yönetişim (bir değişikliği kimin önerdiği, kimin onayladığı, nasıl sürümlendiği). Yakın kavramlarla farkı bu parçalarda. Bir UI kit tasarım aracındaki hazır parçalar kütüphanesi; kod ve kural taşımaz. Bir style guide renkleri, fontları ve logonun kullanımını anlatan bir doküman; çoğu zaman canlı kodla bağlantısı yok. Design system ikisini kodla ve bir süreçle birleştiriyor.

Her proje design system'e ihtiyaç duymuyor. Tek bir ekip, tek bir ürün ve bir tasarımcı varsa iyi düzenlenmiş bir token dosyası ve birkaç ortak component yeterli; yönetişim bir toplantı notundan ibaret olabilir. Aynı markayı taşıyan ikinci bir ürün (Bookstore için mağaza sitesi ve kurumsal portal), ikinci bir ekip ya da ikinci bir platform (web ve mobil uygulama) eklendiğinde ise "aynı mavi" sorusu her sprint tekrar sorulmaya başlıyor; design system'in maliyeti bu noktada kendini ödüyor.

İki yol var. Hazır bir sistemi benimsemek, örneğin Material 3: token'lar, state'leri ve erişilebilirliği düşünülmüş component'ler ve dokümantasyon hazır geliyor, Angular Material ile kodu da var; bedeli, markanın görünüşünün o sistemin kurallarına bağlanması ve özelleştirmenin sistemin izin verdiği yerlerle sınırlı kalması. Kendi sistemini kurmak tam kontrol veriyor, ama her component'in state'lerini, erişilebilirliğini ve dokümantasyonunu ekip kendisi yazıyor ve bakımını yapıyor. Bookstore için seçimimiz ikisinin arası: token'lar kendi sistemimiz, karmaşık component'ler (tarih seçici, dialog) için hazır bir kütüphane ve onu token'larımıza bağlayan bir tema. Angular Material'ın tema sistemi buna izin veriyor: Angular Material dokümantasyonuna göre component'ler --mat-sys-surface, --mat-sys-on-surface gibi system token'larını CSS değişkeni olarak okuyor ve mat.theme-overrides mixin'i bunları yeniden tanımlıyor. Bu yazıda bir Angular projesi kurmadık; eşleme, aşağıda Tailwind için yaptığımızın aynısı.

Token Katmanları: Primitive, Semantic, Component

04. yazıda paleti kurarken iki katmanı farkında olmadan ayırmıştık: --blue-600 bir renk, --color-action o rengin "ne için" kullanıldığı. Design system'lerde bu ayrım üç katmana çıkıyor:

Primitive token'lar ham değerler: paletin 55 rengi, spacing ölçeği, font ailesi, süreler. Anlamları yok; palette.blue.600 hiçbir şey söylemiyor, yalnız bir renk. Semantic token'lar kararlar: color.action "birincil işlemin rengi", color.text-muted "ikincil metin". Tema değiştiğinde değişen katman bu. Component token'lar tek bir component'in kararı: button.primary.bg bugün color.action'a eşit, ama marka ekibi bir gün butonları farklı bir tona çekmek isterse yalnız bu satır değişiyor ve link'ler etkilenmiyor.

Kural, kodun yalnız en alttaki katmanı tanıması. Bu yazının token sayfasındaki buton yalnız component token'larını okuyor:

/* buton yalnız kendi component token'larını tanır */
.btn { min-height: var(--button-min-height); padding: 0 var(--space-4); border: 0; border-radius: var(--button-radius); background: var(--button-primary-bg); color: var(--button-primary-text); font: inherit; font-weight: var(--weight-semibold); }
.btn:hover, .btn.is-hover { background: var(--button-primary-bg-hover); }

Üç katman her yerde gerekmiyor. Component token'ları ancak bir component'in kararı semantic katmandan gerçekten ayrışabiliyorsa değer katıyor; her component'in her property'si için bir token açmak, 108 token'ı 1000'e çıkarıp kimsenin okuyamadığı bir sözlük üretiyor. Bookstore'da yalnız button ve card için 8 component token'ı var.

DTCG 2025.10 Formatı

Token'ları hangi formatta tutacağımız sorusunun artık bir standardı var. W3C bünyesindeki Design Tokens Community Group, formatın ilk kararlı sürümünü 28 Ekim 2025'te yayımladı. 2025.10 raporu üç module'den oluşuyor: Format (token, group, alias ve tipler), Color (renk uzayları) ve Resolver (tema gibi bağlamlar). W3C standardı değil, bir topluluk grubu raporu; ama Terrazzo ve Style Dictionary gibi token araçları bu formatı okuyor.

Bir token, $value taşıyan bir JSON object'i; $type değerin tipini söylüyor ve group seviyesinde verilirse içindeki token'lara geçiyor. Bookstore'un palet dosyasından bir parça:

{
  "palette": {
    "blue": {
      "$type": "color",
      "50": {
        "$value": {
          "colorSpace": "oklch",
          "components": [0.97, 0.014, 264],
          "hex": "#f0f5ff"
        }
      },

Color module rengi bir string olarak değil, renk uzayı ve bileşenleriyle tanımlıyor; OKLCH (renkleri algılanan açıklığa göre tanımlayan renk uzayı) desteklenen uzaylardan biri, hex ise eski araçlar için isteğe bağlı bir yedek. 04. yazıda OKLCH ile ürettiğimiz palet bu sayede kayıpsız taşınıyor. Alias, süslü parantez içinde başka bir token'ın yolu:

"action": {
  "$type": "color",
  "$value": "{palette.blue.600}"
},

Taşıma sırasında formatın bir sınırına takıldık. DTCG'nin dimension tipi yalnız px ve rem birimlerini kabul ediyor; 03. yazıdaki satır uzunluğu token'ı --measure: 52ch ise ch biriminde, çünkü satır uzunluğu karakter sayısıyla ilgili. Spec'e göre rem'in de mobil platformlarda karşılığı her zaman yok ve araçlar gerektiğinde px'e çevirebiliyor; ch ise hiç tanımlı değil. Seçenekler: değeri rem'e çevirmek (font değişince anlamını kaybeder) ya da token sistemine almayıp CSS'te bırakmak. --measure'ı CSS'te bıraktık; ölçümdeki "not in the generated file: --measure" satırı bu kararın kaydı.

Resolver ile Light, Dark ve Reduced Motion

Dark tema, aynı token'ların başka bir bağlamdaki değeri. 2025.10'daki Resolver module bunu tanımlamanın standart yolu: set'ler her bağlamda geçerli token dosyalarını, modifier'lar ise bağlama göre üstüne eklenen dosyaları listeliyor; resolutionOrder hangisinin hangisini ezeceğini belirliyor:

{
  "$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
  "name": "Bookstore",
  "version": "2025.10",
  "sets": {
    "base": {
      "sources": [
        { "$ref": "primitive.tokens.json" },
        { "$ref": "semantic.tokens.json" },
        { "$ref": "component.tokens.json" }
      ]
    }
  },
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [],
        "dark": [{ "$ref": "theme-dark.tokens.json" }]
      },
      "default": "light"
    },
    "motion": {
      "contexts": {
        "default": [],
        "reduced": [{ "$ref": "motion-reduced.tokens.json" }]
      },
      "default": "default"
    }
  },
  "resolutionOrder": [
    { "$ref": "#/sets/base" },
    { "$ref": "#/modifiers/theme" },
    { "$ref": "#/modifiers/motion" }
  ]
}

theme-dark.tokens.json yalnız değişen 19 semantic token'ı içeriyor ve 18'i alias: color.action dark'ta {palette.blue.300}'e dönüyor. Primitive ve component dosyalarına dokunulmuyor; figürdeki "dark temada yalnız semantic katman değişir" cümlesi bu dosyanın ölçüsü. İki modifier birbirinden bağımsız (spec'in deyimiyle orthogonal): biri renklere, diğeri sürelere dokunuyor, böylece dört kombinasyon için dört dosya yazmak gerekmiyor. Bir sonraki adımda yüksek kontrast teması gerekirse theme'e yeni bir context eklemek yetecek.

Tek Kaynaktan CSS ve Tailwind Üretmek

JSON'dan CSS üreten iki yaygın araç var: Style Dictionary ve Terrazzo. İkisi de DTCG'nin $value/$type syntax'ını okuyor; Terrazzo'nun 2.0 sürüm notu 2025.10 spec'ini resolver'larla birlikte tam desteklediğini söylüyor, bu yüzden burada Terrazzo 2.10 kullandık. Configuration, resolver'ın hangi kombinasyonunun hangi CSS seçicisine yazılacağını tanımlıyor:

// token id -> CSS değişken adı: palette.blue.600 -> --blue-600, color.text-muted -> --color-text-muted
const variableName = (token) => `--${token.id.replace(/^palette\./, '').replaceAll('.', '-')}`;
// boş shadow listesi "gölge yok" demek
const noShadow = (token) => (token.$type === 'shadow' && token.$value.length === 0 ? 'none' : undefined);

export default defineConfig({
  tokens: ['./tokens/bookstore.resolver.json'],
  outDir: './web/styles/generated/',
  plugins: [
    css({
      filename: 'tokens.css',
      variableName,
      permutations: [
        {
          input: { theme: 'light', motion: 'default' },
          prepare: (css) => `:root {\n  color-scheme: light;\n  ${css}\n}`,
        },
        {
          input: { theme: 'dark', motion: 'default' },
          include: ['color.*', 'shadow.*'],
          transform: noShadow,
          prepare: (css) => `@media (prefers-color-scheme: dark) {\n  :root:not([data-theme="light"]) {\n    color-scheme: dark;\n    ${css}\n  }\n}`,
        },

Değişken adlarını eski dosyayla aynı tuttuk; böylece 03–09 arasındaki sayfalar hiçbir değişiklik olmadan üretilen dosyayla çalışabiliyor. Dark bloğuna yalnız renk ve shadow token'larını aldık: component token'ları var(--color-action) gibi referanslar olduğu için tarayıcı onları zaten dark değerle çözüyor.

Aynı configuration'a Tailwind plugin'ini ekleyince kaynak aynı kalıp bir çıktı daha geliyor. Admin paneli bg-action, text-muted, p-4 gibi utility'leri bu token'lardan alıyor. npm run tokens iki adımı birden çalıştırıyor; çıktısı:

plugin:@terrazzo/plugin-tailwind: space.1 matched 0 tokens
plugin:@terrazzo/plugin-tailwind: space.2 matched 0 tokens
plugin:@terrazzo/plugin-tailwind: space.3 matched 0 tokens
plugin:@terrazzo/plugin-tailwind: space.4 matched 0 tokens
plugin:@terrazzo/plugin-tailwind: space.6 matched 0 tokens
plugin:@terrazzo/plugin-tailwind: space.8 matched 0 tokens
plugin:@terrazzo/plugin-tailwind: space.12 matched 0 tokens
plugin:@terrazzo/plugin-tailwind: radius.md matched 0 tokens
plugin:@terrazzo/plugin-tailwind: font.sans matched 0 tokens
✔  108 tokens built 33ms
≈ tailwindcss v4.3.5

Done in 37ms

Uyarılar dark bloğuyla ilgili: üretilen tailwind-theme.css'e bakınca dark bloğunda yalnız renklerin olduğu görülüyor, spacing, radius ve font için dark'ta yazılacak bir değer yok. Asıl sürpriz başka yerdeydi. Plugin'in örnek template'indeki gibi en üst seviyede bir @variant dark { … } yazınca Tailwind CLI bunu seçicisi olmayan bir @media (prefers-color-scheme: dark) { --color-bg: … } bloğuna çevirdi; seçicisiz declaration'lar geçersiz CSS ve tarayıcı onları sessizce yok sayıyor. Template'te bloğu @layer theme { :root { @variant dark { … } } } içine alınca doğru kural üretildi. Ölçümün son iki satırı bunun sağlamasını yapıyor: token sayfasındaki düz CSS buton ile Tailwind utility'leriyle çizilmiş buton açık ve koyu temada aynı arka planı alıyor.

Derlenmiş Tailwind dosyasında bir şey daha dikkat çekiyor: Tailwind'in varsayılan teması da --text-sm, --leading-tight ve --ease-out adlarını, bizimkinden farklı değerlerle tanımlıyor (örneğin --text-sm: 0.875rem, bizde 0.8125rem). Tailwind kendi değerlerini @layer theme içine koyduğu ve bizim tokens.css'imiz katmansız olduğu için bizimkiler kazanıyor; ama bu, sayfaya hangi dosyanın hangi sırayla yüklendiğine bağlı kırılgan bir denge. Çakışan namespace'leri @theme içinde sıfırlamak ya da kendi token'larına bir önek vermek daha güvenli; Tailwind tarafındaki ayrıntılar Tailwind CSS serisinin theme ve design token yazısında.

Üretilen CSS Eskisinin Aynısı mı?

Bir token sistemine geçişin en riskli anı, elle yazılmış dosyanın yerine üretilenin konduğu an. Metin karşılaştırması işe yaramıyor: Terrazzo oklch(0.54 0.178 264) yerine oklch(54% 0.178 264) yazıyor, beyazı rgb(100% 100% 100%) olarak çıkarıyor. Script bu yüzden metni değil sonucu karşılaştırıyor: her custom property'yi tipine uygun bir CSS property'sine uyguluyor (renkler color, ölçüler width, süreler transition-duration), renkleri canvas üzerinden sRGB byte'larına çeviriyor ve iki dosyanın tarayıcıda aynı sonucu verip vermediğine bakıyor.

Sonuç üç bağlamda da 101'de 100. Ara adımda bir fark daha çıkmıştı: koyu temada --focus-ring, eski dosyada oklch(0.79 0.106 264), yenisinde oklch(0.7899 0.1057 264). Sebep, Terrazzo'nun sRGB dışına hafifçe taşan üç rengi (amber-600, amber-950, blue-300) temel blokta sRGB'ye sığdırıp orijinal değerleri @media (color-gamut: p3) bloğuna koyması. Karşılaştırmayı outline'ın metni yerine rengin byte'ları üzerinden yapınca fark kayboldu: sRGB ekranda iki değer aynı pikseli veriyor. Geniş renk gamlı ekranlarda ise yeni dosya orijinal rengi gösteriyor, yani ince bir iyileştirme.

Token'ların asıl kazancı ölçümün kontrast satırlarında. 04. yazıda kontrastı bir ekranın metinleri üzerinden ölçmüştük; artık sistemin kendisini ölçebiliyoruz. Dokuz semantic çift (metin/zemin, ikincil metin/yüzey, link/zemin, buton yazısı/buton, üç durum rengi) iki temada da 4.5:1'in üzerinde; en düşük çift açık temada text-muted/surface ile 4.63:1. Bu kontrol CI'da çalışırsa, bir token değişikliği ekranlara ulaşmadan kontrast eşiğini kırdığında yakalanıyor.

Component Library ve Dokümantasyon

Token'lar tek başına bir sistem değil; onları kullanan component'ler ve "bu ne zaman kullanılır" bilgisi de gerekiyor. Storybook'un kendi tanımıyla Storybook, UI component'lerini ve sayfaları uygulamadan bağımsız olarak geliştirmek için bir frontend atölyesi. Her story bir component'in bir state'ini render ediyor: "Primary button, disabled", "Cart, empty". 07. yazıda önerdiğimiz "bütün state'leri yan yana gösteren test sayfası" fikrinin olgun hâli bu; Storybook Angular'ı destekliyor ve story'lerden otomatik dokümantasyon üretebiliyor. Bu seride Storybook kurmadık; component mimarisinin kendisi UI Mimari Pattern'leri serisinin component architecture yazısında.

Küçük bir başlangıç için token'lardan beslenen tek bir sayfa da iş görüyor. web/10-design-system/index.html üretilen CSS'teki bütün --color-* değişkenlerini okuyup her biri için bir renk örneği ve zemine karşı kontrast oranı çiziyor, spacing ölçeğini çubuklarla gösteriyor ve butonun dört state'ini yan yana koyuyor:

const bg = rgb(root.getPropertyValue('--color-bg'));
document.querySelector('#colors').innerHTML = unique.filter((n) => n.startsWith('--color-')).map((n) => `
  <li class="swatch"><span class="chip" style="background: var(${n})"></span>
    <span><code>${n}</code><br><span class="ratio">${ratio(rgb(root.getPropertyValue(n)), bg)}:1</span></span></li>`).join('');

Sayfa token'lardan üretildiği için hiçbir zaman eskimiyor: yeni bir semantic renk eklenince npm run tokens'tan sonra sayfada kendiliğinden görünüyor.

Üretimde Dikkat

Token'lar bir API gibi sürümlenmeli. Bir token'ı silmek ya da adını değiştirmek, onu kullanan her ekranı kırıyor. DTCG bunun için $deprecated property'sini tanımlıyor: token bir süre eski adıyla ve bir açıklamayla yaşıyor, araçlar uyarı veriyor, sonra kaldırılıyor. Token paketini semantic versioning ile yayımlamak ve değişiklik notu tutmak da aynı disiplinin parçası.

Üretilen dosyaları elle düzenleme. Terrazzo'nun çıktısının ilk satırı DO NOT EDIT diyor; elle yapılan bir düzeltme bir sonraki npm run tokens'ta kayboluyor. Bu seride üretilen dosyaları repoya koymadık (.gitignore'da) ve build adımında üretiyoruz. Repoya konması tercih edilirse CI'da "üret ve fark var mı bak" adımı, kaynağın ve çıktının ayrıştığını yakalar.

Yönetişimi küçük tut ama yaz. Yeni bir token'ı kimin önerdiği, tasarımcı ile geliştiricinin nerede anlaştığı ve bir component'in "hazır" sayılması için hangi state'lerin, hangi kontrast ve klavye testlerinin gerektiği tek sayfalık bir dokümanda durmalı. Design system'i bir proje değil bir ürün olarak görmek, bakımını da planlamak demek.

Sık Düşülen Tuzaklar

Birincisi, primitive token'ları doğrudan component'lerde kullanmak. var(--blue-600) yazan bir buton dark temada da aynı maviyi gösterir; component'ler semantic ya da component token'larını okumalı.

İkincisi, her şey için token açmak. Token, tekrar eden bir kararın adı; tek bir yerde kullanılan bir değer token değil, CSS'te kalabilir.

Üçüncüsü, token'ı rengin adıyla adlandırmak. color.blue-button marka rengi değişince yalan söylemeye başlıyor; ad, değeri değil amacı anlatmalı.

Dördüncüsü, geçişi metin karşılaştırmasıyla doğrulamak. Aynı renk birçok biçimde yazılabiliyor; tarayıcıda çözülen değeri karşılaştır.

Beşincisi, araç çıktısına körü körüne güvenmek. Tailwind'in seçicisiz dark bloğu ve varsayılan temanın namespace çakışması ancak üretilen CSS okununca görüldü.

Küçük Bir Deneme

★☆☆ theme-dark.tokens.json'da color.text-muted'ı {palette.gray.400}'e çevir, npm run tokens ve script'i çalıştır. Hangi kontrast çiftinin düştüğünü önce tahmin et, sonra ölçümden oku.

★★☆ Resolver'ın theme modifier'ına darkHighContrast adında bir context ekle: dark dosyasının üstüne yalnız color.text-muted ve color.border'ı değiştiren üçüncü bir dosya koysun. Terrazzo configuration'ına bu bağlam için @media (prefers-contrast: more) seçicili bir permutation ekle ve ölçümle doğrula.

★★★ card.* component token'larını kullanan bir kart component'ini 09. yazının sayfasına uygula ve 09'un dark ölçümünü yeniden çalıştır. Kart ile zemin arasındaki 1.73:1 farkın değişmediğini ve kartın artık semantic token'lara doğrudan bakmadığını doğrula.

Bir sonraki ve son yazıda token'ların diğer ucuna, tasarım aracına geçiyoruz: Figma'yı geliştirici gözüyle okumak, Auto Layout'un Flexbox karşılığı, Figma Variables'ı bu DTCG token'larına bağlamak, Dev Mode ve Code Connect, ve Figma MCP (Model Context Protocol; AI asistanlarının dış araçlara bağlandığı protokol) server ile bir AI asistanına tasarım bağlamı vermenin neyi kolaylaştırdığı ve neyi kolaylaştırmadığı.