Figma Variables Mimarisi: Prodüksiyonda Ayakta Kalan Bir Token Sistemi Nasıl Kurulur

Figma variables kullanan ekiplerin çoğu, stil temelli bir zihinsel model üzerine inşa ediyor ve sorun tam da bu. Mimarisiz variables, fazladan tıklamalı stillerden ibaret.

Doğru yapan ekipler Figma variables'ı gerçek bir design tokens katmanı olarak ele alıyor: yapılandırılmış, alias'lı, kapsamlandırılmış ve dışa aktarılabilir. Yanlış yapanlar ise bir dark mode talebi uzakta tam bir yeniden kurulumdan. Prodüksiyonda ayakta kalan mimari bu.

Variables stil değildir, token katmanıdır

Figma stilleri hazır ayarlardır. Bir renk, bir metin stili, bir efekt tanımlarsınız ve doğrudan bir katmana uygularsınız. Bu, tek markalı, tek modlu ve dev handoff gereksinimi olmayan bir dosya için işe yarar. Bir şey değiştiği an çalışmayı bırakır.

Figma variables birer token'dır. Bir variable bir değer tutar ama başka bir variable'a referans da tutabilir. Bu referans zinciri ve çözümlenmiş değerlerin tüm setlerini modes ile değiştirebilme yeteneği, variables'ı mimari olarak stillerden ayıran şeydir. Bu ayrım kozmetik değil. Hazır ayar sistemi ile token sistemi arasındaki fark bu.

Üç katmanlı token mimarisi

Primitives, semantic, component. Çalışan her variable sisteminde bu üç katman vardır. Semantic katmanı atlamak, bugün Figma dosyalarındaki en yaygın mimari hatadır.

Üç katman üç işe karşılık gelir: primitives ham değerleri tutar, semantic tokens anlam taşır, component tokens ise tek bir component ailesine kapsamlanır. Her katman yalnızca altındaki katmanla konuşur. Atlama yok, kısa yol yok.

Üç katman proje boyutuna göre isteğe bağlı değildir. Beş component'li küçük bir sistem bile üç katmanın hepsine ihtiyaç duyar, yoksa ilk tema talebi onu paramparça eder.

Birinci katman: primitives

Primitives ham değerlerdir. blue-500, gray-900, space-4, radius-md. Palet, ölçek, temel onlar. Hiçbir zaman doğrudan bir component katmanına bağlanmazlar.

Bir primitive'in işi var olmak, yukarıdan alias'lanmak ve yoldan çekilmektir. Bir tasarımcı bir butona uygulamak için blue-500'e uzanıyorsa, mimari zaten bozulmuştur. Primitives, primitives collection'a aittir ve başka hiçbir yere değil.

İsimlendirme kuralı burada önemli. Primitives ölçek temelli veya palet temelli olmalı, asla semantic olmamalı. blue-500 doğru. Primitive olarak button-blue ise ölçek büyüdükçe acı çektiren bir kategori hatasıdır.

İkinci katman: semantic

Semantic tokens anlam taşır. surface, surface-elevated, text-primary, text-muted, border-default, border-focus. "Bu hangi renk?" yerine "Bu renk ne için?" sorusunu yanıtlarlar.

Semantic tokens primitives'e alias'lanır. Sahip oldukları tek ilişki budur. Semantic'ten semantic'e alias vermek, değerin nerede yaşadığı konusunda belirsizlik yaratır ve mode override'larını güvenilmez kılar.

Light, dark ve brand modlarınız bu katmanda yaşar. Bir semantic token, aktif moda göre farklı bir primitive'e çözümlenir; tema işleyişi gerçekte böyledir. blue-500 primitive'i değişmez. text-link semantic token'ı ise moda göre neye çözümleneceğini değiştirir.

Üçüncü katman: component

Component tokens tek bir component ailesine kapsamlanır. button-bg, button-text, button-border, card-surface, card-border, input-bg. Semantic tokens'a alias'lanırlar, asla primitives'e değil.

Bir component token'ın işi, bağımlılık yaratmadan özgüllük sağlamaktır. button-bg, surface-action'a çözümlenir, o da blue-500'e. Marka değiştiğinde semantic katmanı güncellersiniz ve buton onunla birlikte güncellenir. Component token'a dokunulmaz.

Sık gelen bir itiraz, bunun sebepsiz fazladan token gibi hissettirmesidir. Sebep şu: button-bg ve surface-action ayrışabilir. Bir noktada bir ürün kararı, butonun biraz farklı bir yüzey kullanmasını gerektirir. Component tokens, semantic sisteme dokunmadan size override noktası verir.

Modes ve collections: karar ağacı

