Design Token Nedir? DTCG Standardı ile Token Yapısı

Bir ürünün birincil rengi tasarım dosyasında bir yerde, web kodunda başka bir yerde, mobil uygulamada üçüncü bir yerde yazılıysa, o renk bir gün mutlaka üç farklı tona dönüşür. Design token'lar bu dağınıklığı çözmek için vardır: karar bir kez, bir adla verilir ve her platform aynı kaynaktan beslenir. Bu yazı token kavramını, W3C topluluk grubunun 2025.10 formatını, katmanlı token yapısını, tema kurgusunu ve adlandırma kurallarını bir örnek üzerinden anlatıyor.

Design token nedir, neden önemlidir?

DTCG'nin format belgesi token'ı en sade hâliyle insan tarafından okunabilir bir adla ilişkilendirilmiş bilgi, en azından bir ad ve değer çifti olarak tanımlar 3. Teknik raporun giriş sayfası da token'ları renkler, boşluklar ve yazı ölçeği gibi bir design system'in bölünemez parçaları olarak anlatır 2.

Token'ın değeri, kararı değerden ayırmasıdır. "Birincil eylem rengi" bir karardır; bugün belirli bir magenta tonu, yarın başka bir ton olabilir. Ekranlar ve bileşenler değeri değil kararı kullandığında, değişiklik tek bir satırda yapılır ve tüm ürünlere yayılır. Topluluk grubunun duyurusu da standardın, aynı token kaynağından iOS, Android, web ve Flutter için platforma özgü kod üretilmesini desteklediğini vurgular 1.

Design system'in genel yapısını ve token'ların bu yapıdaki yerini design system nedir yazısında anlattık.

DTCG standardı: 2025.10 neyi getirdi?

W3C Design Tokens Community Group, 28 Ekim 2025'te token spesifikasyonunun ilk kararlı sürümünü duyurdu 1. Sürüm üç modülden oluşur 2:

• Format modülü: Token'ların JSON içinde nasıl yazılacağını, türlerini, gruplarını ve birbirine nasıl referans verdiğini tanımlar.
• Renk modülü: Renk değerlerinin hangi renk uzaylarında ve hangi yapıyla yazılacağını tanımlar.
• Resolver modülü: Aynı token setinin açık ve koyu tema gibi farklı bağlamlarda nasıl çözüleceğini tanımlar.

Duyuruda öne çıkan yenilikler; dosya çoğaltmadan açık ve koyu mod, erişilebilirlik varyantları ve marka temalarının yönetilmesi, Display P3 ve Oklch dahil CSS Color Module 4 renk uzaylarının tam desteği ve token'lar arasında kalıtım ile takma ad ilişkileridir 1. Duyuru ayrıca standardı uygulayan ya da destekleyen tasarım araçlarını ve dönüştürücüleri listeler; kendi kullandığınız aracın 2025.10 sürümünü ne ölçüde desteklediğini yine de aracın dokümantasyonundan kontrol etmek gerekir.

Önemli bir ayrıntı: 2025.10, bir nihai topluluk grubu raporudur. Belge kararlı kabul edildiğini, ancak bir W3C Standardı olmadığını ve W3C standart yolunda da bulunmadığını açıkça belirtir 2. Pratikte bu, formatın araçlar arası ortak dil olarak kullanılabilecek olgunlukta olduğu, ama resmi bir standart statüsü taşımadığı anlamına gelir.

Format belgesi dosyalar için .tokens ya da .tokens.json uzantısını ve application/design-tokens+json ortam türünü önerir 3.

Bir token'ın anatomisi

Format modülüne göre bir token'ı tanımlayan özellikler dolar işaretiyle başlar 3:

Token'lar gruplar içinde düzenlenir. Bir grup kendi $type değerini tanımlarsa içindeki token'lar bu türü devralır 3. Bir token başka bir token'ı süslü parantez içinde, grup ve token adlarını noktayla ayırarak yazılan bir yol ile gösterebilir; bu durumda hedefin değeri kullanılır. Daha ayrıntılı erişim için JSON Pointer tabanlı $ref sözdizimi de tanımlanmıştır 3.

Format modülündeki temel türler color, dimension, fontFamily, fontWeight, duration, cubicBezier ve number'dır; bunların yanında shadow, border, transition, strokeStyle, gradient ve typography gibi bileşik türler bulunur 3. İki tür özellikle dikkat ister:

• dimension değeri düz bir metin değil, sayısal value ve px ya da rem olan unit alanlarını içeren bir nesnedir 3.
• color değeri, renk modülüne göre zorunlu colorSpace ve components alanlarını, isteğe bağlı alpha ve altı haneli hex yedeğini içeren bir nesnedir. Modül sRGB, Display P3, Oklch dahil 14 renk uzayını destekler 4.

Token katmanları: ilkel, anlamsal, bileşen

Token'ları katmanlara ayırmak, hangi kararın nerede değiştirileceğini netleştirir. Material Design'ın web bileşen kütüphanesi Material Web bu katmanları açıkça adlandırır: somut değerleri tutan referans token'lar, sisteme karakterini veren rol ve kararları tanımlayan sistem token'ları ve öğelere atanan bileşen token'ları 6. Material'da bileşen token'ları sistem token'larına, sistem token'ları da referans token'lardaki somut değerlere bağlanır 6.

Aşağıdaki örnek, DTCG 2025.10 formatında üç katmanı birlikte gösteriyor. Renk değerleri renk modülündeki nesne yapısıyla, köşe yarıçapı dimension nesnesiyle yazıldı; anlamsal ve bileşen token'ları alttaki katmana referans veriyor:

