Kurumsal Tasarım Sistemi: Token, Bileşen Kütüphanesi ve Yönetişim

Aynı mavinin dört tonu, üç farklı düğme yüksekliği, her projede baştan yazılan bir tarih seçici. Bir kurumda birden fazla web uygulaması, müşteri portalı ve kurumsal site ayrı ekiplerce geliştirildiğinde arayüz bu hale gelir. Tasarım sistemi, tasarım kararlarını ve bileşenleri sürümlenen, belgelenen ve ortak kullanılan bir ürüne çevirerek bu dağılmayı durdurur. Aşağıda token’dan bileşen kütüphanesine, sürümlemeden katkı sürecine kadar kod tabanlı bir sistemin kurulumunu ve hangi durumda kurulmaması gerektiğini anlatıyoruz.

Tasarım sisteminin kapsamı

“Tasarım sistemi” her ekipte başka bir şey anlamına gelir. Tasarımcı Figma kütüphanesini, ön yüzcü npm paketini, ürün yöneticisi stil rehberini düşünür. Kapsamı baştan yazılı tanımlamazsanız beklenti farkı ve yarım kalan çalışma kaçınılmazdır. Tipik katmanlar şunlar:

Katman	İçerik	Sahibi
Temeller	Renk, tipografi, boşluk, köşe yarıçapı, gölge, hareket token’ları	Tasarım + ön yüz
Bileşenler	Düğme, form alanı, modal, tablo, bildirim; durumları ve varyantları	Ön yüz ekibi
Desenler	Form düzeni, liste–detay ekranı, boş durum, hata sayfası	Tasarım + ürün
İçerik kuralları	Hata mesajı dili, düğme metinleri, tarih/para biçimi	İçerik / ürün
Yönetişim	Sürümleme, katkı süreci, karar kayıtları, destek kanalı	Sistem ekibi

Küçük başlayın: temeller ve en sık kullanılan 8–10 bileşenle ilk sürümü çıkarmak, tüm katmanları aynı anda bitirmeye çalışmaktan sağlıklıdır. Öncelikli bileşenleri bulmak için mevcut uygulamalardan ekran görüntüsü envanteri çıkarıp tekrar eden öğeleri gruplamak yeter. Envanter, tartışmayı bitirir.

Tasarım token’ları ve CSS değişkenleri

Token, bir tasarım kararının platformdan bağımsız, isimlendirilmiş halidir. Sağlıklı yapıda iki katman bulunur: temel (primitive) token’lar ham değeri tutar (color.blue.600), anlamsal (semantic) token’lar kullanım amacını ifade eder ve temel token’a referans verir (color.action.primary). Bileşenler yalnız anlamsal token kullanır; marka rengi değişince ya da karanlık tema eklenince bileşen koduna dokunulmaz. Sahada en sık gördüğümüz hata, bileşenlerin doğrudan blue-600 gibi temel token’lara bağlanmasıdır. Tema geldiği gün yüzlerce dosya değişir.

{
  "color": {
    "blue":  { "600": { "$type": "color", "$value": "#1d4ed8" } },
    "gray":  { "900": { "$type": "color", "$value": "#111827" } },
    "action": {
      "primary": { "$type": "color", "$value": "{color.blue.600}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.gray.900}" }
    }
  },
  "space": {
    "2": { "$type": "dimension", "$value": "8px" },
    "4": { "$type": "dimension", "$value": "16px" }
  }
}

Bu biçim W3C Design Tokens Community Group’un önerdiği $type/$value yapısını izler. Token kaynak dosyaları Git’te tutulur ve bir derleme aracıyla hedef platformlara dönüştürülür. Style Dictionary bu iş için yaygın açık kaynak araçtır; $type/$value biçimini doğrudan okuma desteği 4. ana sürümle geldi, eski sürümler value anahtarı bekler. Aşağıdaki yapılandırma her iki sürümde de temel CSS çıktısını üretir:

// style-dictionary yapılandırması (config.json)
{
  "source": ["tokens/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "dist/css/",
      "files": [{ "destination": "tokens.css", "format": "css/variables" }]
    }
  }
}

Çıktı, :root altında --color-action-primary gibi CSS özel özellikleri içeren bir dosyadır. Tema desteği için anlamsal katman ikinci bir değer setiyle yeniden tanımlanır:

:root {
  --color-action-primary: #1d4ed8;
  --color-text-default: #111827;
  --color-surface: #ffffff;
}
[data-theme="dark"] {
  --color-action-primary: #60a5fa;
  --color-text-default: #f3f4f6;
  --color-surface: #0f172a;
}
.btn-primary {
  background: var(--color-action-primary);
  padding: var(--space-2) var(--space-4);
}

Kontrastı token düzeyinde doğrulayın: her anlamsal metin/arka plan çifti için WCAG eşikleri (normal metinde en az 4,5:1) derleme sırasında bir betikle kontrol edilebilir. Eşiği tutmayan çift derlemeyi kırsın, ekranda keşfedilmesin. Bileşen düzeyindeki diğer erişilebilirlik gereksinimleri için WCAG 2.2 geliştirici rehberine bakın.