Modes, bir collection içindeki değerleri değiştirir. Collections ise ilgi alanlarını ayırır. Bu ikisi aynı şey değildir ve ikisini karıştırmak, Figma variable kurulumlarındaki mimari kafa karışıklığının çoğunun kaynağıdır.

Kural şu: ilgi alanı başına bir collection, aynı ilgi alanının varyantları için modes. Renk bir ilgi alanıdır. Spacing bir ilgi alanıdır. Light ve dark ayrı ilgi alanları değildir. Aynı renk ilgi alanının modlarıdır.

Mode ile yeni collection arasında nasıl seçim yapılır:

• Aynı şeyin farklı değeri mi? Mode.
• Tamamen farklı bir şey mi? Collection.
• Light ile dark arasında geçiş mi? Renk collection'ı içinde mode.
• Compact ile comfortable spacing arasında geçiş mi? Spacing collection'ı içinde mode.
• Marka mı ekliyorsunuz? Yeni collection değil, semantic katman içinde mode.

Dört kapsam kuralı

Variable scoping, bir variable'ın Figma'da nerelere uygulanabileceğini kontrol eder. Bunu yanlış yapmak, tasarımcıların yanlışlıkla semantic tokens yerine primitives'e uzanabilmesi demektir ve mimari disiplin kullanım noktasında çöker.

Dört kural tartışmasızdır:

1. Primitives'i none olarak kapsamlandırın. Primitives hiçbir yerde uygulanabilir olmamalı. Bunlar tüketiciye dönük token değil, iç değerlerdir. Apply açılır listesinden tamamen gizleyin.
2. Semantic tokens'ı türlerine göre kapsamlandırın. Bir renk semantic token'ı fills ve strokes'a kapsamlanır. Bir spacing token'ı gap, padding ve size alanlarına kapsamlanır. Kapsamı dar tutun.
3. Component tokens'ı ailelerine göre kapsamlandırın. Bir button token'ı bir card'a uygulanabilir olmamalı. Kapsam fazla genişse component sınırı anlamsızdır.
4. Primitives'i asla tüketicilere açmayın. Bir tasarımcı ya da geliştirici bir katmana primitive uyguluyorsa, sistem kapsam katmanında başarısız olmuştur. Bu bir süreç hatasıdır, kullanıcı hatası değil.

Temaları mümkün kılan alias zinciri

Çalışan bir tema bir alias zinciridir: component semantic'e, semantic primitive'e alias'lanır, primitive değeri tutar. Zincir uzunluğu üçtür, her zaman üç.

İki uzunluğundaki bir zincir (component'ten primitive'e) çeviri katmanını atlar ve her component token'da elle override yapmadan modes'u imkânsız kılar. Dört uzunluğundaki bir zincir ise modu hangi semantic katmanın taşıdığı konusunda belirsizlik yaratır ve denetlemek bir arama değil, hata ayıklama egzersizine dönüşür.

button-bg → surface-action → blue-500 → #0066FF

Copy

Bu zincir, semantic collection'ın dark modunda surface-action'ı blue-300'e yönlendirerek dark mode'dan sağ çıkar. button-bg token'ı otomatik güncellenir. blue-500 primitive'i hâlâ #0066FF'e çözümlenir. Başka hiçbir şeyin değişmesi gerekmez.

Light, dark ve brand modları

Çoğu variable sisteminin ihtiyaç duyduğu üç mod light, dark ve brand'dir. Bunları yalnızca semantic katman taşır. Asla primitive katmanı değil.

Modes'u primitives'e uygulamak bir kategori hatasıdır. blue-500 her zaman #0066FF'tir. O bir primitive'dir. Anlam taşımadığı için light ya da dark varyantı yoktur. text-link semantic token'ının light ve dark varyantı vardır, çünkü farklı bağlamlarda farklı çözümlenen bir anlam taşır.

Brand modları da aynı şekilde çalışır. Marka gerçekten farklı ham değerler kullanmadıkça ikinci bir marka için ikinci bir primitive paletine ihtiyaç yoktur. Çoğu zaman, semantic katmanda mevcut primitives'in farklı bir alt kümesini işaret eden bir brand mode doğru karardır. İki marka için iki tam primitive collection genellikle fazlalıktır. Yukarı akıştaki renk kararlarının bunu nasıl şekillendirdiği için, semantic katman yapınızı sabitlemeden önce dark mode renk sistemi yazısını okumaya değer.

Number, string ve boolean variables

Figma variables yalnızca renklerden ibaret değildir. Number variables spacing, sizing ve radius'u kontrol eder. String variables tasarım dosyalarındaki metni kontrol eder. Boolean variables katman görünürlüğünü kontrol eder ve bu doğrudan component props'a karşılık gelir.