{
  "primitive": {
    "$type": "color",
    "magenta-600": {
      "$value": { "colorSpace": "srgb", "components": [0.8196, 0.0392, 0.4392], "hex": "#d10a70" }
    },
    "gray-950": {
      "$value": { "colorSpace": "srgb", "components": [0.0784, 0.0784, 0.0784], "hex": "#141414" }
    },
    "white": {
      "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" }
    }
  },
  "semantic": {
    "$type": "color",
    "action-primary": {
      "$value": "{primitive.magenta-600}",
      "$description": "Birincil eylem butonlarının zemini"
    },
    "text-on-action": { "$value": "{primitive.white}" },
    "surface-default": { "$value": "{primitive.white}" },
    "text-default": { "$value": "{primitive.gray-950}" }
  },
  "button": {
    "primary": {
      "background": { "$type": "color", "$value": "{semantic.action-primary}" },
      "label": { "$type": "color", "$value": "{semantic.text-on-action}" },
      "radius": { "$type": "dimension", "$value": { "value": 12, "unit": "px" } }
    }
  }
}

Bu yapıda butonun zemin rengini değiştirmek isteyen ekip yalnız bileşen katmanına dokunur; tüm birincil eylemlerin rengini değiştirmek isteyen ekip anlamsal katmana, marka paletini yenileyen ekip ise ilkel katmana. Ekranlarda ve bileşenlerde ilkel token'ların doğrudan kullanılmaması bu ayrımın işlemesi için şarttır.

Tema: açık ve koyu mod

Katmanlı yapının en büyük getirisi temalarda ortaya çıkar. Koyu temada ilkel palet çoğunlukla aynı kalır; değişen, anlamsal token'ların hangi ilkel değeri gösterdiğidir. Yüzey rengi açık temada beyazı, koyu temada koyu griyi gösterir; bileşen token'ları anlamsal katmana bağlı olduğu için hiç değişmez.

DTCG'nin Resolver modülü bu senaryo için tasarlandı. Modül; token kaynaklarını bir araya getiren setleri, "light" ve "dark" gibi bağlamlar içeren değiştiricileri ve bunların hangi sırayla birleşeceğini belirleyen bir çözümleme sırasını tanımlar; sonradan gelen değer çakışmada öncekini ezer 5. Resolver dosyaları .resolver.json uzantısını kullanır ve sürüm olarak 2025.10 belirtmek zorunludur 5. Modül aynı yaklaşımın yüksek kontrast, farklı ekran boyutları ve azaltılmış hareket gibi bağlamlar için de kullanılabileceğini belirtir 5. Basitleştirilmiş bir örnek:

{
  "version": "2025.10",
  "sets": {
    "base": { "sources": [{ "$ref": "primitive.tokens.json" }, { "$ref": "components.tokens.json" }] }
  },
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [{ "$ref": "semantic-light.tokens.json" }],
        "dark": [{ "$ref": "semantic-dark.tokens.json" }]
      }
    }
  },
  "resolutionOrder": [{ "$ref": "#/sets/base" }, { "$ref": "#/modifiers/theme" }]
}

Koyu tema yalnız renklerin ters çevrilmesi değildir; her anlamsal renk çiftinin kontrastı iki temada ayrı ayrı kontrol edilmelidir. Mobil tarafta kontrast ve dinamik yazı boyutu gibi konuları mobil uygulama erişilebilirliği yazısında ele aldık.

Adlandırma kuralları

Format belgesi adlar için yalnız birkaç teknik kısıt koyar: token ve grup adları dolar işaretiyle başlayamaz, süslü parantez ve nokta karakterlerini içeremez, çünkü bunlar özellik ve referans sözdiziminde kullanılır 3. Geri kalan kararlar size kalır. Sağlam bir adlandırma için şu adımlar işe yarar:

1. Katmanı adın başında belirtin. İlkel, anlamsal ve bileşen token'ları bir bakışta ayırt edilebilmelidir.
2. Anlamsal adlarda değeri değil rolü yazın. "action-primary" tema değişince de doğru kalır; "magenta-button" ise ilk marka yenilemesinde yanlış olur.
3. Sabit bir sıra kullanın. Örneğin kategori, rol, varyant ve durum sırası; "text-default", "text-muted", "text-on-action" gibi.
4. Ölçeklerde aralık bırakın. 100, 200, 300 gibi adımlar, araya yeni bir ton eklemeye yer bırakır.
5. Tek bir dil ve karakter seti seçin. Token adları koda dönüştüğü için Türkçe karakterler bazı araçlarda sorun çıkarabilir; çoğu ekip ASCII karakterlerle İngilizce adlar kullanır. Hangi tercih yapılırsa yapılsın, karışık kullanılmamalıdır.
6. Kaldırmayı da planlayın. Kullanımdan kalkan token'ı silmeden önce $deprecated ile işaretleyip yerine geçen token'ı açıklamada belirtin 3.

Token'ları tasarımdan koda taşımak

Token'lar ancak tasarım dosyası ile kod aynı kaynaktan beslendiğinde işe yarar. Yaygın akış şöyledir: token dosyası sürüm kontrolünde tutulur, bir dönüştürücü bu dosyadan web için CSS değişkenleri ve mobil platformlar için kod üretir, tasarım aracındaki değişkenler de aynı dosyayla eşitlenir. Böylece "tasarımda başka, kodda başka" tartışması teknik olarak ortadan kalkar.

Bu akışın tasarım tarafını, yani token envanterini, katman yapısını, adlandırma rehberini ve geliştirici devrini nasıl hazırladığımızı design system hizmeti sayfasında bulabilirsiniz.