Figma ile kod arasında senkron

Tasarımcılar Figma’da değişkenlerle (variables) çalışıyorsa token’ların tek gerçeklik kaynağının nerede duracağına karar verin. İki yaygın model var: token’lar Git’te tutulur ve Figma’ya aktarılır, ya da Figma’da düzenlenip bir eklenti veya API üzerinden Git’e çekme isteği (pull request) olarak gelir. Hangisini seçerseniz seçin değişiklik kod incelemesinden geçmeli, kimse iki yerde elle güncelleme yapmamalıdır. Yoksa birkaç ay içinde tasarım dosyası ile canlı arayüz ayrışır ve kimse hangisinin doğru olduğunu bilmez.

Bileşen kütüphanesi ve dokümantasyon

Bileşen kütüphanesinde işin kaderini API tasarımı belirler. Prop’lar sürümler boyunca bir sözleşmedir; her ekibin özel ihtiyacına yeni bir boolean prop eklemek kısa sürede yönetilemez bir yüzey yaratır. On yedi prop’lu bir düğme artık düğme değildir. Bu riski düşüren ilkeler:

• Varyantları serbest metin yerine sınırlı birleşim tipleriyle tanımlayın: variant: 'primary' | 'secondary' | 'danger'.
• Stil geçersiz kılmayı (style, rastgele className) kontrollü sunun; aksi halde tutarlılık yine dağılır.
• Karmaşık bileşenlerde tek dev bileşen yerine birleşik (compound) yapı kullanın: <Dialog>, <Dialog.Title>, <Dialog.Actions>.
• Erişilebilirliği bileşenin içinde çözün: odak yönetimi, ARIA öznitelikleri ve klavye davranışı kullanan ekibe bırakılmasın.
• Sıfırdan yazmak yerine davranışı hazır, stilsiz (headless) bir kütüphanenin üzerine kendi görsel katmanınızı kurmayı değerlendirin; karmaşık bileşenlerin klavye ve ARIA davranışını doğru yazmak ciddi emek ister.

Dokümantasyonda Storybook yaygın tercihtir: her bileşenin varyantları “story” olarak yazılır, prop tablosu TypeScript tiplerinden otomatik üretilir ve etkileşimli denenebilir. Erişilebilirlik eklentisi (@storybook/addon-a11y) axe-core taramasını her story’de çalıştırır. Görsel regresyon testi (story ekran görüntülerinin karşılaştırılması) istenmeyen stil değişikliklerini yayından önce yakalar; bir token değişikliğinin hangi bileşenleri etkilediğini çoğu zaman ilk burada görürsünüz.

// Button.stories.tsx (Storybook, CSF 3)
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  component: Button,
  args: { children: 'Kaydet' },
};
export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = { args: { variant: 'primary' } };
export const Danger: Story = { args: { variant: 'danger' } };
export const Disabled: Story = { args: { variant: 'primary', disabled: true } };

Yapılandırma ve eklenti ayrıntıları için resmi Storybook dokümantasyonu esas alınmalı; sürümler arasında paket adları ve yapılandırma biçimi değişebiliyor.

Sürümleme ve dağıtım

Tasarım sistemini tüketen uygulamalar onu bir bağımlılık olarak kullanır. Anlamsal sürümleme (SemVer) disiplini bu yüzden pazarlık konusu değildir:

Değişiklik	Sürüm	Örnek
Hata düzeltme, görsel ince ayar	Yama (1.4.2 → 1.4.3)	Odak halkası kalınlığı düzeltmesi
Geriye uyumlu yeni özellik	Küçük (1.4.3 → 1.5.0)	Düğmeye yeni size değeri
Kırıcı değişiklik	Büyük (1.5.0 → 2.0.0)	Prop adı değişikliği, token silinmesi

Sahada işe yarayan uygulamalar:

• Token’ları ve bileşenleri ayrı paketler olarak yayımlayın (ör. @kurum/tokens, @kurum/react). React ve Next.js uygulamaları bileşen paketini, React kullanmayan bir proje veya WordPress teması yalnız token CSS’ini kullanabilir.
• Paketleri kurum içi bir npm kayıt deposunda (GitHub Packages, GitLab Package Registry, Azure Artifacts veya Verdaccio) yayımlayın.
• Değişiklik günlüğünü elle değil, Changesets gibi bir araçla her çekme isteğinde üretin; sürüm tipi katkı sırasında belirlenir.
• Kırıcı değişiklikten önce eski API’yi en az bir küçük sürüm boyunca “deprecated” uyarısıyla yaşatın ve mümkünse otomatik dönüşüm betiği (codemod) verin.
• Yayın hattını CI’da çalıştırın: tip kontrolü, birim testleri, erişilebilirlik taraması ve görsel regresyon geçmeden paket yayımlanmasın. Hattın kurulumu için GitHub Actions ile CI/CD hattı rehberine bakabilirsiniz.

Katkı ve karar süreci