Bu, ekiplerin çoğunun kullanmadığı variables sistemi parçasıdır ve tasarım ile kod arasındaki boşluğu en çarpıcı biçimde kapatan da odur. Number variables olarak tanımlanıp auto-layout gap'lerine uygulanan bir spacing ölçeği, variable'daki bir spacing değişikliğinin o token'ı kullanan her component'i güncellemesi demektir. Gerçek bir token sistemi tam olarak bunu yapar.

Locale modlu string variables, tasarımcıların bir dosyayı İngilizce ile Arapça arasında çevirip layout'un gerçek zamanlı bozulduğunu görmesini sağlar. Component props'a eşlenen boolean variables ise Figma component'i ile kod component'i arasında bire bir prop ilişkisi demektir; bu da dev handoff'u yorumlanabilir olmaktan çıkarıp gözden geçirilebilir yapar.

Koda handoff: işe yarayan desen

Bir variable sistemi, ancak dışa aktarımı kadar iyidir. Çalışan handoff deseni Tokens Studio veya Figma Variables REST API'si, artı bir dönüştürme pipeline'ı, artı koda tarafında bir import script'idir.

Tokens Studio, variable collections'ı Style Dictionary ile uyumlu yapılandırılmış bir JSON formatına aktarır. Style Dictionary bu JSON'u kod tabanının ihtiyaç duyduğu çıktıya dönüştürür: CSS custom properties, Swift color sets, Kotlin resource dosyaları, Tailwind config. İsimlendirme kurallarının normalleştirildiği ve kod kurallarına eşlenmeyen Figma'ya özgü isimlerin temizlendiği yer bu dönüştürme adımıdır.

Pipeline elle değil, her variable güncellemesinde çalışmalı. Bir Tokens Studio push'unda tetiklenen bir GitHub Action ya da variable değişikliklerinde ateşlenen bir Figma webhook'u, kimsenin dışa aktarmayı hatırlamasına gerek kalmadan kod tarafındaki token'ları senkron tutar. Stripe ve Atlassian'ın ölçekte çalıştırdığı desen budur ve build adımı olan her kod tabanında uygulanabilir. O çıktıdaki renk token'ı format kararları için, CSS custom property değerlerini sabitlemeden önce OKLCH color yazısını okumaya değer.

---

Modes, markalar ve dev handoff'a yeniden yazım gerektirmeden dayanan bir Figma variable sistemi mi istiyorsunuz? Brainy, üç katmanlı model, alias zinciri ve kod tabanınıza sorunsuz oturan dışa aktarım pipeline'ı ile Figma'da prodüksiyon seviyesinde token mimarileri tasarlar. Brainy'yi tutun

---

Variable sistemlerini bozan yedi yaygın hata

Bu hataların çoğu aynı kök nedeni paylaşır: variables panelini mimari bir katman olarak değil, daha iyi bir stiller paneli olarak görmek. Düzeltme zihinsel model değişimidir. Geri kalan her şey ondan çıkar.

Variable sistemi denetimi

Bu denetimi herhangi bir Figma variable sisteminde çalıştırın, mimari borcu ürün yayına çıkmadan yakalarsınız.

Yapı

• En az üç collection: primitives, semantic, component (veya eşdeğer isimlendirme)
• Her collection'ın tek ve net bir ilgi alanı var
• Hiçbir collection türleri karıştırmıyor (renk ve spacing'in aynı collection'da olması bir başarısızlıktır)

Alias zinciri

• Her component token'ı bir semantic token'a alias'lanıyor, primitive'e değil
• Her semantic token bir primitive'e alias'lanıyor, başka bir semantic token'a değil
• Primitives dışında hiçbir token ham değer tutmuyor
• Tüm renk token'ları için alias zinciri uzunluğu tam olarak üç

Modes

• Light ve dark, ayrı collection'lar değil, semantic collection'daki modes
• Marka varyantları, ayrı dosyalar değil, semantic collection'daki modes
• Primitive collection'da hiç mode yok

Scoping

• Primitive variables none olarak kapsamlanmış (hiçbir yerde uygulanamaz)
• Semantic variables türlerine göre kapsamlanmış (renk için fills/strokes, spacing için layout alanları)
• Component variables component ailelerine göre kapsamlanmış

Handoff

• Variables, Tokens Studio veya REST API ile dışa aktarılabiliyor
• Dönüştürme pipeline'ı var ve otomatik
• Kod tarafındaki token'lar, belgelenmiş istisnalarla Figma variable isimlendirme kuralına uyuyor