Tasarım sistemleri genellikle teknik değil, organizasyonel nedenle çöker: ekip ihtiyaç duyduğu bileşeni sistemde bulamaz, katkı süreci haftalar sürer ve herkes kendi kopyasını yazar. Altı ay sonra sistem kâğıt üzerinde vardır. Bunu önlemek için süreç yazılı ve hafif olmalı:

1. Talep: Yeni bileşen veya varyant ihtiyacı bir şablonla açılır: kullanım senaryosu, ekran görüntüsü, kaç ürünün ihtiyaç duyduğu.
2. Değerlendirme: Sistem ekibi ihtiyacın mevcut bir bileşenle karşılanıp karşılanamayacağına bakar. Tek ürüne özgü ihtiyaç ürün içinde kalır; iki veya daha fazla üründe tekrar ederse sisteme alınır.
3. Tasarım ve API önerisi: Kod yazılmadan önce prop’lar, durumlar ve erişilebilirlik davranışı kısa bir dokümanda kararlaştırılır.
4. Uygulama: Katkıyı talep eden ekip de yapabilir; sistem ekibi inceler ve standartlara uygunluğu onaylar.
5. Kayıt: Önemli kararlar (ör. “tarih seçici takvimi neden haftaya pazartesiden başlıyor”) karar kaydı olarak saklanır; aynı tartışma ikinci kez açılmaz.

Benimsemeyi ölçmek için tüketen depolarda sistem bileşenlerinin ve yerel kopyaların kullanımını tarayan basit bir betik yeter. Kod düzeyindeki modül sınırları ve lint kurallarıyla yerel kopyaların önüne geçme yöntemleri TypeScript kod tabanı standartları rehberinde anlatılıyor.

Tasarım sistemi gerekmediği durumlar

Tasarım sistemi kalıcı bir bakım yüküdür: en az bir kişinin düzenli zamanını, güncel dokümantasyonu ve tüketen ekiplerle sürekli iletişimi ister. Aşağıdaki durumlarda tam sistem yerine hafif bir yaklaşım yeterlidir:

• Tek ürün, tek ekip: Ortak bileşenler uygulamanın içinde bir klasörde durur; ayrı paket ve sürümleme gereksiz yük getirir.
• Ürün henüz şekilleniyor: Arayüz her sprintte değişiyorsa erken soyutlama yanlış API’leri kalıcı hale getirir.
• Hazır kütüphane ihtiyacı karşılıyor: Olgun bir bileşen kütüphanesinin üzerinde yalnız token’larla tema tanımlamak birçok iç uygulama için yeterlidir.
• Sahiplik yok: Bakımı üstlenecek kişi veya ekip belli değilse sistem birkaç ay içinde güncelliğini yitirir ve ekipler ondan kaçmaya başlar. Sahipsiz sistem çürür.

Bu durumlarda bile token katmanını kurmak düşük maliyetli, yüksek getirili bir ilk adımdır: renk ve tipografi kararlarını tek dosyada toplamak ileride tam sisteme geçişi kolaylaştırır. WordPress tabanlı sitelerde benzer tutarlılık Elementor global stilleriyle sağlanır; bu yaklaşım Elementor ile ölçeklenebilir site yapısı rehberinde anlatılıyor ve token CSS’i bu iki ortam arasında ortak payda olabilir.

Birden fazla uygulama ve site için ortak bir arayüz dili kurmayı planlıyorsanız UI/UX ve kurumsal tasarım sistemi çalışmasını kapsam ve sahiplik modeliyle birlikte ele alıyoruz.

Sık sorulan sorular

Tasarım sistemi ile bileşen kütüphanesi aynı şey mi?

Hayır. Bileşen kütüphanesi tasarım sisteminin bir parçasıdır. Tasarım sistemi ayrıca token’ları, kullanım desenlerini, içerik kurallarını, dokümantasyonu ve sürümleme ile katkı sürecini içeren yönetişimi kapsar.

Token’lar neden temel ve anlamsal olarak ikiye ayrılır?

Temel token’lar ham değeri, anlamsal token’lar kullanım amacını tutar. Bileşenler yalnız anlamsal token kullanırsa marka rengi değişikliği veya karanlık tema bileşen koduna dokunmadan, yalnız anlamsal katmanı yeniden eşleyerek yapılır.

Tasarım sistemi hangi aşamada kurulmalı?

Aynı arayüz öğelerinin iki veya daha fazla ürün ya da ekip tarafından tekrar yazıldığı görülmeye başlayınca kurmak anlamlıdır. Tek ürünlü ve arayüzü hâlâ hızla değişen projelerde token katmanıyla başlamak yeterlidir.

Tasarım sistemindeki kırıcı değişiklikler nasıl yönetilir?

Anlamsal sürümleme kullanılır; kırıcı değişiklik büyük sürüm numarasını artırır. Eski API en az bir küçük sürüm boyunca kullanımdan kaldırma uyarısıyla korunur, değişiklik günlüğüne geçiş adımları yazılır ve mümkünse otomatik dönüşüm betiği verilir.