Bunlardan üçten fazlası başarısız oluyorsa sistemin yama değil, yeniden kurulum ihtiyacı vardır. Denetim en çok borcu orada gösteriyorsa, primitive katmanı besleyen yukarı akıştaki renk kararlarını marka renk paleti yazısı ele alıyor.

SSS

Figma variables ile Figma stilleri arasındaki fark nedir?

Stiller doğrudan katmanlara uygulanan hazır ayarlardır. Variables ise birbirine referans verebilen ve modes ile değer değiştirebilen token'lardır. Variables stillerin yaptığı her şeyi yapabilir, üstüne tema desteği ve dışa aktarımla dev handoff ekler. Yeni bir design system için variables doğru seçimdir. Olgun bir stil sistemi olan mevcut bir dosyada ise geçmeden önce bir migrasyon planı yazmaya değer.

Bir Figma variable sisteminde kaç collection olmalı?

Çoğu sistem için üç ila beş: primitives, semantic, component ve bu ölçekler kendi kapsam kurallarını gerektirecek kadar karmaşıksa isteğe bağlı olarak ayrı spacing ve typography collection'ları. Beşten fazla collection genellikle ilgi alanlarının doğru gruplanmadığının işaretidir.

Figma variables, Tokens Studio'nun yerini alabilir mi?

Figma içinde oluşturma ve düzenleme için evet. Yerel variables paneli, variables API'si çıkmadan önce Tokens Studio'nun yaptığı şeylerin çoğunu karşılıyor. Dışa aktarım ve dönüştürme için ise Tokens Studio hâlâ değer katıyor, çünkü Style Dictionary'ye giden olgun bir pipeline'ı var ve yerel dışa aktarımın karşılamadığı uç durumları ele alıyor. İki araç şu an rakip değil, birbirini tamamlıyor.

Bir semantic token'ı başka bir semantic token'a alias'larsam ne olur?

Mode çözümlemesi belirsizleşir. text-secondary, text-primary'ye alias'lanmışsa ve dark mode'a geçerseniz, Figma zinciri çözümler ve dark mode override'ını beklediğiniz yere uygulamayabilir. Semantic'ten semantic'e alias ayrıca sistemi ölçekte denetlemeyi neredeyse imkânsız kılar. Kural sert: semantic tokens yalnızca primitives'e alias'lanır.

Sistemi yeniden kurmadan üçüncü bir markayı nasıl ele alırım?

Semantic collection'a üçüncü bir mode ekleyin. Markalar gerçekten farklı ham değerler kullanmadıkça primitive collection markalar arasında paylaşılır. Primitives'in farklı bir alt kümesini işaret eden semantic katmandaki bir brand mode doğru mimaridir. Markalar o kadar farklıysa ki primitive paletleri hiç örtüşmüyorsa, paylaşılan bir semantic yapıyla iki primitive collection yedek çözümdür.

Üç katmanlı model küçük projeler için gerekli mi?

Evet, ama her katmanın boyutu küçülür. Küçük bir projede on beş primitive, sekiz semantic token ve component başına iki component token olabilir. Mimari yine üç katmandır. Küçük projelerde semantic'i atlama cazibesi, ikinci bir tasarımcı ya da bir dark mode talebi geldiği anda bu kadar çok küçük projenin mimari borca dönüşmesinin sebebidir. Token mimarisinin daha geniş stack kararına nasıl oturduğu için Framer vs Webflow vs Next.js yazısında bağlam var.

Figma variables'ın gerçekten açtığı değişim

Figma'daki gerçek bir variable sistemi, tasarım ve geliştirme tarafının tek doğruluk kaynağına en çok yaklaştığı noktadır. Bir handoff dokümanı değil. Bir Zeplin linki değil. Her iki tarafın da aynı tanımlardan okuduğu yaşayan, dışa aktarılabilir, yapılandırılmış bir token katmanı.

Variables'ı mimari olarak ele alan ekipler design system borcunu yarıya indiriyor; variables sihirli olduğu için değil, iyi bir variable sisteminin gerektirdiği mimari disiplin, design system'lerin sürekli ertelediği kararları da zorunlu kıldığı için. Bu token ne anlama geliyor? Neye alias'lanabilir? Primitive kimin sorumluluğunda? Bu soruların artık cevapları var ve cevaplar dosyanın içinde yaşıyor.

Mimarisiz variables, fazladan tıklamalı stillerden ibarettir. Üç katmanlı model, alias zinciri, kapsam kuralları ve dışa aktarım pipeline'ı olan variables ise ikinci bir markadan, bir dark mode'dan ve Figma'yı hiç açmamış bir geliştiriciden sağ çıkabilen bir design system'dir.

Sadece token'ları değil, mimariyi kurun.