Shadcn UI Kullanarak Şirket İçi Tasarım Sistemi Kurmak

Shadcn UI Kullanarak Şirket İçi Tasarım Sistemi Kurmak, birkaç hazır component'i projeye eklemekten çok daha kapsamlı bir mühendislik ve ürün tasarımı çalışmasıdır. Şirket büyüdükçe aynı Button'ın farklı ürünlerde farklı görünmesi, renklerin doğrudan kod içine yazılması, tasarım ile production ekranlarının ayrışması ve ekiplerin birbirinden bağımsız component üretmesi ciddi bakım maliyeti oluşturur. İyi kurulan bir design system bu sorunları design token, component katmanları, erişilebilirlik standartları, dokümantasyon, versioning ve governance kurallarıyla ortak bir modele bağlar. Shadcn/ui bu model için güçlü bir başlangıç noktasıdır çünkü kodun projenin içine alınmasını ve ekip tarafından doğrudan yönetilmesini destekleyen yaklaşımı, şirketin kendi UI mimarisini oluşturmasına alan açar. Bu rehber, paylaştığınız kapsam ve başlık mimarisi esas alınarak hazırlanmış olup design token'lardan private registry yapısına, Figma senkronizasyonundan çok ürünlü organizasyonlarda governance modeline kadar production odaklı bir yol haritası sunar. :contentReference[oaicite:0]{index=0}

Şirket İçi Tasarım Sistemi Nedir?

Şirket içi tasarım sistemi, ürün ekiplerinin kullanıcı arayüzü geliştirirken kullandığı görsel kuralları, component'leri, tasarım kararlarını, erişilebilirlik standartlarını ve kullanım prensiplerini ortak bir sistem altında toplar. Buradaki amaç yalnızca bütün butonların aynı renkte görünmesini sağlamak değildir; tasarım kararlarının kod ve ürün geliştirme süreçleri boyunca tekrar kullanılabilir hale gelmesidir. Sistem güçlü olduğunda tasarımcı yeni ekran hazırlarken mevcut yapı taşlarını bilir, geliştirici aynı davranışı sıfırdan kodlamaz ve ürün yöneticisi farklı ürünlerin ortak deneyim dilini koruyabilir. Design system ayrıca hangi component'in hangi koşulda kullanılacağını, hangi varyantların desteklendiğini ve hangi davranışların şirket standardına aykırı olduğunu açıkça tanımlar. Bu nedenle tasarım sistemi bir Figma dosyasından veya React klasöründen daha geniş, yaşayan bir ürün geliştirme altyapısı olarak ele alınmalıdır.

Tasarım Sistemi ile Component Library Arasındaki Fark

Component library çoğunlukla tekrar kullanılabilir teknik UI parçalarını içerirken tasarım sistemi bu parçaların neden, ne zaman ve hangi kurallarla kullanıldığını da tanımlar. Bir Button component'inin variant, size ve disabled state seçeneklerini sunması component library görevidir, ancak Primary Action'ın hangi ekranlarda kullanılabileceğini açıklamak design system sorumluluğuna girer. Tasarım sistemi ayrıca token yapısı, typography, spacing, accessibility, content guidelines ve contribution süreçleri gibi daha geniş alanları kapsar. Component library güçlü olsa bile ekipler aynı component'i farklı amaçlarla kullanıyor ve görsel kuralları sürekli override ediyorsa gerçek anlamda ortak sistem oluşmamıştır. Bu nedenle şirket içinde sürdürülebilir yapı kurarken component geliştirme kadar kullanım politikalarının, dokümantasyonun ve governance mekanizmasının da birlikte tasarlanması gerekir.

UI Kit ile Design System Arasındaki Fark

UI Kit çoğunlukla Figma veya benzeri tasarım aracında bulunan hazır ekran elemanları ve görsel varyantlardan oluşur. Design system ise UI Kit içindeki kararların koddaki karşılığını, davranış kurallarını, erişilebilirlik gereksinimlerini ve component yaşam döngüsünü de içerir. Bir UI Kit tasarımcıya hızlı başlangıç sağlar, ancak geliştirici karşılığında hangi component'in kullanılacağını bilmiyorsa tasarım ile production arasında zamanla fark oluşur. İyi bir design system Figma component'i ile kod component'i arasında isim, variant ve token düzeyinde mümkün olduğunca açık eşleşme kurar. Bu nedenle şirket yalnızca ortak Figma dosyası oluşturarak sistem kurmuş sayılmaz; tasarım, kod, dokümantasyon ve karar süreçlerinin birlikte yaşaması gerekir.

Bir Şirket Neden Kendi Tasarım Sistemine İhtiyaç Duyar?

Birden fazla ürün veya frontend ekibi bulunan şirketlerde aynı UI problemleri tekrar tekrar çözülmeye başladığında ortak tasarım sistemi ciddi değer üretir. Her ürün kendi modal, form field, data table veya notification çözümünü geliştirirse zaman içinde bakım, test ve erişilebilirlik maliyeti katlanır. Ortak sistem ekiplerin sıfırdan karar vermesi gereken alanları azaltır ve şirketin kullanıcı deneyimini daha öngörülebilir hale getirir. Yeni projeler hazır token, component ve pattern'lerle başlayabildiği için başlangıç süresi de kısalır. Bununla birlikte tasarım sistemi yalnızca merkezi ekibin component yayınladığı depo olarak görülmemeli, ürün ekiplerinin gerçek ihtiyaçlarını karşılayan ve kontrollü katkıya izin veren ortak platform olarak yönetilmelidir.

Tasarım Tutarlılığı

Tasarım tutarlılığı kullanıcının farklı ekranlarda benzer işlemleri benzer şekilde gerçekleştirebilmesini sağlar. Aynı “kaydet” eylemi bir üründe mavi dolu buton, diğerinde gri link ve başka bir ekranda ikon olarak sunuluyorsa kullanıcı her seferinde yeni davranış öğrenmek zorunda kalır. Design system renk, tipografi, spacing, durumlar ve interaction pattern'leri için ortak kurallar belirleyerek bu farklılıkları azaltır. Tutarlılık bütün ekranların birebir aynı görünmesi anlamına gelmez; aynı amaca hizmet eden etkileşimlerin aynı zihinsel modeli taşıması anlamına gelir. Bu yaklaşım hem kullanıcı deneyimini iyileştirir hem de tasarım review sırasında tekrar tekrar temel UI kararlarının tartışılmasını önler.

Daha Hızlı Ürün Geliştirme

Hazır ve güvenilir component'ler ürün ekiplerinin temel UI davranışlarını tekrar geliştirmesini önler. Geliştirici modal focus yönetimi, form error state'i veya keyboard navigation gibi altyapı ayrıntılarını her feature'da yeniden ele almak zorunda kalmaz. Tasarımcı da sıfırdan component çizmek yerine mevcut variant'lar üzerinden ürün akışına odaklanabilir. Bu hız yalnızca ilk geliştirmede değil, design review, QA ve accessibility kontrollerinde de kendini gösterir çünkü ortak parçalar daha önce test edilmiştir. Tasarım sistemi olgunlaştıkça ekiplerin zamanı temel UI üretmekten çok ürüne özgü kullanıcı problemlerini çözmeye kayar.

Tekrarlanan Kodun Azaltılması

Birden fazla uygulamada birbirine benzeyen ancak ayrı ayrı geliştirilmiş component'ler zaman içinde büyük teknik borç oluşturur. Aynı davranışın beş farklı implementasyonu bulunduğunda güvenlik, accessibility veya görsel hata düzeltmesi beş ayrı yerde yapılmak zorunda kalır. Ortak design system standart davranışı tek merkezden veya kontrollü dağıtım mekanizmasından sağlayabilir. Her tekrar mutlaka merkezi component'e dönüşmemelidir çünkü ürün bağlamı farklı olabilir, ancak gerçekten ortaklaşan pattern'ler erken belirlenmelidir. Duplicate component envanterinin düzenli incelenmesi sistemin hangi yeni yapı taşlarına ihtiyaç duyduğunu anlamak için de değerli bir veri kaynağıdır.

Tasarımcı–Geliştirici İşbirliği

Tasarım sistemi tasarımcı ve geliştiricinin aynı component isimleri, token'lar ve state modelleri üzerinden konuşmasını kolaylaştırır. Tasarımcı “small secondary button” dediğinde kod tarafında aynı variant'ın bulunması handoff süresini önemli ölçüde azaltır. Figma ile kod arasındaki isimlerin uyumlu olması yorumlama ihtiyacını düşürür ve yanlış implementasyon riskini azaltır. Geliştirici teknik kısıtları sistem seviyesinde tasarım ekibiyle tartışabilir, tasarımcı da component kullanımının ürün deneyimine etkisini daha erken paylaşabilir. Bu ortak dil tasarım review ve code review süreçlerini birbirinden kopuk kontroller yerine aynı sistemin iki farklı doğrulama noktası haline getirir.

Tasarım Sisteminin Başarısını Belirleyen Unsurlar

Başarılı tasarım sistemi yalnızca component sayısıyla ölçülemez. Kullanım oranı, documentation kalitesi, accessibility seviyesi, ekiplerin contribution deneyimi, Figma ile kod arasındaki uyum ve migration kolaylığı birlikte değerlendirilmelidir. Sistem çok güçlü teknik altyapıya sahip olsa bile ürün ekipleri kullanmakta zorlanıyorsa veya sürekli escape hatch kullanıyorsa adoption düşük kalır. Core team gerçek ürün ihtiyaçlarını dinlemeli ve sistemin hangi noktada gereksiz kural oluşturduğunu düzenli incelemelidir. Başarının önemli göstergelerinden biri, ekiplerin ortak component'i zorunluluktan değil daha güvenli, hızlı ve öngörülebilir olduğu için tercih etmeye başlamasıdır.

Shadcn UI Nedir ve Design System İçin Neden Uygundur?

Shadcn/ui, klasik anlamda yalnızca paket içinden component import edilen bir UI library yaklaşımından farklı olarak component kodunu uygulamanın veya workspace'in içine alıp ekip tarafından sahiplenmeye odaklanan bir model sunar. Bu yaklaşım şirket içi design system kurarken önemli avantaj sağlar çünkü component API'si, styling modeli ve davranışları kurumsal ihtiyaçlara göre doğrudan geliştirilebilir. Resmi dokümantasyon güncel sürümlerde CSS variables tabanlı theming, Tailwind CSS v4 desteği, monorepo CLI desteği ve registry mekanizması gibi design system açısından değerli özellikler sunuyor. :contentReference[oaicite:1]{index=1} Bunun karşılığında şirket upstream güncellemelerini izlemek, kendi fork drift'ini yönetmek ve component kalite standardını korumak gibi daha fazla sorumluluk üstlenir. Bu nedenle Shadcn UI Kullanarak Şirket İçi Tasarım Sistemi Kurmak, hazır component'leri kopyalamaktan çok sahiplik modelini doğru tasarlamakla ilgilidir.

Shadcn/ui Geleneksel Bir Component Library midir?

Shadcn/ui geleneksel “paketi kur, component'i dependency içinden import et ve iç koduna dokunma” modelinden farklı çalışır. Component kaynak kodu projenize eklenir ve uygulamanızın kod tabanının parçası olur. Bu durum design system ekibine API ve styling üzerinde geniş kontrol sağlar. Bununla birlikte merkezi package davranışının otomatik avantajları azalır çünkü daha önce alınmış component kopyaları kendiliğinden upstream ile eşitlenmez. Dolayısıyla Shadcn/ui'ı şirket içinde kullanırken component ownership, versioning ve update politikasını başlangıçta açık biçimde tanımlamak gerekir.

Copy-and-Own-Code Yaklaşımı

Copy-and-own-code yaklaşımında component uygulamaya alındıktan sonra artık şirket kodunun parçası olarak değerlendirilir. Ekip Button, Dialog veya Input üzerinde ihtiyaç duyduğu değişiklikleri doğrudan yapabilir ve üçüncü taraf package API'sinin izin verdiği sınırlarla kısıtlanmaz. Bu özellikle semantic token, kurumsal accessibility standardı veya özel interaction davranışı gerektiğinde güçlü esneklik sağlar. Ancak her ürün ekibi aynı component'i kendi uygulamasında ayrı yönde değiştirirse standardizasyon hızla bozulabilir. Bu nedenle şirket seviyesinde copy-and-own modelini kullanırken “kod bizim” anlayışının yanında “ortak kodun sahibi ve contribution süreci belli” yaklaşımı da kurulmalıdır.

Component Kodunun Şirkete Ait Olmasının Avantajları

Component kodunun şirket repository'sinde bulunması debugging ve customization süreçlerini kolaylaştırır. Geliştirici davranışın neden oluştuğunu dependency source'a gitmeden doğrudan inceleyebilir ve gerekli erişilebilirlik veya business uyarlamasını yapabilir. API'nin şirket ürünlerinin gerçek kullanım biçimine göre şekillendirilmesi daha kolay hale gelir. Gereksiz prop veya style katmanı kaldırılabilir, yeni semantic variant eklenebilir ve test stratejisi kurum standardına bağlanabilir. Bu özgürlük özellikle uzun ömürlü design systemlerde değerlidir, ancak değişikliklerin rastgele değil governance ve review süreci altında yapılması gerekir.

Shadcn/ui'ın Sınırlamaları

Shadcn/ui şirketin bütün design system problemlerini hazır olarak çözmez. Enterprise data table, kapsamlı permission pattern'leri, şirket içi form standardı veya çok markalı token yapısı gibi ihtiyaçları organizasyonun kendisi geliştirmek zorunda kalabilir. Copy model nedeniyle upstream değişikliklerini mevcut özelleştirilmiş component'lere uygulamak otomatik dependency update kadar kolay değildir. Tasarım sistemi dokümantasyonu, Figma eşleşmesi, contribution modeli ve lifecycle yönetimi de doğrudan şirket sorumluluğundadır. Bu nedenle Shadcn/ui güçlü bir temel sunar, fakat “CLI ile component ekledik, design system tamamlandı” yaklaşımı uzun vadede yetersiz kalır.

Shadcn/ui'ın Şirket İçinde Getirdiği Yeni Sorumluluklar

Şirket Shadcn/ui tabanlı sistem kurduğunda component bakımını doğrudan sahiplenir. Upstream değişikliklerinin izlenmesi, security ve accessibility iyileştirmelerinin değerlendirilmesi, internal API stabilitesinin korunması ve migration guide hazırlanması gerekir. Component'lerin kim tarafından değiştirilebildiği ve hangi review'lardan geçmesi gerektiği açık olmalıdır. Private registry veya shared package kullanılıyorsa dağıtım ve versioning süreçleri de platform sorumluluğuna dönüşür. Bu ek sorumluluklar doğru governance ile yönetildiğinde şirketin kendi ürünlerine çok daha iyi uyum sağlayan esnek bir UI altyapısı oluşturmasına imkan verir.

Shadcn UI Tabanlı Tasarım Sisteminin Mimari Katmanları

Ölçeklenebilir design system bütün UI parçalarını tek “components” klasöründe toplamak yerine anlamlı katmanlara ayırmalıdır. Design token'lar en temel görsel kararları taşırken primitive component'ler düşük seviyeli tekrar kullanılabilir davranışları sunar. Semantic component'ler işlevsel anlam ekler, composite component'ler birden fazla parçayı birlikte kullanır, UI pattern ve blocks ise daha geniş kullanıcı akışlarını standartlaştırır. Page template ve product-specific component'ler sistemin ürünle birleştiği üst katmanları oluşturur. Bu ayrım her parçanın merkezi design system'e taşınması gerekip gerekmediğini daha sağlıklı değerlendirmeyi ve bağımlılıkların tek yönde ilerlemesini kolaylaştırır.

Design Tokens

Design token'lar renk, spacing, typography, radius ve shadow gibi tasarım kararlarını isimlendirilmiş veri olarak temsil eder. Component'ler doğrudan rastgele hex renk veya piksel değeri kullanmak yerine bu token'lara dayanır. Böylece marka değişikliği veya dark mode gibi kapsamlı dönüşümler component dosyalarını tek tek değiştirmeden yönetilebilir. Token katmanı tasarım ve kod arasındaki en güçlü ortak sözlüklerden biridir. İyi bir token mimarisi primitive değerler ile semantic anlamı ayırdığı için ürün büyüdükçe yeni tema ve markaların eklenmesini de kolaylaştırır.

Primitive Components

Primitive component'ler Button, Input, Dialog, Checkbox veya Tooltip gibi düşük seviyeli ve birçok ürün alanında tekrar kullanılabilen UI parçalarıdır. Bu katmanda business domain bilgisi mümkün olduğunca bulunmamalıdır. Primitive API erişilebilirlik, interaction ve görsel temel davranışları güvenilir biçimde sunmalıdır. Shadcn/ui component'lerinin önemli bölümü şirket sisteminde bu katmana başlangıç sağlayabilir. Primitive component'ler stabil olduğunda üst katmanlar aynı temel davranışları tekrar uygulamak yerine composition yoluyla kullanabilir.

Semantic Components

Semantic component primitive davranışa şirket içi anlam ekler. Örneğin genel Button yerine PrimaryAction veya DestructiveAction belirli kullanım amacını ifade edebilir. Bu yaklaşım variant seçimini ürün geliştiricisinin kişisel tercihinden çıkarıp şirketin UX standardına bağlayabilir. Ancak her kullanım için ayrı semantic component üretmek API ve component sayısını gereksiz büyütebilir. Semantic katman yalnızca anlamın gerçekten tekrarlandığı ve yanlış kullanımın ürün tutarlılığını bozduğu durumlarda kullanılmalıdır.

Composite Components

Composite component birden fazla primitive veya semantic component'i anlamlı kullanıcı senaryosunda bir araya getirir. SearchForm, FilterPanel veya UserCard buna örnek olabilir. Bu parçalar ürün ekiplerinin sürekli tekrar ettiği düzen ve interaction kodunu azaltır. Composite component yeterince genel değilse bütün ürün ihtiyaçlarını karşılamak için aşırı prop almaya başlayabilir. Bu nedenle design system'e eklenmeden önce en az birkaç gerçek kullanım senaryosunda ortak davranış gösterdiğinin doğrulanması önemlidir.

UI Patterns

UI Pattern tek component yerine kullanıcı problemini çözme yöntemini tanımlar. Form validation, destructive confirmation, pagination veya bulk selection gibi davranışlar birden fazla component'i kapsayabilir. Pattern dokümantasyonu hangi component'lerin birlikte kullanılacağını ve edge case'lerde nasıl davranılması gerektiğini açıklar. Böylece ürün ekipleri yalnızca görsel parçaları değil deneyim standardını da tekrar kullanır. Pattern'lerin Storybook veya design guideline sayfalarında canlı örneklerle gösterilmesi adoption açısından oldukça faydalıdır.

Blocks

Blocks daha geniş hazır UI bölümleridir ve genellikle birçok component'i bir kullanıcı ihtiyacı etrafında birleştirir. Kullanıcı yönetim tablosu, ayarlar paneli veya login bölümü örnek olabilir. Shadcn registry yapısı block türlerini dağıtmak için de kullanılabilir ve registry item şeması component, block, theme ve farklı dosya tiplerini ayrı türlerle tanımlamaya izin verir. :contentReference[oaicite:2]{index=2} Şirket içinde block kullanımı yeni projeleri hızlandırabilir, ancak block'ların ürün seviyesindeki business logic'i aşırı sahiplenmemesi gerekir. En iyi block'lar başlangıç şablonu sağlayıp ürünün kendi gereksinimine kontrollü uyarlama alanı bırakır.

Page Templates

Page Template bir sayfanın genel yerleşim ve yapısal pattern'ini tanımlar. Dashboard, settings, authentication veya CRUD yönetim sayfaları için template oluşturulabilir. Template ürün ekiplerine ilk ekran geliştirmesinde güçlü hız kazandırır ve responsive davranışların ortak uygulanmasını sağlar. Buna rağmen her ürün ekranının aynı layout'a zorlanması kullanıcı ihtiyacını sınırlayabilir. Template'ler katı sayfa üreticisi yerine iyi başlangıç noktası ve önerilen düzen olarak ele alındığında daha sağlıklı sonuç verir.

Product-Specific Components

Product-specific component yalnızca belirli ürün veya domain içinde anlam taşıyan UI parçasıdır. Örneğin belirli finans sürecine özgü PricingRuleEditor bütün şirket ürünlerinde tekrar kullanılmayabilir. Böyle parçaları merkezi design system'e taşımak sistemin domain bağımlılığını artırır. Ürün repository'sinde kalması, ancak temel primitive ve token'ları ortak sistemden kullanması daha doğru olabilir. Zaman içinde başka ürünlerde de aynı ihtiyaç ortaya çıkarsa component'in daha genel hale getirilerek design system'e taşınması yeniden değerlendirilebilir.

Hangi Katmanın Design System'e Ait Olduğunu Belirlemek

Bir component'in design system'e ait olup olmadığını anlamak için tekrar kullanım, domain bağımsızlığı, davranış standardı ve sahiplik kriterleri birlikte değerlendirilebilir. En az iki veya üç ürünün aynı problemi benzer şekilde çözmesi güçlü aday göstergesidir. Yalnızca tek ekibin ihtiyacını karşılayan ve sürekli ürün kuralı değişen component merkezi sisteme taşınmamalıdır. Design system ekibi “merkezi yapmak” yerine “ortaklaştırıldığında gerçekten bakım maliyeti azalacak mı?” sorusunu sormalıdır. Bu yaklaşım sistemin gereksiz büyümesini ve core team'in bütün ürün UI'larının darboğazı haline gelmesini önler.

Design Token Mimarisi Nasıl Kurulmalı?

Design token mimarisi şirket tasarım sisteminin görsel kararlarını component kodundan ayıran temel katmandır. Primitive token'lar ham değerleri, semantic token'lar kullanım anlamını, component-level token'lar ise gerektiğinde belirli component davranışını temsil eder. Örneğin doğrudan blue-600 kullanmak yerine primary veya action-background gibi semantic isimler tercih edildiğinde marka veya tema değişikliği daha kolay yönetilir. Token isimleri görsel görünümden çok amaç ifade ettiğinde sistem uzun vadede daha esnek olur. Tasarım ve kod tarafının aynı token sözlüğünü kullanması Figma ile production arasındaki farkı azaltan en önemli mimari kararlardan biridir.

Design Token Nedir?

Design token renk, font, spacing veya benzeri tasarım kararını isimlendirilmiş bir değer olarak saklar. Token'ın amacı aynı değerin farklı dosyalarda kopyalanmasını önlemek ve tasarım kararına ortak referans vermektir. Örneğin border radius değeri değiştiğinde onlarca component'i manuel düzenlemek yerine ilgili token güncellenebilir. Token tasarım sistemi için API gibi düşünülebilir çünkü component'ler doğrudan ham tasarım değeri yerine bu sözleşmeyi kullanır. İyi token sistemi theme switching, multi-brand ve design audit çalışmalarını önemli ölçüde kolaylaştırır.

Primitive Tokens

Primitive token'lar tasarım sistemindeki ham ölçekleri temsil eder. Color palette, spacing scale, font size, radius ve shadow seviyeleri bu katmanda bulunabilir. İsimler genellikle görsel veya ölçek odaklı olabilir, örneğin color-blue-500 veya space-4 gibi. Primitive token'ların doğrudan product component'lerde yoğun kullanılması semantic esnekliği azaltabilir. En sağlıklı modelde primitive token semantic katmanın girdisi olur ve uygulama component'leri mümkün olduğunca anlam temelli semantic token kullanır.

Color

Color primitive token'ları marka ve nötr renklerin ton ölçeğini içerir. Örneğin neutral-50 ile neutral-950 arasında değerler veya brand palette seviyeleri tanımlanabilir. Bu değerler doğrudan “başarılı işlem” veya “ana aksiyon” anlamı taşımaz. Semantic token'lar daha sonra bu palette içinden uygun değeri seçer. Böylece dark mode veya farklı marka geldiğinde semantic anlam korunurken primitive eşleştirme değiştirilebilir.

Spacing

Spacing token'ları padding, gap ve margin kararlarında kullanılan ortak ölçeği oluşturur. Rastgele 13px, 19px veya 27px değerlerinin ürün boyunca yayılmasını önler. Küçük, orta ve büyük aralıkların belirli matematiksel veya görsel ritme dayanması UI tutarlılığını artırır. Component'ler mümkün olduğunca bu ölçek içinden değer kullanmalıdır. Gerektiğinde özel layout ihtiyacı olabilir, ancak istisna standart davranış haline gelmemelidir.

Typography

Typography token'ları font family, size, weight, line-height ve letter spacing kararlarını tanımlar. Yalnızca font büyüklüğü yerine heading, body ve label gibi semantic typography stilleri de ayrıca oluşturulabilir. Farklı ürün ekiplerinin aynı büyüklükte farklı line-height kullanması bu yapı sayesinde önlenir. Responsive typography gerekiyorsa ölçek ve breakpoint davranışı ortak tasarlanabilir. Figma text styles veya variables ile kod token'larının aynı isim yapısını kullanması handoff sürecini kolaylaştırır.

Radius

Radius token'ları card, input, modal ve button gibi yüzeylerin köşe yuvarlaklığını ortaklaştırır. Her component'in kendi bağımsız radius değerini seçmesi markanın görsel karakterini parçalayabilir. Küçük, orta ve büyük radius ölçeği tasarım dilinin kontrollü gelişmesini sağlar. Shadcn/ui theming yaklaşımı radius değerlerinin CSS variable üzerinden yönetilmesini destekler. :contentReference[oaicite:3]{index=3} Marka farklılaşması gerektiğinde aynı component kodu korunup yalnızca token katmanı değiştirilebilir.

Shadow

Shadow token'ları yüzeylerin elevation ve vurgu seviyelerini belirler. Rastgele box-shadow değerleri yerine birkaç anlamlı seviye kullanılması arayüzün daha düzenli görünmesini sağlar. Modal, dropdown ve card için aynı shadow kullanılması gerekmeyebilir, ancak ölçek kontrollü olmalıdır. Dark theme içinde shadow davranışı light theme'den farklılaşabilir. Token katmanı bu değişimi component dosyalarına yaymadan yönetmeye yardımcı olur.

Semantic Tokens

Semantic token'lar ham değerden çok kullanım amacını ifade eder. Background, foreground, primary, muted veya destructive gibi isimler component'in “hangi renk?” sorusundan çok “hangi rol?” sorusuna cevap verir. Shadcn/ui resmi theming yaklaşımı da CSS variables üzerinden background, foreground ve primary gibi semantic theme token'ları kullanmayı önerir. :contentReference[oaicite:4]{index=4} Bu model light, dark ve multi-brand theme geliştirmeyi kolaylaştırır. Component kodu semantic token'a bağlı kaldığı sürece görsel değerler merkezi olarak değiştirilebilir.

Background

Background token uygulamanın veya belirli yüzeylerin temel arka plan rengini temsil eder. Doğrudan white kullanmak yerine background token tercih edildiğinde dark mode aynı component koduyla çalışabilir. Alt yüzeyler için surface veya elevated-background gibi ek semantic seviyeler gerekebilir. Token sayısı gerçek tasarım ihtiyacına göre sınırlı tutulmalıdır. Her yeni renk farkını ayrı semantic isim haline getirmek sistemin kullanımını zorlaştırabilir.

Foreground

Foreground çoğunlukla background üzerinde kullanılan temel metin veya ikon rengini ifade eder. Semantic eşleşme contrast kontrolünü daha kolay hale getirir. Dark mode geçişinde foreground değeri theme tarafından değiştirilebilir. Muted veya disabled içerikler için farklı semantic foreground token'ları tanımlanabilir. Erişilebilirlik kontrolü token çiftleri üzerinde yapılırsa birçok component aynı anda güvenli hale gelir.

Primary

Primary token markanın veya ürünün ana aksiyon rengini temsil edebilir. Bunun doğrudan şirket logosundaki ana renkle aynı olması şart değildir; UI interaction gereksinimleri ve contrast koşulları değerlendirilmelidir. Primary foreground token'ı da birlikte tanımlanarak metin okunabilirliği korunabilir. Multi-brand sistemde primary her marka için farklı değere eşlenebilir. Component kodu aynı semantic isimle çalışmaya devam eder.

Secondary

Secondary token ana aksiyona göre daha düşük vurgu gerektiren yüzey veya action'larda kullanılabilir. Tasarım sistemi secondary kullanımının primary ile farkını dokümante etmelidir. Her ekranın primary ve secondary butonlarla dolması görsel hiyerarşiyi zayıflatabilir. Semantic token yalnızca renk değil kullanım anlamıyla birlikte ele alınmalıdır. Storybook ve Figma örnekleri doğru kullanımın anlaşılmasını kolaylaştırır.

Muted

Muted token düşük vurgu gerektiren arka plan, açıklama veya yardımcı içeriklerde kullanılabilir. Contrast seviyesi erişilebilirlik açısından kontrol edilmelidir çünkü düşük vurgu okunamaz metin anlamına gelmemelidir. Muted background ve muted foreground ayrı token'lar olarak tasarlanabilir. Tema değiştiğinde iki değer birlikte optimize edilebilir. Bu yaklaşım component geliştiricinin her seferinde rastgele gri ton seçmesini önler.

Destructive

Destructive token silme, iptal etme veya geri döndürülemez riskli aksiyonları vurgulamak için kullanılabilir. Rengin tek başına anlam taşımasına güvenilmemeli, ikon, metin ve confirmation pattern'i gibi ek sinyaller kullanılmalıdır. Destructive foreground değerinin yeterli contrast üretmesi gerekir. Aynı token alert, button ve status component'lerinde kontrollü şekilde kullanılabilir. Kullanım guideline'ı bulunması kırmızı rengin gereksiz her hata veya vurgu için kullanılmasını önler.

Border

Border token input, card, separator ve diğer yüzey sınırlarının ortak rengini belirler. Light ve dark theme içinde aynı ham renk kullanılması çoğu zaman doğru sonuç vermez. Semantic token tema başına farklı değere eşlenebilir. Focus ring veya interactive border için ayrı token gerekebilir. Border sistemi typography ve spacing kadar görünür olmasa da ürün tutarlılığında önemli rol oynar.

Component-Level Tokens

Component-level token belirli component için semantic sistemin yeterli olmadığı özel tasarım kararlarını temsil eder. Örneğin data-table-row-hover veya button-primary-shadow gibi isimler kullanılabilir. Bu katman çok erken oluşturulursa her component kendi token dünyasına sahip olur ve sistem ağırlaşır. Önce genel semantic token'larla çözüm aranmalı, tekrar eden gerçek ihtiyaç oluştuğunda component seviyesine inilmelidir. Component-level token'lar özellikle multi-brand sistemde belirli component'in marka başına farklı davranması gerektiğinde yararlı olabilir.

Primitive Token ile Semantic Token Arasındaki Fark

Primitive token değerin ne olduğunu, semantic token ise neden kullanıldığını ifade eder. Color-blue-600 primitive iken action-primary-background semantic bir isimdir. Bir marka değişikliğinde action-primary-background artık başka primitive değere bağlanabilir ve component kodu değişmez. Bu ayrım design system'i görsel palette bağımlı olmaktan çıkarır. Uzun vadeli theming ve multi-brand planı bulunan şirketlerde bu katmanlama özellikle önemlidir.

Hardcoded Renklerden Neden Kaçınılmalı?

Hardcoded renkler component'i belirli tema veya marka değerine doğrudan bağlar. Kod içinde yüzlerce hex değeri yayıldığında dark mode veya rebranding çalışması büyük migration projesine dönüşebilir. Semantic token kullanımı aynı değişikliği merkezi hale getirir. Hardcoded değerler ayrıca accessibility audit sırasında hangi renk çiftlerinin gerçekten kullanıldığını anlamayı zorlaştırır. Lint kuralları ve code review checklist'i yeni hardcoded renklerin sisteme girmesini azaltmak için kullanılabilir.

Token Naming Convention Oluşturmak

Token isimlendirme standardı sistemin anlaşılabilirliği açısından değerin kendisi kadar önemlidir. İsimler mümkün olduğunca kullanım rolünü ifade etmeli ve tasarım ile kod tarafında aynı mantığı taşımalıdır. Örneğin semantic token isimleri color-blue yerine action-primary veya surface-muted şeklinde kurulabilir. Naming convention yeni token öneri sürecinde de referans olarak kullanılmalıdır. İyi isimler design token'ı yalnızca teknik değişken olmaktan çıkarıp ekipler arası ortak tasarım dili haline getirir.

Tailwind CSS ile Design Token Entegrasyonu

Tailwind CSS v4 design token mimarisini utility class üretimiyle doğrudan ilişkilendirebilen theme variable yapısı sunar. Resmi dokümantasyona göre @theme içinde tanımlanan theme variables ilgili utility class'ların oluşmasını sağlar ve shared CSS dosyaları üzerinden projeler arasında paylaşılabilir. :contentReference[oaicite:5]{index=5} Shadcn/ui da Tailwind v4 ile @theme ve @theme inline desteğini kullanıyor ve CSS variable temelli theming modelini sürdürüyor. :contentReference[oaicite:6]{index=6} Şirket açısından önemli nokta Tailwind'i serbest styling alanı olarak değil, design token API'sini tüketen uygulama katmanı olarak konumlandırmaktır. Bu yaklaşım arbitrary value ve hardcoded renk kullanımını azaltırken design system sınırlarının lint ve CI ile denetlenmesini mümkün kılar.

CSS Variables Kullanımı

CSS variables theme ve runtime değişimleri için esnek temel sağlar. Semantic token'lar --background, --foreground veya şirket isimlendirmesine uygun değişkenler halinde tutulabilir. Component class'ları doğrudan bu semantic değerlerle eşlenen utility'leri kullanabilir. Shadcn/ui resmi theming dokümantasyonu CSS variables kullanımını öneriyor ve semantic utility örneklerini bu model üzerinden gösteriyor. :contentReference[oaicite:7]{index=7} Multi-brand veya tenant bazlı tema gerektiğinde root veya scope seviyesinde variable değerleri değiştirilerek component kodu korunabilir.

Tailwind CSS v4 Theme Yapısı

Tailwind CSS v4 @theme direktifiyle design token'ların utility API'sine bağlanmasını sağlar. Örneğin --color-*, --font-* veya --shadow-* namespace'leri ilgili utility class'ların üretilmesini etkiler. :contentReference[oaicite:8]{index=8} Şirket ortak token dosyasını ayrı package veya shared CSS olarak sağlayabilir ve birden fazla uygulama bunu import edebilir. Bu model token paylaşımını JavaScript configuration bağımlılığından daha doğrudan CSS tabanlı yapıya taşıyabilir. Ancak hangi token'ın Tailwind utility oluşturacağı ve hangisinin yalnızca normal CSS variable olarak kalacağı bilinçli şekilde belirlenmelidir.

Semantic Utility Class'lar

Semantic utility class'lar bg-background, text-foreground veya border-border gibi kullanım amacını ifade eder. Shadcn/ui resmi theming yaklaşımında bu tür semantic token eşleşmeleri varsayılan modelin temel parçalarındandır. :contentReference[oaicite:9]{index=9} Şirket kendi semantic token sözlüğünü genişleterek bg-surface-critical veya text-content-muted gibi daha kurumsal isimler oluşturabilir. Bu class'lar raw palette kullanımını azaltır ve dark mode davranışını component'ten ayırır. İsimlerin tasarım ekibindeki token adlarıyla mümkün olduğunca eşleşmesi Figma ile kod arasındaki iletişimi de kolaylaştırır.

Arbitrary Value Kullanımını Sınırlamak

Tailwind arbitrary value özelliği gerekli özel durumlarda yararlıdır, ancak design system içinde kontrolsüz kullanıldığında token standardını kolayca aşındırır. w-[317px] veya rastgele renk değerleri ürün ekiplerinin ortak ölçek dışına çıkmasına neden olabilir. Tamamen yasaklamak bazı gerçek layout ihtiyaçlarını zorlaştırabilir, bu nedenle kullanım politikası belirlemek daha sağlıklıdır. Design system component'lerinde arbitrary value çok daha sıkı sınırlandırılabilir, product-level layout'ta belirli istisnalar kabul edilebilir. Lint uyarısı veya PR checklist ile bu kullanım görünür hale getirilebilir.

Design System Dışına Çıkılmasını ESLint ile Engellemek

ESLint veya özel static analysis kuralları design system standardının yalnızca dokümanda kalmasını önleyebilir. Hardcoded hex renk, yasak import yolu, raw Button kullanımı veya belirli HTML elementlerinin doğrudan kullanılması kontrol edilebilir. İlk aşamada bütün ihlalleri error yapmak yerine warning ile adoption ölçmek daha sağlıklı olabilir. Legacy uygulamalarda yeni ihlalleri engelleyip eski kodu kademeli temizlemek migration sürecini kolaylaştırır. Lint kuralının amacı geliştiriciyi cezalandırmak değil, yanlış kullanımı code review'a gelmeden önce hızlı geri bildirimle yakalamaktır.

Şirket Markasını Shadcn UI'a Nasıl Uyarlayabiliriz?

Shadcn/ui'ı şirket içinde kullanırken varsayılan görünümü yalnızca logo ve primary renk değişikliğiyle bırakmak güçlü marka sistemi oluşturmaz. Brand color, typography, radius, shadow, spacing, iconography ve motion kararları birlikte ele alınmalıdır. Semantic token yapısı bu kararların component implementation'dan ayrılmasını sağlar ve Shadcn/ui'ın varsayılan component davranışları korunurken görsel kimlik şirket standardına uyarlanabilir. Resmi theming modeli CSS variables üzerinden renk, radius, font ve benzeri token'ların değiştirilmesini destekliyor. :contentReference[oaicite:10]{index=10} Amaç Shadcn görünümünü gizlemek değil, hazır altyapıyı şirketin kendi tasarım diline hizmet eden teknik temel haline getirmektir.

Brand Color Sistemi

Brand color sistemi logo renginden daha geniş düşünülmelidir. Primary, accent, interactive, neutral, success, warning ve destructive rolleri ayrı semantic anlamlara sahip olabilir. Marka palette'i önce primitive tonlara, ardından semantic token'lara bağlanmalıdır. Contrast gereksinimleri nedeniyle pazarlama materyalindeki ana renk UI action için birebir uygun olmayabilir. Farklı theme ve state'lerde test edilmiş semantic renk sistemi, component'lerin marka kimliğini korurken erişilebilir kalmasını sağlar.

Typography

Typography şirketin görsel karakterini en güçlü taşıyan katmanlardan biridir. Font family kadar heading scale, body size, line-height ve weight kullanımı da standartlaştırılmalıdır. Dashboard gibi veri yoğun ürünlerde pazarlama sitesinden farklı density gerekebilir, ancak temel token sistemi ortak kalabilir. Typography token'ları responsive davranış ve dil farklılıklarını kaldırabilecek esneklikte tasarlanmalıdır. Kod ve Figma aynı typography isimlerini kullandığında tasarım handoff daha net hale gelir.

Border Radius

Border radius marka hissini etkileyen ancak kolayca kontrolsüzleşebilen ayrıntıdır. Bir ürün tamamen yuvarlak, diğer ürün keskin köşeler kullanıyorsa aynı şirket deneyimi zayıflayabilir. Küçük, orta ve büyük radius ölçeği belirlenerek Button, Input, Card ve Dialog için kullanım kuralları tanımlanabilir. Semantic veya component seviyesinde gerekli eşlemeler yapılabilir. Multi-brand yapı planlanıyorsa radius token'larının marka katmanından override edilebilmesi gelecekte önemli avantaj sağlar.

Shadow Sistemi

Shadow sistemi elevation ve interactive hierarchy'yi desteklemelidir. Her geliştiricinin farklı box-shadow üretmesi yerine birkaç kontrollü token kullanılması tasarım tutarlılığını artırır. Dropdown, modal ve floating panel gibi yüzeylerin farklı elevation seviyeleri olabilir. Dark mode içinde shadow tek başına yeterli görünmeyebilir ve border veya background contrast ile desteklenebilir. Bu nedenle shadow token'ları theme regression testlerine dahil edilmelidir.

Spacing Sistemi

Spacing sistemi ürünün density ve görsel ritmini belirler. Form alanları, card iç boşlukları ve section aralıkları ortak ölçek üzerinden tanımlanmalıdır. Enterprise uygulamalarda compact ve comfortable density seçenekleri gerekebilir. Böyle durumda her component'e rastgele spacing prop eklemek yerine density token veya context yaklaşımı değerlendirilebilir. Tasarımcı ve geliştirici aynı spacing scale'i kullandığında ekran implementasyonunda küçük ancak sürekli farklar önemli ölçüde azalır.

Iconography

Iconography çizgi kalınlığı, boyut, optik hizalama ve semantic kullanım açısından ortak standarda sahip olmalıdır. Aynı anlam için farklı ikonların kullanılması kullanıcı deneyimini zayıflatabilir. Design system desteklenen icon set ve size token'larını belirleyebilir. Icon-only button'larda accessible name zorunluluğu ayrıca tanımlanmalıdır. Marka özel ikonları varsa bunların general-purpose icon set ile birlikte nasıl dağıtılacağı ve versionlanacağı açık olmalıdır.

Motion ve Animation

Motion kullanıcıya durum değişikliği, hierarchy ve feedback anlatmak için kullanılmalıdır. Her component'in farklı duration veya easing seçmesi ürünün parçalı hissettirmesine neden olur. Duration, easing ve transition pattern'leri token veya guideline olarak tanımlanabilir. Reduced motion tercihi sistem seviyesinde desteklenmelidir. Animation dekorasyon amacıyla aşırı kullanılmak yerine kullanıcı deneyimini açıklayan kontrollü davranış olarak ele alınmalıdır.

Default Shadcn Görünümünden Uzaklaşmak

Shadcn/ui güçlü başlangıç sağladığı için birçok proje varsayılan örnek görünümüne yakın kalabilir. Şirket tasarım sistemi kurarken bu durum marka farklılaşmasını sınırlayabilir. Token, typography, iconography, spacing ve component composition kararları birlikte değiştirilmelidir. Ancak farklılaşmak uğruna erişilebilir interaction davranışlarını veya faydalı primitive yapıları yeniden yazmak gereksizdir. Amaç yüzeyde özgün, altyapıda tutarlı ve bakımı kolay şirket standardı oluşturmaktır.

Dark Mode ve Tema Yönetimi

Dark mode yalnızca renklerin tersine çevrilmesi değildir; semantic token ilişkilerinin farklı ışık koşullarında yeniden dengelenmesidir. Background, foreground, border, muted ve interactive state'lerin her theme içinde yeterli contrast ve hierarchy sağlaması gerekir. Shadcn/ui CSS variables temelli semantic token modeli dark theme yönetimini doğrudan destekler ve mevcut component'lerin semantic class'lar üzerinden aynı API ile çalışmasını sağlar. :contentReference[oaicite:11]{index=11} Theme switching, system preference, high contrast ve visual regression testleri daha başlangıçta design system planına dahil edilmelidir. Tema desteği sonradan eklenen ürün özelliği yerine token mimarisinin doğal sonucu olduğunda bakım maliyeti önemli ölçüde azalır.

Semantic Token'larla Dark Mode

Dark mode için component içinde sürekli dark: renk override'ı yazmak yerine semantic token değerlerinin tema seviyesinde değişmesi daha ölçeklenebilir yaklaşımdır. Button aynı bg-primary class'ını kullanır, ancak primary token dark theme altında farklı değere bağlanır. Bu yöntem component code duplication'ını azaltır. İstisnai görsel davranış gerektiğinde theme-specific rule kullanılabilir. Ancak ana model semantic token üzerinden çalıştığında çok sayıda component'in theme desteği merkezi biçimde kontrol edilebilir.

Light ve Dark Theme Arasında Component Tutarlılığı

Component'in light ve dark theme'de aynı davranış ve hierarchy'yi koruması gerekir. Primary action her iki temada da en yüksek görsel önceliğe sahip olmalıdır. Border ve shadow gibi yüzey ayırıcıları dark mode içinde farklı tekniklerle desteklenebilir. Interactive hover, focus ve disabled state'ler ayrı ayrı kontrol edilmelidir. Storybook theme stories ve visual regression testleri bu tutarlılığı sistematik biçimde doğrulamaya yardımcı olur.

High Contrast Theme

High contrast theme yalnızca renkleri daha parlak yapmak değildir. Border, focus indicator ve text contrast gibi öğelerin daha belirgin hale gelmesi gerekebilir. Semantic token katmanı yeni theme eklemeyi component değişikliğinden ayırdığı için burada önemli avantaj sağlar. High contrast kullanıcı tercihi veya kurumsal accessibility ihtiyacı olarak değerlendirilebilir. Theme testleri keyboard ve screen reader davranışlarıyla birlikte yürütüldüğünde daha bütünlüklü erişilebilirlik standardı oluşur.

Sistem Temasını Takip Etmek

Kullanıcının işletim sistemi light veya dark tercihini takip etmek iyi varsayılan deneyim olabilir. Bunun için sistem media query'si ile başlangıç theme'i seçilebilir. Kullanıcı manuel seçim yaptığında bu tercih sistem değerinin önüne geçebilir. Server rendering kullanılan uygulamalarda ilk render ile client theme uyuşmazlığına dikkat edilmelidir. Design system dokümantasyonu ürün ekiplerine önerilen theme initialization yöntemini hazır pattern olarak sunmalıdır.

Theme Switching

Theme switching kullanıcı seçimiyle light, dark veya farklı brand theme'leri arasında geçiş yapılmasını sağlar. Runtime değişimde component'lerin yeniden mount edilmesine gerek kalmadan CSS variable değerleri değiştirilebilir. Seçim local storage, kullanıcı profili veya tenant ayarı üzerinden saklanabilir. Theme değiştirici component de design system'in ortak parçası olabilir. Ancak ürünün gerçekten theme seçim ihtiyacı yoksa gereksiz kullanıcı ayarı eklemek yerine sistem tercihini takip etmek daha sade olabilir.

Theme Regression Testleri

Yeni token veya component değişikliği yalnızca light theme'de kontrol edilirse dark mode hataları production'a kolayca taşınabilir. Visual regression suite her önemli story'yi light ve dark varyantlarda render edebilir. High contrast veya marka theme'leri kritikse bunlar da test matrisi içine eklenebilir. Contrast ve focus state gibi alanlar otomatik accessibility testleriyle desteklenmelidir. Böylece theme desteği manuel hatırlanması gereken görev olmaktan çıkar ve CI standardına dönüşür.

Multi-Brand Tasarım Sistemi Nasıl Kurulur?

Multi-brand design system aynı component davranışını farklı marka kimlikleriyle sunmayı hedefler. En önemli prensip component logic ile marka görünümünü birbirinden ayırmaktır. Semantic token katmanı renk, typography, radius ve shadow değerlerini marka bazında değiştirmeyi mümkün kılar. Component API'si her marka için ayrı fork edilirse kısa sürede bakım maliyeti yükselir ve özellik eşitliği bozulur. Bu nedenle tek component, brand-specific token ve gerektiğinde sınırlı theme override yaklaşımı white-label ve çok markalı kurumsal ürünlerde daha sürdürülebilir sonuç verir.

Tek Component, Birden Fazla Marka

Tek Button component'inin farklı markalarda ayrı renk, radius veya typography ile görünmesi ideal multi-brand modelidir. Interaction, accessibility ve API aynı kalır. Marka farkları token katmanında uygulanır. Gerçekten farklı UX davranışı gereken markalarda sınırlı component override düşünülebilir. Ancak her görsel farkın yeni component fork'una dönüşmesi merkezi sistemin faydasını ortadan kaldırır.

Brand-Specific Token Katmanı

Brand-specific token katmanı ortak semantic isimleri marka değerleriyle eşler. Örneğin primary token marka A'da farklı, marka B'de farklı primitive palette'e bağlanabilir. Component her iki durumda da primary kullanır. Typography ve radius gibi yalnızca renk dışındaki kararlar da aynı katmanda override edilebilir. Bu model yeni marka eklemeyi yeni component seti geliştirmekten çok yeni theme configuration hazırlamaya yaklaştırır.

White-Label Ürünlerde Shadcn/ui

White-label ürün aynı application logic'i farklı müşteri veya marka görünümüyle sunar. Shadcn/ui'ın code ownership yaklaşımı burada şirketin component API'sini tamamen kontrol etmesine imkan verir. CSS variable ve semantic token yapısı runtime theme farklılıklarını yönetebilir. Tenant özel requirementlar token sınırını aşarsa ürün-level extension mekanizması tanımlanmalıdır. Böylece core component'ler her müşteri için ayrı fork edilmeden white-label esnekliği korunabilir.

Tenant Bazlı Theme

Tenant bazlı theme kullanıcı hangi kuruma aitse ilgili marka token'larının uygulanmasını sağlar. Theme config backend veya deployment configuration üzerinden belirlenebilir. Kritik nokta tenant verisinin güvenli şekilde çözülmesi ve theme'in yalnızca görsel katmana etki etmesidir. Her tenant için ayrı CSS bundle üretmek veya runtime variable değiştirmek arasında ölçek ve performans değerlendirmesi yapılabilir. Design system her iki yöntemde de aynı semantic API'yi korumalıdır.

Runtime Theme Switching

Runtime theme switching sayfa yeniden build edilmeden marka veya theme değerlerinin değişmesini sağlar. CSS custom properties bu model için doğal araçtır. Kullanıcı tenant değiştirdiğinde veya preview ekranında farklı marka görüntülendiğinde theme root seviyesinde güncellenebilir. Font ve icon asset gibi yalnızca variable ile değişmeyen kaynaklar ayrıca yönetilmelidir. Theme switching sırasında flash ve hydration sorunları test edilmelidir.

Marka Bazlı Figma Library Yönetimi

Figma tarafında her marka için tamamen ayrı component library oluşturmak kısa vadede kolay, uzun vadede drift riski yüksek olabilir. Ortak component structure ve brand variable collection yaklaşımı daha sürdürülebilir olabilir. Designer seçili marka mode'una göre aynı component'in farklı token değerlerini görebilir. Kod token isimleriyle Figma variable isimlerinin eşleşmesi handoff'u güçlendirir. Marka özel component gerçekten gerekiyorsa bunun neden ortak sistemden ayrıldığı dokumente edilmelidir.

Shadcn UI Component'leri Nasıl Özelleştirilmeli?

Shadcn/ui component'leri şirket sistemine alınırken en kritik karar doğrudan kod değişikliği, wrapper veya yeni semantic component seçeneklerinden hangisinin kullanılacağıdır. Copy-and-own modeli doğrudan değişikliğe izin verir, ancak her fark için base component'i değiştirmek upstream karşılaştırmasını zorlaştırabilir. Öte yandan bütün değişiklikleri wrapper katmanına taşımak gereksiz abstraction ve prop forwarding yükü oluşturabilir. İyi strateji şirketin kalıcı standardı olan davranışları base component'e, domain veya kullanım anlamı ekleyen davranışları composition veya semantic component'e yerleştirir. Variant ve escape hatch politikalarının açık olması ürün ekiplerinin component'i kontrollü biçimde genişletmesini sağlar.

Doğrudan Değiştirmek mi Wrapper Kullanmak mı?

Şirketin bütün uygulamalarında geçerli olacak accessibility, token veya temel interaction değişikliği base component'e doğrudan uygulanabilir. Yalnızca belirli kullanım bağlamına ait davranış wrapper veya composite component'e taşınabilir. Her değişiklikte wrapper kullanmak DOM ve API katmanlarını gereksiz büyütebilir. Her değişikliği base içine almak da component'i bütün ürün ihtiyaçlarını taşımaya zorlar. Karar verirken değişikliğin kullanım alanı, stabilitesi ve upstream update etkisi birlikte değerlendirilmelidir.

Base Component ile Company Component Ayrımı

Base component düşük seviyeli teknik primitive'i temsil ederken Company Component kurumsal semantic veya UX kuralını ekleyebilir. Örneğin base Button temel variant'ları sağlar, ConfirmDeleteAction ise şirketin destructive confirmation standardını uygular. Bu ayrım bütün component'lerde zorunlu değildir. Yalnızca gerçekten anlamlı semantic katman bulunduğunda kullanılması API'nin anlaşılır kalmasını sağlar. Dokümantasyon hangi seviyenin product ekiplerine doğrudan açık olduğunu belirtmelidir.

Composition Over Inheritance

React dünyasında component davranışlarını inheritance yerine composition ile birleştirmek daha esnek yapı sağlar. Card içine özel header, footer veya action slot'ları composition yoluyla geçirilebilir. Çok sayıda boolean prop ile her olası kombinasyonu base component içinde yönetmeye çalışmak API'yi hızla büyütür. Compound component veya slot pattern bazı karmaşık parçalar için iyi seçenek olabilir. Design system ekibi composition yaklaşımını örneklerle dokümante ederek ürün geliştiricilerinin doğru extension modelini kullanmasını sağlayabilir.

className Escape Hatch Politikası

className prop component'in ürün bağlamında layout veya küçük görsel uyarlama yapmasını kolaylaştırır. Tamamen kapatmak gerçek kullanım ihtiyaçlarında gereksiz wrapper oluşmasına yol açabilir. Ancak renk, radius ve typography gibi design system kararlarının sürekli className ile override edilmesi standardı etkisiz hale getirir. Dokümantasyon hangi sınıfların güvenli escape hatch olarak kabul edildiğini açıklayabilir. Lint veya review süreci özellikle design token dışına çıkan override'ları görünür hale getirebilir.

Variant Yönetimi

Variant sistemi component'in desteklenen görsel ve semantic durumlarını açık API'ye dönüştürür. Primary, secondary veya destructive gibi anlamlı varyantlar tasarım sisteminin kullanım dilini güçlendirir. Variant sayısı arttıkça kombinasyonların test maliyeti de yükselir. Her yeni variant gerçek tekrar eden kullanım üzerinden gerekçelendirilmelidir. Variant isimleri Figma properties ile eşleştirildiğinde designer ve developer aynı seçenek kümesini kullanabilir.

Class Variance Authority

Class Variance Authority benzeri yaklaşım Tailwind class kombinasyonlarını variant API'si altında düzenlemek için kullanılabilir. Component'in variant, size ve state sınıfları merkezi tanımda tutulur. Bu yapı type-safe prop üretimiyle TypeScript kullanımını da güçlendirebilir. Ancak çok büyük variant matrisi oluşturmak yine bakım sorununa dönüşebilir. Araç yalnızca organizasyon sağlar, doğru component API tasarımının yerini almaz.

Variant Naming

Variant isimleri görsel ayrıntı yerine mümkün olduğunca kullanım anlamını taşımalıdır. Red veya blue yerine destructive ve primary gibi semantic isimler theme ve marka değişikliklerine daha dayanıklıdır. Figma tarafında da aynı isimlerin kullanılması önerilir. Variant adı kullanıcı deneyimi amacını açık etmiyorsa yeniden değerlendirilmelidir. İsimlendirme standardı bütün component setinde tutarlı olmalıdır.

Size Variants

Size variant'ları component'in farklı density ve kullanım bağlamlarında boyut seçeneklerini tanımlar. Small, medium ve large gibi ölçekler kullanılabilir, ancak her component'in aynı sayıda size seçeneğine ihtiyacı yoktur. Icon size ve touch target gibi accessibility gereksinimleri unutulmamalıdır. Compact enterprise ekranlarda özel density ihtiyacı varsa bütün sistem seviyesinde düşünülmelidir. Rastgele height override yerine desteklenen size variant kullanımı tercih edilmelidir.

State Variants

State variant hover, active, loading, selected veya invalid gibi component durumlarını temsil eder. Bazı state'ler prop yerine native attribute veya data attribute üzerinden otomatik oluşabilir. Shadcn/ui güncel component yapısında primitive'lerde styling için data-slot kullanımını destekleyen değişiklikler bulunuyor. :contentReference[oaicite:12]{index=12} State davranışı hem görsel hem accessibility açısından test edilmelidir. Ürün geliştiricinin state class'larını tek tek elle kurması yerine component API'si güvenli varsayılan sunmalıdır.

Component API'sini Gereksiz Büyütmemek

Design system olgunlaştıkça farklı ekiplerden çok sayıda prop talebi gelebilir. Her talebi base component'e eklemek kısa sürede anlaşılması zor API oluşturur. Önce composition, slot veya product-level wrapper ile çözüm değerlendirilebilir. Yeni prop en az birkaç gerçek kullanımda ortak ihtiyaç gösteriyorsa merkezi API'ye alınabilir. Küçük ve öngörülebilir component API'si hem migration hem testing açısından daha sürdürülebilir olur.

Primitive, Semantic ve Composite Component Ayrımı

Primitive, semantic ve composite ayrımı design system'in sorumluluk sınırlarını anlaşılır hale getirir. Primitive düşük seviyeli reusable davranış, semantic şirket UX anlamı, composite ise daha geniş kullanıcı senaryosu sunar. Bu katmanlar fiziksel olarak farklı package olmak zorunda değildir, ancak mimari düşünce olarak ayrılmaları faydalıdır. Bir component'in hangi seviyede olduğu API kararlarını ve ownership modelini etkiler. Böylece ürün ekipleri en düşük seviyeyi gereksiz override etmek yerine ihtiyaçlarına uygun abstraction seviyesini seçebilir.

Primitive Component Nedir?

Primitive component domain bağımsız, tekrar kullanılabilir temel UI davranışını temsil eder. Button, Input ve Dialog gibi parçalar birçok ürün ekranında ortak ihtiyaçtır. Primitive mümkün olduğunca business kuralı taşımaz. Accessibility ve temel interaction davranışları bu seviyede güvenli varsayılan olarak sunulmalıdır. Üst component'ler primitive'i composition yoluyla kullanarak daha özel anlamlar ekler.

Button

Button kullanıcının bir action başlatmasını sağlayan temel interactive primitive'dir. Type, disabled, loading, icon ve variant davranışları şirket standardına göre düzenlenebilir. Native button semantics korunmalıdır. Link davranışı gereken durumlarda gerçek link ile button ayrımı dokümante edilmelidir. Focus indicator ve keyboard activation bütün varyantlarda test edilmelidir.

Input

Input metin verisi girişi için temel primitive'dir. Tek başına label veya error ilişkisini her zaman taşımaz, bu nedenle FormField gibi daha üst abstraction içinde kullanılabilir. Disabled, readonly ve invalid state'ler açık olmalıdır. Browser autofill davranışı ve farklı input type'ları test edilmelidir. Input styling semantic token'lardan beslenerek theme uyumu korunmalıdır.

Dialog

Dialog kullanıcıyı mevcut bağlam üzerinde odaklanması gereken ayrı etkileşime taşır. Focus trap, escape davranışı ve focus return erişilebilirliğin önemli parçalarıdır. Her bilgi için dialog açmak kullanıcı deneyimini gereksiz bölebilir. Design system ne zaman modal, drawer veya ayrı sayfa kullanılacağını guideline olarak açıklayabilir. Primitive teknik davranışı sağlarken kullanım kararı semantic ve UX dokümantasyonuyla desteklenmelidir.

Semantic Component Nedir?

Semantic component temel primitive'e şirketin kullanım anlamını ekler. Örneğin PrimaryAction yalnızca mavi Button değil, ekranın ana aksiyonunu temsil eden kullanım kontratıdır. Bu yapı yanlış variant seçimini azaltabilir. Ancak semantic component sayısı kontrolsüz büyütülürse geliştirici hangi abstraction'ı kullanacağını anlamakta zorlanır. Yalnızca güçlü tekrar eden UX anlamları için tercih edilmelidir.

PrimaryAction

PrimaryAction ekranın veya bölümün ana ilerleme aksiyonunu temsil eder. Bir ekranda çok sayıda PrimaryAction kullanılması görsel hierarchy'yi bozabilir. Component primary variant, uygun size ve loading davranışını standartlaştırabilir. Metin içeriğinin kısa ve eylem odaklı olması content guideline içinde açıklanabilir. Böylece renk tercihi ile UX anlamı aynı component kontratında birleşir.

DestructiveAction

DestructiveAction veri silme veya geri dönüşü zor işlem gibi riskli aksiyonlar için kullanılabilir. Component destructive visual token'larını uygulayabilir ve gerektiğinde confirmation pattern ile birlikte sunulabilir. Her iptal butonu destructive olarak işaretlenmemelidir. Kullanıcıya işlemin sonucu açıkça anlatılmalıdır. Accessibility açısından renk dışındaki metin ve context sinyalleri korunmalıdır.

Composite Component Nedir?

Composite component birkaç primitive ve semantic parçayı tekrar eden kullanıcı senaryosunda birleştirir. UserCard, SearchForm veya FilterPanel gibi component'ler hem layout hem interaction mantığı taşıyabilir. Bu parçalar gerçek ürünlerde tekrarlandığında güçlü hız kazandırır. Çok fazla business logic eklenirse reusable özellik hızla azalır. Design system'e alınmadan önce esneklik sınırı ve sahiplik modeli belirlenmelidir.

UserCard

UserCard avatar, kullanıcı adı, metadata ve action alanlarını ortak yapıda gösterebilir. Şirketin birden fazla ürününde aynı kullanıcı özeti kullanılıyorsa iyi composite adayıdır. Ancak her ürün farklı kullanıcı verisi gösteriyorsa prop sayısı hızla artabilir. Slot veya composition yaklaşımı belirli esneklik sağlayabilir. Çok ürünlü kullanım doğrulanmıyorsa product-level component olarak kalması daha doğru olabilir.

SearchForm

SearchForm Input, Button ve gerekirse filter öğelerini ortak arama deneyiminde birleştirir. Keyboard submit, clear ve loading davranışları standartlaştırılabilir. Arama sorgusunun business mantığı component içine gömülmemelidir. Consumer uygulama data fetching davranışını kontrol ederken component UI interaction standardını sağlar. Böyle ayrım component'in farklı ürünlerde tekrar kullanımını kolaylaştırır.

FilterPanel

FilterPanel Select, Checkbox, Date Picker ve action öğelerini filtreleme pattern'i etrafında birleştirebilir. Desktop ve mobil davranışları farklı olabilir. Applied filter sayısı, clear all ve submit pattern'i standartlaştırılabilir. Domain-specific filtre seçenekleri consumer tarafından sağlanmalıdır. Böylece tasarım sistemi filter experience'ı ortaklaştırırken ürün verisine bağımlı hale gelmez.

Product-Specific Component Ne Zaman Design System'e Eklenmemeli?

Component yalnızca tek ürünün iş kuralını içeriyorsa merkezi design system'e taşınması genellikle erken karardır. Sık değişen domain logic core package release hızını ürün roadmap'ine bağlayabilir. Aynı ihtiyacın farklı ürünlerde gerçekten tekrar edip etmediği gözlemlenmelidir. Primitive ve token kullanımı merkezi kalırken product-specific composition ürün repository'sinde tutulabilir. Ortak kullanım olgunlaştığında daha genel API tasarlanıp merkezi sisteme taşınması çok daha güvenli olur.

Şirket İçin Standart Button Sistemi Oluşturmak

Button sistemi basit görünmesine rağmen design system kalitesini ölçmek için iyi örnektir. Variant, size, loading, disabled, icon ve destructive davranışları bütün ürünlerde ortak standarda bağlanabilir. API'nin küçük ve semantic olması ürün geliştiricilerin doğru seçimi hızlı yapmasını sağlar. Accessibility kuralları primitive içinde güvenli varsayılan haline getirilmelidir. Figma variant isimleri ile TypeScript prop değerleri aynı tutulduğunda tasarım ve kod arasındaki iletişim de belirgin şekilde iyileşir.

Button Variant'ları

Button variant'ları primary, secondary, ghost veya destructive gibi anlamlı seçeneklerden oluşabilir. Her variant'ın hangi kullanım hiyerarşisini temsil ettiği dokümante edilmelidir. Yalnızca farklı renk ihtiyacı yeni variant gerekçesi olmamalıdır. Tema ve marka farklılıkları token üzerinden yönetilmelidir. Variant galerisi Storybook içinde bütün state'lerle gösterildiğinde ekipler doğru seçimi daha kolay yapar.

Button Size'ları

Size seçenekleri interaction alanı ve ürün density ihtiyacına göre belirlenmelidir. Small, default ve large çoğu sistem için yeterli olabilir. Çok küçük butonlar touch target ve okunabilirlik açısından sorun oluşturabilir. Icon ve text hizası her size içinde test edilmelidir. Ürün ekiplerinin height'i className ile rastgele değiştirmesi yerine desteklenen scale kullanması teşvik edilmelidir.

Loading State

Loading state kullanıcıya action'ın başladığını ve henüz tamamlanmadığını bildirir. Tekrar tıklamayı engellemek gerekebilir. Button genişliğinin loading sırasında zıplamaması daha stabil deneyim sağlar. Spinner yanında accessible loading açıklaması gerektiğinde eklenebilir. Loading state'in disabled state ile aynı semantic davranışı taşıyıp taşımadığı açık API ile belirlenmelidir.

Disabled State

Disabled state kullanıcının action'ı neden kullanamadığını tamamen gizlememelidir. Kritik durumlarda açıklama veya validation feedback sağlanması gerekebilir. Native disabled davranışı keyboard ve form semantics açısından avantajlıdır. Görsel contrast çok düşük yapılarak buton okunamaz hale getirilmemelidir. Disabled state bütün theme ve size varyantlarında test edilmelidir.

Icon Button

Icon Button yalnızca ikon gösterdiği için accessible name zorunluluğu taşır. Kullanıcı ikonun anlamını her zaman tahmin edemeyebilir. Tooltip yardımcı olabilir ancak accessible label'ın yerine geçmemelidir. Icon size ve touch target standardı belirlenmelidir. Delete veya edit gibi yaygın ikonların bütün ürünlerde aynı semantic anlamla kullanılması tutarlılığı güçlendirir.

Destructive Action

Destructive action geri dönüşü zor işlemler için belirgin risk sinyali sunar. Yalnızca kırmızı renk kullanmak yeterli değildir. Açık action label ve gerektiğinde confirmation dialog kullanılmalıdır. Çok sık destructive görünüm kullanmak gerçek kritik işlemlerin önemini azaltır. Design guideline hangi işlemlerin bu kategoriye girdiğini örneklerle göstermelidir.

Accessibility Kuralları

Button keyboard ile erişilebilir ve Enter veya Space davranışlarına uygun olmalıdır. Focus indicator görünür kalmalıdır. Icon-only kullanımda accessible name bulunmalıdır. Loading ve disabled durumlarında screen reader davranışı test edilmelidir. Otomatik testler faydalıdır, ancak semantic doğruluk ve kullanıcı deneyimi manuel keyboard kontrolüyle de doğrulanmalıdır.

Kurumsal Form Component Sistemi

Kurumsal uygulamalarda form component'leri design system'in en yoğun kullanılan parçaları arasındadır. Input, Select, Checkbox, Radio Group, Date Picker ve Combobox gibi primitive'ler ortak Form Field yapısıyla label, description, required state ve validation error davranışına bağlanmalıdır. Bu model geliştiricinin her formda erişilebilirlik ilişkilerini tekrar kurmasını azaltır. Form library entegrasyonu component'leri belirli business modeline kilitlemeden yapılmalıdır. Error state, focus yönetimi ve screen reader açıklamaları sistem seviyesinde doğru çözüldüğünde çok sayıda ürün aynı erişilebilir temel üzerinden çalışabilir.

Input

Input text, email, number ve benzeri veri girişlerinde temel form primitive'idir. Label ilişkisi Form Field katmanında güvenli biçimde kurulmalıdır. Invalid, disabled ve readonly state'ler hem görsel hem semantic olarak ayrılmalıdır. Placeholder label yerine kullanılmamalıdır. AutoComplete ve input type gibi native özellikler component API tarafından gereksiz engellenmemelidir.

Select

Select sınırlı seçenek listesinden tek veya belirli durumlarda çoklu seçim için kullanılabilir. Native Select ile custom popover tabanlı Select arasındaki accessibility ve mobil deneyim farkları değerlendirilmelidir. Çok uzun listelerde Combobox daha uygun olabilir. Placeholder ve selected value durumları açıkça gösterilmelidir. Keyboard navigation bütün custom Select implementasyonlarında kritik test alanıdır.

Checkbox

Checkbox bağımsız boolean tercih veya çoklu seçim grupları için uygundur. Label ile tıklama alanı birlikte çalışmalıdır. Checked, unchecked ve gerektiğinde indeterminate state desteklenebilir. Tek seçim için Radio Group ile karıştırılmamalıdır. Form validation içinde required checkbox kullanımının kullanıcıya açık biçimde anlatılması gerekir.

Radio Group

Radio Group kullanıcının birbirini dışlayan seçeneklerden tek seçim yapmasını sağlar. Grup label veya legend benzeri semantic ilişki taşımalıdır. Keyboard arrow navigation doğru çalışmalıdır. Seçenek sayısı çok fazlaysa Select veya başka pattern değerlendirilmelidir. Her radio label'ı tek başına anlaşılır olmalıdır.

Date Picker

Date Picker kurumsal ürünlerde locale, timezone ve accessibility nedeniyle dikkatli tasarlanmalıdır. Kullanıcı yalnızca calendar üzerinden değil gerektiğinde keyboard ile de tarih girebilmelidir. Format açıkça gösterilmelidir. Min, max ve disabled date kuralları business requirement ile bağlanabilir. Tarih verisinin UI formatı ile API formatı birbirinden ayrılmalıdır.

Combobox

Combobox arama yapılabilen seçim listeleri için güçlü pattern'dir. Keyboard navigation, active option ve screen reader announcement davranışları doğru kurulmalıdır. Server-side search gerekiyorsa loading ve empty state düşünülmelidir. Çok büyük veri listesi doğrudan client'a yüklenmemelidir. Component yalnızca UI davranışını yönetmeli, veri kaynağı stratejisini consumer'a bırakmalıdır.

Form Field

Form Field input control ile label, description, error ve required bilgilerini tek standarda bağlayan composite yapı olabilir. Bu yaklaşım bütün form component'lerinin aynı spacing ve feedback düzenini kullanmasını sağlar. Field ID ve aria ilişkileri otomatik oluşturulabilir. Validation state consumer form library'den alınabilir. Component'in çok fazla business validation logic taşımaması gerekir.

Label

Label kullanıcıya alanın hangi bilgiyi istediğini açıklar. Placeholder ile değiştirilmemelidir çünkü kullanıcı yazmaya başladığında placeholder kaybolur. Label control ile programatik olarak ilişkilendirilmelidir. Uzun label ve farklı dillerde wrapping davranışı test edilmelidir. Required bilgisi yalnızca görsel yıldızla bırakılmamalıdır.

Description

Description kullanıcıya format, amaç veya ek açıklama sunar. Her alan için açıklama eklemek formu gereksiz kalabalıklaştırabilir. Yalnızca gerçekten karar veya giriş kalitesini destekleyen bilgiler kullanılmalıdır. Screen reader ilişkisi gerektiğinde aria-describedby üzerinden kurulabilir. Error oluştuğunda description ve error sırasının nasıl davranacağı design system tarafından standardize edilmelidir.

Validation Error

Validation Error sorunun ne olduğunu ve kullanıcının nasıl düzeltebileceğini mümkün olduğunca açık anlatmalıdır. “Geçersiz değer” yerine spesifik kural daha faydalıdır. Error mesajı renk dışında ikon veya metin sinyaliyle desteklenmelidir. Screen reader'a doğru zamanda iletilmesi gerekir. Form submit sonrasında ilk hatalı alana focus veya error summary pattern'i değerlendirilmelidir.

Required Indicator

Required Indicator zorunlu alanları tutarlı biçimde göstermelidir. Yalnızca yıldız simgesine güvenilirse anlam açık olmayabilir. Form başında yıldızın ne ifade ettiği açıklanabilir veya “zorunlu” metni kullanılabilir. Native required veya aria-required semantiği teknik olarak da doğru kurulmalıdır. Opsiyonel alanların sayısı azsa bazı sistemlerde yalnızca “opsiyonel” olanları işaretlemek daha sade deneyim sağlayabilir.

React Hook Form Entegrasyonu

Form component'leri React Hook Form gibi bir library ile kolay entegre olabilmeli, ancak yalnızca ona bağımlı çalışmak zorunda kalmamalıdır. Primitive Input standart value, defaultValue, onChange ve ref davranışlarını korursa farklı form çözümleriyle kullanılabilir. Üst seviyede helper adapter veya FormField wrapper oluşturulabilir. Validation schema entegrasyonu ürün katmanında kalabilir. Böylece design system ileride form library değişikliğinde büyük migration yapmak zorunda kalmaz.

Form Component'lerinde Accessibility

Form accessibility label, description, error ve control arasındaki semantic ilişkilerin doğru kurulmasına dayanır. Keyboard navigation bütün interactive alanlarda çalışmalıdır. Error yalnızca renk ile belirtilmemelidir. Focus sırası DOM düzeniyle mantıklı ilerlemelidir. Storybook accessibility kontrolleri ve gerçek keyboard testleri form component'leri için release kriterinin parçası olmalıdır.

Enterprise Uygulamalar İçin Eksik Component'leri Tamamlamak

Shadcn/ui güçlü primitive ve yaygın component tabanı sunsa da enterprise uygulamalar genellikle daha geniş pattern setine ihtiyaç duyar. Data Table, Advanced Filter, Bulk Actions, File Upload, Tree View, Form Wizard ve permission-aware UI gibi ihtiyaçlar kurumun kendi design system katmanında geliştirilebilir. Bu parçaları eklerken mevcut primitive'leri compose etmek, yeni davranışı sıfırdan düşük seviyede yazmaktan daha güvenli olabilir. Her enterprise component'in bütün olası ürün ihtiyaçlarını tek API'de çözmeye çalışması doğru değildir. Gerçek ürünlerden gelen tekrar eden kullanım örnekleri üzerinden iteratif geliştirme yapmak sistemin gereksiz büyümesini önler.

Data Table

Data Table sorting, filtering, pagination, selection ve responsive davranışlarıyla enterprise ürünlerde sık kullanılan karmaşık pattern'dir. Headless table engine ile visual design system katmanını ayırmak esneklik sağlayabilir. Column definition, empty state, loading ve error davranışları standardize edilebilir. Çok farklı ürün ihtiyaçları nedeniyle tek dev Table component'i yerine composable API daha sürdürülebilir olabilir. Keyboard ve screen reader deneyimi özellikle interactive cell veya selection durumlarında test edilmelidir.

Advanced Filter

Advanced Filter çok sayıda veri kriterini kontrollü biçimde kullanıcıya sunar. Filter type, operator ve selected value modeli ortak hale getirilebilir. Applied filter chip'leri ve clear behavior standardize edilebilir. Domain'e özel filtre değerleri consumer tarafından sağlanmalıdır. Mobil ve dar ekranlarda panel davranışı ayrıca tasarlanmalıdır.

Bulk Actions

Bulk Actions tablo veya liste içinde birden fazla öğe seçildiğinde ortak işlem yapmayı sağlar. Selection count ve action bar davranışı ürünlerde tutarlı olmalıdır. Destructive bulk işlem için confirmation ve sonuç feedback'i önemlidir. Yetki kontrolü action görünürlüğünü etkileyebilir. Büyük veri setlerinde “mevcut sayfa” ile “tüm sonuçlar” seçiminin anlamı açıkça belirtilmelidir.

File Upload

File Upload drag-and-drop, file picker, progress, validation ve error state gibi birçok davranışı içerir. Maksimum boyut ve dosya tipi kullanıcıya yükleme öncesinde gösterilmelidir. Upload logic ve storage provider design system'in sorumluluğu olmak zorunda değildir. Component UI state ve interaction standardını sağlayabilir. Keyboard ve screen reader ile dosya seçimi desteklenmelidir.

Date Range Picker

Date Range Picker raporlama ve filtreleme ekranlarında yaygın enterprise ihtiyacıdır. Başlangıç ve bitiş tarihi ilişkisi açıkça gösterilmelidir. Preset seçenekler gerekiyorsa ürün kullanımına göre tanımlanabilir. Locale ve timezone davranışı standardize edilmelidir. Dar ekranlarda iki takvim yerine farklı interaction modeli gerekebilir.

Tree View

Tree View hiyerarşik data gösterimi ve seçim için kullanılabilir. Expand, collapse, keyboard navigation ve selection state doğru tanımlanmalıdır. Büyük data setinde lazy loading gerekebilir. Folder ve leaf semantics kullanıcı tarafından kolay anlaşılmalıdır. Screen reader deneyimi native veya ARIA tree pattern'lerine uygun şekilde test edilmelidir.

Command Menu

Command Menu hızlı navigation ve action araması sağlayabilir. Keyboard shortcut ve fuzzy search davranışı şirket ürünlerinde ortaklaştırılabilir. Sonuç gruplama ve empty state tasarlanmalıdır. Her action'ın authorization kontrolü yapılmalıdır. Command palette normal navigation'ın tek alternatifi haline gelmemelidir.

Form Wizard

Form Wizard uzun süreçleri birkaç anlamlı adıma böler. Step validation, geri dönüş, progress ve draft davranışları ortak pattern'e bağlanabilir. Her formun wizard olması gerekmez. Adımlar kullanıcının zihinsel modeline göre gruplanmalıdır. URL veya state persistence stratejisi product architecture'a bırakılabilir.

Empty State

Empty State yalnızca boş alanı dolduran illüstrasyon değildir. Kullanıcıya neden veri olmadığını ve mümkünse sonraki adımı anlatmalıdır. İlk kullanım ile filtre sonucu boş olması farklı mesajlar gerektirebilir. Design system birkaç semantic empty state pattern'i sağlayabilir. Action bulunuyorsa hierarchy ve permission koşulları dikkate alınmalıdır.

Error State

Error State teknik hata kodunu doğrudan kullanıcıya göstermek yerine anlaşılır durum ve recovery seçeneği sunmalıdır. Retry, support veya geri dönüş action'ları bağlama göre değişebilir. Page-level ve component-level error için farklı pattern gerekebilir. Error reference ID gibi destek bilgileri gerektiğinde gösterilebilir. Design system error tone ve visual hierarchy'yi ortaklaştırabilir.

Permission-Aware Components

Permission-aware component kullanıcı yetkisine göre action veya içerik görünürlüğünü yönetmeye yardımcı olabilir. Ancak frontend kontrolü güvenlik sınırı olarak görülmemelidir ve backend authorization mutlaka korunmalıdır. UI seviyesinde disabled mı hidden mı davranışı ürün ve güvenlik UX standardına göre belirlenebilir. Permission logic merkezi helper veya context üzerinden okunabilir. Component API'nin business role isimlerine doğrudan bağlanması yerine genel capability modeli daha reusable olabilir.

Figma ile Shadcn UI Kodunu Senkronize Etmek

Figma ile kod arasında sağlıklı senkronizasyon yalnızca component isimlerinin benzemesiyle sağlanmaz. Design token, variant, component property ve state modelleri mümkün olduğunca aynı zihinsel yapıyı kullanmalıdır. Designer Button için “variant=destructive, size=sm” seçtiğinde geliştiricinin TypeScript API'sinde aynı değerleri bulması büyük hız kazandırır. Figma Variables design token sisteminin tasarım tarafındaki karşılığını oluşturabilir. Drift tamamen sıfırlanamaz, ancak düzenli audit, ownership ve visual regression süreçleriyle ölçülebilir seviyede tutulabilir.

Figma Component Library Yapısı

Figma library primitive, composite ve template gibi anlaşılır gruplara ayrılabilir. Component isimleri kod repository'sindeki kavramlarla mümkün olduğunca uyumlu olmalıdır. Deprecated component tasarım tarafında da açıkça işaretlenmelidir. Yeni variant veya component release edilmeden developer review alınması drift riskini azaltır. Library'nin owner ve yayın süreci belirli olmalıdır.

Figma Variables ile Design Tokens

Figma Variables renk, spacing ve benzeri değerlerin tasarım tarafında token olarak kullanılmasını sağlar. Primitive ve semantic collection ayrımı kod yapısıyla eşleştirilebilir. Light, dark veya brand mode'ları variable mode'larıyla modellenebilir. İsimlerin otomasyonla dönüştürülebilecek standarda sahip olması token pipeline geliştirmeyi kolaylaştırır. Tasarımcıların raw color yerine semantic variable kullanması Figma içindeki design system dışına çıkışları da azaltır.

Component Properties

Figma Component Properties variant, boolean, text veya instance swap gibi seçeneklerle component API'sine benzer kontrol yüzeyi sağlar. Kod tarafındaki prop isimleriyle yakın eşleşme handoff'u kolaylaştırır. Her kod prop'unun Figma property karşılığı olmak zorunda değildir. Teknik callback veya data prop'ları tasarım aracında anlamlı değildir. Yalnızca kullanıcı deneyimini etkileyen seçeneklerin eşleştirilmesi yeterlidir.

Variant İsimlerini Kodla Eşleştirmek

Figma'da primary, kodda default ve dokümantasyonda brand-button gibi üç farklı isim kullanmak sürekli çeviri ihtiyacı yaratır. Tek semantic isim seti belirlenmelidir. Breaking rename gerekiyorsa hem Figma hem code migration planı birlikte yapılmalıdır. Variant isimleri yalnızca görünüm değil kullanım anlamı taşımalıdır. Bu ortak sözlük QA ve product ekiplerinin de aynı terminolojiyi kullanmasını sağlar.

Design Token İsimlerini Aynı Tutmak

Figma ve CSS token isimleri birebir veya deterministik dönüşümle eşlenebilirse drift kontrolü kolaylaşır. Örneğin color/background/primary ile --color-background-primary arasında açık mapping bulunabilir. Manuel isim eşleştirme zamanla hata üretir. Token export veya validation script'leri otomasyonu destekleyebilir. İsim standardı başlangıçta belirlenirse ileride multi-brand eklemek çok daha kolay olur.

Designer–Developer Handoff Süreci

Handoff yalnızca Figma linkinin geliştiriciye gönderilmesi olmamalıdır. Kullanılan component, yeni token, state ve responsive davranışları açıkça belirtilmelidir. Tasarım system dışına çıkan yeni pattern varsa development başlamadan önce ortak review yapılmalıdır. Geliştirici teknik uygulanabilirlik konusunda erken feedback verebilir. Böylece tasarım tamamlandıktan sonra büyük geri dönüşler yaşanmaz.

Figma–Code Drift Problemi

Figma ve code farklı hızlarda değiştiğinde component varyantları ve görsel değerler ayrışabilir. Designer eski Figma component'ini kullanırken developer yeni API ile çalışabilir. Drift arttıkça handoff ve QA maliyeti büyür. Her iki kaynağın owner'ı ve release ritmi tanımlanmalıdır. Küçük düzenli güncellemeler büyük dönemsel eşitleme projelerinden daha yönetilebilir olur.

Drift Nasıl Ölçülür ve Önlenir?

Drift component inventory karşılaştırması, token diff ve visual audit ile ölçülebilir. Figma'da bulunan ancak code'da olmayan variant'lar raporlanabilir. Kod story screenshot'ları onaylı tasarımla periyodik olarak karşılaştırılabilir. Yeni design system release checklist'ine Figma update maddesi eklenebilir. Ölçüm cezalandırma amacıyla değil, senkronizasyon sürecinin nerede koptuğunu görmek için kullanılmalıdır.

Storybook ile Şirket İçi Component Dokümantasyonu

Storybook component'leri uygulama ekranından bağımsız geliştirmek, göstermek ve test etmek için güçlü bir çalışma alanı sağlar. Her component'in variant, responsive, theme ve interaction durumları story olarak görünür hale getirilebilir. Güncel Storybook dokümantasyonu interaction testlerinin story içindeki play fonksiyonlarıyla kullanıcı davranışlarını simüle edebildiğini ve accessibility addon'un axe-core tabanlı otomatik kontroller sunduğunu belirtiyor. :contentReference[oaicite:13]{index=13} Bu nedenle Storybook yalnızca component kataloğu değil, design system kalite altyapısının önemli parçası haline gelebilir. Dokümantasyon, test ve tasarım review aynı ortamda birleştiğinde component release süreci daha öngörülebilir olur.

Storybook Neden Kullanılmalı?

Storybook component'i bütün application bağımlılıklarından ayırarak tek başına incelemeyi kolaylaştırır. Designer ve QA doğrudan component state'lerini görebilir. Geliştirici nadir edge case'leri tekrar üretmek için bütün ürünü çalıştırmak zorunda kalmaz. Story'ler visual regression ve interaction testleri için fixture görevi görebilir. Bu ortak ortam design system adoption ve review süreçlerini hızlandırır.

Her Component İçin Story Yazmak

Design system içinde stable olarak yayınlanan her component için temel story bulunması güçlü standarttır. Default kullanımın yanında kritik variant ve state'ler ayrı gösterilebilir. Bütün prop kombinasyonlarını story haline getirmek gereksiz olabilir. Gerçek kullanıcı davranışını temsil eden örneklere öncelik verilmelidir. Story eksikliği component'in dokümantasyon ve test görünürlüğünü azaltır.

Component Props Dokümantasyonu

Props dokümantasyonu API'nin ne yaptığını ve hangi seçeneklerin desteklendiğini açıklar. TypeScript type'larından otomatik bilgi alınabilir, ancak yalnızca type adı kullanım bağlamını anlatmaz. Kritik prop için kısa guideline ve örnek verilmelidir. Deprecated prop'lar görünür biçimde işaretlenmelidir. Dokümantasyon component source ile aynı release içinde güncellenmelidir.

Variant Galerisi

Variant galerisi component'in bütün temel görsel seçeneklerini tek bakışta göstermeyi sağlar. Button primary, secondary ve destructive varyantları light ve dark theme içinde karşılaştırılabilir. Designer ve developer Figma ile code farkını hızlı fark edebilir. Visual regression için de güçlü fixture oluşturur. Galeri çok büyükse category veya matrix görünümü kullanılabilir.

Dark Mode Stories

Dark Mode Stories component'in dark theme'deki gerçek durumunu sürekli görünür kılar. Yalnızca default state değil hover, disabled ve error durumları da test edilmelidir. Theme decorator ile story environment kolayca değiştirilebilir. Snapshot veya screenshot testi light ve dark varyantları kapsayabilir. Bu alışkanlık dark mode regressionlarının release sonrasında fark edilmesini azaltır.

Responsive Stories

Responsive Stories component'in farklı container ve viewport genişliklerindeki davranışını gösterir. Özellikle Table, Navigation ve Form layout'larında değerlidir. Sadece desktop screenshot üzerinden component tamamlandı kabul edilmemelidir. Uzun text ve küçük ekran senaryoları eklenebilir. Storybook viewport kontrolü design review sırasında da kullanılabilir.

Interaction Tests

Interaction testleri kullanıcı tıklaması, typing ve form submission gibi davranışları story içinde doğrulayabilir. Storybook dokümantasyonu bu testlerin play fonksiyonlarıyla yazılabildiğini ve CI ortamında otomatik çalıştırılabildiğini açıklıyor. :contentReference[oaicite:14]{index=14} Dialog açma, Combobox seçim veya validation akışı gibi component'ler için özellikle değerlidir. Testler yalnızca implementation detail yerine kullanıcı tarafından gözlemlenen sonucu doğrulamalıdır. Böylece story hem dokümantasyon hem davranış testi görevi görür.

Accessibility Panel

Storybook accessibility addon component render edildiğinde otomatik accessibility kontrolleri sağlayabilir. Resmi dokümantasyona göre addon axe-core üzerine kuruludur ve sonuçları violation, pass ve manuel kontrol gerektiren durumlar şeklinde sunabilir. :contentReference[oaicite:15]{index=15} Bu testler birçok temel sorunu erken yakalar. Ancak keyboard flow, screen reader deneyimi ve doğru UX anlamı yalnızca otomasyonla garanti edilemez. Bu nedenle accessibility panel manuel review süreçlerini tamamlayan ilk kalite katmanı olarak kullanılmalıdır.

Do / Don't Örnekleri

Do / Don't örnekleri yalnızca component'in nasıl kullanılacağını değil hangi kullanımların yanlış olduğunu da gösterir. Özellikle Button hierarchy, Dialog kullanımı veya Form error pattern'lerinde çok değerlidir. Görsel örnek kısa metinden daha hızlı anlaşılabilir. “Don't” örnekleri gerçek ürünlerde sık görülen hatalardan seçilmelidir. Böylece dokümantasyon soyut kural listesi yerine ürün ekiplerinin günlük kararlarını destekleyen rehbere dönüşür.

Design Guidelines Eklemek

Component story'si yalnızca prop tablosuyla sınırlı kalmamalıdır. Ne zaman kullanılacağı, hangi alternatifin tercih edilmesi gerektiği ve content kuralları açıklanabilir. UX ve accessibility guideline aynı sayfada bulunabilir. Figma component linki eklenebilir. Bu yaklaşım Storybook'u teknik component kataloğundan şirket içi design system portalına yaklaştırır.

Design System Dokümantasyonu Nasıl Yazılmalı?

Design system dokümantasyonu geliştirici, tasarımcı ve ürün ekiplerinin günlük sorularına hızlı cevap vermelidir. Component API kadar kullanım amacı, yanlış kullanım örnekleri, accessibility, content ve migration bilgileri de önemlidir. Çok uzun teori yerine karar anında kullanılabilecek açık örnekler daha değerlidir. Dokümantasyon source code release sürecine bağlanmazsa kısa sürede güncelliğini kaybeder. Her component'in owner'ı documentation değişikliklerinden de sorumlu olduğunda yaşayan sistem oluşturmak daha kolaydır.

Component Ne Zaman Kullanılmalı?

Her component sayfası çözdüğü kullanıcı problemini açıklamalıdır. Örneğin Dialog'ın kullanıcıyı kısa kritik karara odaklamak için uygun olduğu belirtilebilir. Benzer alternatifler arasında seçim kriteri sunulmalıdır. Kullanım amacı yalnızca teknik açıklama olmamalıdır. Bu bilgi designer ve product ekiplerinin de aynı sistemi doğru kullanmasını sağlar.

Ne Zaman Kullanılmamalı?

Yanlış kullanım sınırları component standardının önemli parçasıdır. Örneğin Tooltip kritik bilginin tek taşıyıcısı olarak kullanılmamalıdır. Dialog çok uzun form akışları için uygun olmayabilir. Gerçek ürün hatalarından örnekler eklenebilir. Bu bilgiler component API'sinin kontrol edemediği UX yanlışlarını azaltır.

API Reference

API Reference prop, event ve variant seçeneklerinin teknik açıklamasını içerir. TypeScript type'ları otomatik üretim için kullanılabilir. Default değerler ve controlled veya uncontrolled davranışlar açık olmalıdır. Breaking change olduğunda eski ve yeni API farkı migration note ile desteklenmelidir. Reference mümkün olduğunca component sürümüyle aynı kaynak üzerinden yayınlanmalıdır.

Accessibility Kuralları

Accessibility bölümü keyboard behavior, focus management ve gerekli accessible name gibi kuralları açıklamalıdır. Component'in consumer tarafından sağlanması gereken zorunlu bilgiler belirtilmelidir. Örneğin IconButton label gereksinimi açıkça yazılabilir. Otomatik testlerin hangi alanı kapsadığı belirtilebilir. Manuel test gerektiren davranışlar checklist olarak eklenebilir.

Content Guidelines

Content Guidelines buton metni, validation mesajı veya empty state yazımı gibi mikro içerik standartlarını tanımlar. Aynı component'in farklı ürünlerde farklı ton kullanmasını azaltır. Metin kısa, açık ve action odaklı olmalıdır. Hata mesajları kullanıcıya çözüm yolunu göstermelidir. Localization ve uzun metin ihtiyacı içerik guideline hazırlanırken dikkate alınmalıdır.

UX Kuralları

UX kuralları component'in interaction bağlamını açıklar. Confirmation ne zaman gerekir, loading state ne zaman gösterilir veya disabled yerine validation mı tercih edilir gibi kararlar burada yer alabilir. Bu bilgiler yalnızca geliştirici API'sinden anlaşılamaz. Designer ve product ekipleri için doğrudan değer üretir. Pattern düzeyindeki kurallar birden fazla component sayfasından ortak guideline'a bağlanabilir.

Migration Notes

Migration Notes değişen component API'sine mevcut uygulamaların nasıl geçirileceğini gösterir. Eski prop ve yeni karşılığı açıkça yazılmalıdır. Gerekirse codemod veya otomatik script sağlanabilir. Breaking change'in neden gerekli olduğu kısa biçimde açıklanabilir. Migration dokümanı olmadan major release adoption süresi ciddi şekilde uzayabilir.

Changelog

Changelog ürün ekiplerine design system'de hangi değişikliklerin yayınlandığını anlatır. Yeni component, bug fix, deprecation ve breaking change kategorileri ayrıştırılabilir. Her teknik commit'in changelog'a girmesi gerekmez. Consumer davranışını etkileyen değişikliklere odaklanılmalıdır. Otomatik release tooling ile changelog üretimi desteklenebilir, ancak metinlerin kullanıcı ekipler açısından anlaşılır olması gerekir.

Monorepo ile Şirket İçi Shadcn UI Yönetimi

Monorepo birden fazla uygulama ile ortak UI package'larının aynı repository içinde yönetildiği yapılarda güçlü seçenek olabilir. Shadcn/ui CLI güncel olarak monorepo yapısını destekliyor, workspace'lerde components.json kullanarak component ve dependency'leri uygun konumlara yerleştirebiliyor ve örnek başlangıçta Turborepo yapısı sunuyor. :contentReference[oaicite:16]{index=16} Şirket design token, UI component, config ve uygulamaları ortak repository içinde versionlayabilir. Bu model hızlı atomic change ve kolay refactor avantajı sağlar. Ancak repository çok büyük veya ekiplerin release bağımsızlığı yüksekse package ve registry tabanlı dağıtım seçenekleri ayrıca değerlendirilmelidir.

Monorepo Ne Zaman Mantıklıdır?

Birden fazla frontend aynı component setini yoğun biçimde kullanıyorsa monorepo güçlü avantaj sağlar. UI değişikliği ile consumer uygulama değişikliği aynı pull request içinde test edilebilir. Shared configuration ve tooling merkezi tutulur. Ekipler sık birlikte değişiklik yapıyorsa dependency version koordinasyonu azalır. Çok bağımsız organizasyonlarda veya ayrı repository zorunluluğu varsa monorepo yerine package veya registry modeli daha uygun olabilir.

Turborepo Yapısı

Turborepo monorepo içindeki uygulama ve package task'larını organize etmek için kullanılabilir. Build, lint, test ve Storybook pipeline'ları package bağımlılıklarına göre çalıştırılabilir. Shadcn/ui resmi monorepo başlangıç akışı da Turborepo tabanlı örnek oluşturabiliyor. :contentReference[oaicite:17]{index=17} Cache mekanizması CI süresini azaltabilir. Repository yapısı araç tarafından değil şirketin ownership ve dependency sınırlarına göre tasarlanmalıdır.

apps/

apps/ klasörü gerçek consumer uygulamaları içerebilir. Web portal, admin panel veya farklı ürün frontend'leri burada yer alabilir. Uygulamalar ortak UI package'ı tüketir. Product-specific component'ler ilgili app içinde kalabilir. Bu sınır design system ile ürün kodunun birbirine karışmasını azaltır.

packages/ui

packages/ui ortak primitive, semantic ve belirli composite component'leri barındırabilir. Public export yüzeyi kontrollü tutulmalıdır. Her internal helper consumer uygulamalara açılmamalıdır. Story ve test dosyaları component ile birlikte bulunabilir. Ownership ve code review kuralları bu package için daha sıkı uygulanabilir.

packages/tokens

packages/tokens design token CSS, source data veya generated output dosyalarını barındırabilir. Multi-brand theme'ler burada ayrı dosyalar halinde tutulabilir. Figma token pipeline varsa aynı source üzerinden generation yapılabilir. Consumer uygulamalar yalnızca stable token API'sini import etmelidir. Breaking token rename semantic versioning kapsamında değerlendirilmelidir.

packages/config

packages/config ESLint, TypeScript veya test gibi ortak configuration paketlerini içerebilir. Bu yaklaşım bütün uygulamalarda aynı design system lint kurallarını uygulamayı kolaylaştırır. Config paketleri aşırı opinionated hale getirilmemelidir. Uygulamaların gerekli küçük override alanları bulunabilir. Versioning monorepo içinde olsa bile değişikliklerin consumer etkisi test edilmelidir.

Shared UI Package

Shared UI Package ortak component'lerin uygulamalara tek import yüzeyi sunmasını sağlar. Package private workspace olarak veya ayrıca publish edilebilir. Export map ile internal dosyalara doğrudan import engellenebilir. Bu durum component API'sinin kontrollü kalmasına yardımcı olur. Consumer contract testleri public exportların istemeden kırılmasını önleyebilir.

Shared ESLint Configuration

Shared ESLint configuration hardcoded color, yasak import ve design system dışı kullanım kurallarını bütün uygulamalarda aynı şekilde uygular. Kurallar merkezi güncellenebilir. Legacy ürünlerde bazı rule'lar aşamalı etkinleştirilebilir. Fix önerileri geliştirici deneyimini iyileştirir. Lint standardı design system governance'ın kod seviyesindeki otomatik uygulayıcısı haline gelebilir.

Shared TypeScript Configuration

Shared TypeScript configuration strictness ve module ayarlarında ortak standart sağlar. UI package daha sıkı type kontrolü kullanabilir. Consumer uygulamalar minimum ortak baseline'ı paylaşır. Path alias ve module resolution monorepo yapısıyla uyumlu olmalıdır. Shadcn/ui CLI alias configuration'ının doğru tanımlanmasını monorepo kullanımında özellikle bekler. :contentReference[oaicite:18]{index=18}

Shared Tailwind Theme

Shared Tailwind Theme ortak token ve utility API'sini bütün uygulamalara sağlar. Tailwind CSS v4 theme variables CSS dosyaları üzerinden paylaşılabildiği için ortak theme package bu modele doğal şekilde uyum sağlar. :contentReference[oaicite:19]{index=19} Uygulamalar kendi product-level extension'larını kontrollü biçimde ekleyebilir. Core token override'ları kısıtlanabilir. Böylece bütün uygulamalar aynı semantic class sözlüğünü kullanır.

Birden Fazla Uygulamada Component Tüketimi

Consumer uygulamalar mümkün olduğunca public package exportları üzerinden component kullanmalıdır. Internal path importları future refactor'ları zorlaştırır. Aynı component farklı app'lerde story veya integration test ile doğrulanabilir. Monorepo CI affected package analizinden yararlanarak yalnızca ilgili uygulamaları test edebilir. Böylece merkezi component değişikliği geniş ürün yüzeyinde kontrollü biçimde yayılır.

Private Shadcn Registry Kurmak

Private Shadcn Registry şirket component'lerini Shadcn CLI akışına uygun biçimde farklı repository ve ürünlere dağıtmak için güçlü modeldir. Güncel registry sistemi custom registry item'larını component, UI, block, theme, hook ve farklı dosya tipleriyle tanımlayabiliyor. :contentReference[oaicite:20]{index=20} Namespaced registry configuration authenticated URL ve header desteği sunarak private component dağıtımını mümkün kılıyor. :contentReference[oaicite:21]{index=21} Bu model copy-and-own felsefesini şirket seviyesinde sürdürebilir çünkü consumer proje component kaynak kodunu doğrudan alır. Registry kurarken authentication, version pinning, dependency governance ve update stratejisi en baştan düşünülmelidir.

Shadcn Registry Nedir?

Shadcn Registry component ve ilgili dosyaları CLI tarafından çözülebilir yapılandırılmış öğeler halinde yayınlamayı sağlar. Registry item component source, dependency, CSS variable ve başka registry dependency'lerini tanımlayabilir. Güncel şema bütün design system için registry:base, component için registry:ui veya daha geniş yapılar için registry:block gibi türler sunar. :contentReference[oaicite:22]{index=22} Bu sayede şirket yalnızca tek dosyalık Button değil tema ve çok dosyalı pattern'leri de dağıtabilir. Registry bir package manager yerine code distribution ve composition mekanizması olarak düşünülmelidir.

Şirket İçi Registry Neden Kullanılır?

Şirket içi registry farklı repository'lerdeki ürünlere aynı approved component başlangıcını sağlar. Geliştirici CLI ile component ekler ve kod kendi projesine gelir. Merkezi package runtime dependency'si gerekmeyebilir. Ürün ekibi gerektiğinde kodu sahiplenebilir, ancak şirket update ve fork politikası belirlemelidir. Registry özellikle farklı release döngülerine sahip uygulamalarda copy-based dağıtım isteyen organizasyonlar için güçlü seçenektir.

Registry Yapısı

Registry root tanımı metadata ve item listesini içerir. Büyük registry yapıları birden fazla registry dosyasını include mekanizmasıyla organize edebilir. Güncel resmi şema item'ların dependencies, registryDependencies ve files gibi alanlarını destekliyor. :contentReference[oaicite:23]{index=23} Şirket component, block ve theme kataloglarını ayrı klasörlerde yönetebilir. Build pipeline generated registry output'unu publish ederek consumer CLI kullanımına açabilir.

Registry Metadata

Registry metadata isim, açıklama, sürüm veya şirket içi kategori bilgilerini taşıyabilir. Güncel item şeması custom metadata kullanımını da destekleyebilir. :contentReference[oaicite:24]{index=24} Bu bilgiler internal portal veya analytics tooling tarafından kullanılabilir. Metadata API contract kadar stabil olmak zorunda değildir, ancak naming standardı bulunmalıdır. Component lifecycle durumu gibi bilgilerin registry ile entegrasyonu adoption yönetimini kolaylaştırabilir.

Components

Component item tek veya birkaç dosyalık reusable UI parçasını temsil eder. Button, Input veya Alert gibi component'ler registry üzerinden dağıtılabilir. Item gerekli npm dependency ve başka registry component'lerini tanımlayabilir. Consumer CLI dependency zincirini çözebilir. Şirket kendi namespace'i altında approved component isimlerini tutarak discovery deneyimini iyileştirebilir.

Blocks

Blocks birden fazla component ve dosyadan oluşan daha geniş UI çözümünü temsil eder. Login paneli veya filtreli data table örneği verilebilir. Registry schema block türünü doğrudan destekler. :contentReference[oaicite:25]{index=25} Block consumer projeye başlangıç kodu sağlayabilir. Ürün business logic'inin fazla gömülmemesi reusable özelliği korur.

Dependencies

Registry item gerekli npm ve registry dependency'lerini açıkça tanımlamalıdır. Bu sayede component başka UI primitive'lerine bağlıysa CLI doğru kaynakları ekleyebilir. Dependency sürüm politikası şirket tarafından yönetilmelidir. Unreviewed dış dependency'nin registry item içine eklenmesi supply-chain riskini büyütebilir. Core team dependency değişikliklerini code review ve security sürecine dahil etmelidir.

Şirket Component'lerini CLI ile Dağıtmak

Namespaced registry sayesinde geliştirici şirket namespace'i ve component adını kullanarak internal UI öğesini ekleyebilir. Güncel shadcn registry namespace modeli URL pattern üzerinden kaynak çözümlemeyi destekliyor. :contentReference[oaicite:26]{index=26} Bu deneyim onboarding süresini azaltabilir. CLI yalnızca approved component'i kopyalamamalı, gerekli token ve dependency'leri de tutarlı biçimde kurmalıdır. Installation sonrasında local customization yapılacaksa update politikasının nasıl işleyeceği açıkça dokümante edilmelidir.

Registry Authentication

Private registry şirket içi component kodunu korumak için authentication gerektirebilir. Güncel resmi dokümantasyon Bearer token ve API key gibi yöntemlerle authenticated registry kullanımını ve credentials değerlerinin environment variable üzerinden verilmesini destekliyor. :contentReference[oaicite:27]{index=27} Token hiçbir zaman repository içine düz metin yazılmamalıdır. Access log ve rate limit gibi kontroller kurum ihtiyacına göre eklenebilir. Registry erişimi component source code'a erişim yetkisiyle uyumlu olmalıdır.

Internal Registry ile Official Registry'yi Birlikte Kullanmak

Şirket internal registry kullanırken official veya başka approved registry kaynaklarından da component alabilir. Namespaced yapı farklı registry'lerin ayrıştırılmasını sağlar. :contentReference[oaicite:28]{index=28} Product geliştirici hangi component'in şirket tarafından desteklendiğini açıkça görmelidir. External registry code'u kurulumdan önce security ve quality açısından incelenmelidir. Şirket standardına alınan component daha sonra internal registry içinde kontrollü fork veya wrapper olarak yayınlanabilir.

Private Registry mi npm Package mı Monorepo mu?

Private registry, npm package ve monorepo birbirini tamamen dışlayan seçenekler değildir. Monorepo sık birlikte değişen uygulama ve component'lerde atomic geliştirme sağlar, npm package merkezi runtime veya build dependency üzerinden version kontrollü dağıtım sunar, registry ise kaynak kodu consumer projeye kopyalayan esnek model sağlar. Şirket organizasyon yapısı, repository sayısı, release bağımsızlığı ve customization ihtiyacı seçimde belirleyicidir. Birçok büyük yapıda token ve core primitive package üzerinden, daha geniş block'lar registry üzerinden dağıtılabilir. Hibrit model gereksiz teknik çeşitliliğe dönüşmemesi için açık ownership ve kullanım kriterleriyle tanımlanmalıdır.

Monorepo Modelinin Avantajları

Monorepo design system ile consumer uygulamanın aynı commit içinde değişmesine imkan verir. Breaking refactor tek pull request'te bütün consumer'lara uygulanabilir. Ortak lint, test ve build configuration kolay paylaşılır. Package publish beklemeden local workspace development yapılabilir. Bunun karşılığında repository büyüklüğü ve ownership sınırlarının iyi yönetilmesi gerekir.

npm Package Modelinin Avantajları

npm package merkezi component implementasyonunu dependency olarak dağıtır. Consumer uygulama belirli version'a pin olabilir ve update'i kontrollü yapabilir. Security fix tek package release ile bütün ekiplerin alabileceği hale gelir. Component code consumer tarafından doğrudan fork edilmediği için drift daha sınırlı kalabilir. Ancak derin customization ihtiyacı package API'sini büyütebilir.

Shadcn Registry Modelinin Avantajları

Registry component source'u consumer projeye verdiği için maksimum ownership ve customization sağlar. Farklı repository'lerde ortak başlangıç standardı oluşturur. Package API'sine ek extension beklemek yerine product ekibi local değişiklik yapabilir. Bunun karşılığında güncelleme ve drift yönetimi ayrıca çözülmelidir. Registry en çok kontrollü copy-and-own modelini bilinçli olarak tercih eden organizasyonlarda değer üretir.

Hibrit Yaklaşım

Hibrit model primitive'leri merkezi package içinde tutup product-level blocks veya templates'i registry üzerinden dağıtabilir. Token package bütün ürünlerde tek semantic API sağlar. Monorepo içindeki ana ürünler workspace package kullanırken bağımsız repository'ler private registry veya npm package tüketebilir. Bu esneklik farklı ekip yapılarını destekler. Ancak aynı component'in üç farklı dağıtım yöntemiyle sahiplenilmesi önlenmelidir.

Hangi Şirket Hangi Modeli Seçmeli?

Az sayıda uygulama ve sık ortak değişiklik yapan ekipler monorepo ile hızlı ilerleyebilir. Çok sayıda bağımsız repository ve güçlü version kontrol ihtiyacı bulunan şirketlerde npm package daha uygun olabilir. Ürün ekiplerinin source'u özelleştirmesi kritikse private registry değerlendirilebilir. Karar yalnızca teknik tercih değil organizasyonun ownership modeliyle birlikte verilmelidir. Küçük pilot ile migration ve update deneyimini test etmek büyük geçişten önce faydalıdır.

Shadcn UI Güncellemeleri Nasıl Yönetilmeli?

Shadcn/ui copy modelinde component kaynağı projeye alındığı için upstream update'ler klasik dependency bump şeklinde otomatik uygulanmaz. Resmi Tailwind v4 geçiş dokümantasyonu bile overwrite ile component güncellemeden önce değişikliklerin commit edilmesini ve sonrasında local özelleştirmelerin tekrar gözden geçirilmesini öneriyor. :contentReference[oaicite:29]{index=29} Şirket bu gerçeği kabul ederek upstream monitoring, diff, patch ve breaking change değerlendirmesi için düzenli süreç kurmalıdır. Her upstream değişiklik alınmak zorunda değildir. Güvenlik, accessibility, browser uyumluluğu veya değerli API iyileştirmeleri öncelikli değerlendirilirken yalnızca görsel değişiklikler şirket theme'iyle uyumlu değilse atlanabilir.

Copy-Paste Modelinin Update Problemi

Component kopyalandığı anda upstream ile bağı gevşer. Sonraki resmi iyileştirme local dosyaya otomatik yansımaz. Şirket component'i çok değiştirmişse yeni source ile doğrudan overwrite risklidir. Bu nedenle başlangıç source version veya commit bilgisini metadata olarak tutmak faydalı olabilir. Update süreci diff ve test üzerinden yürütülmelidir.

Upstream ile Şirket Component'lerini Karşılaştırmak

Periyodik script veya tooling official component source ile internal version arasında diff üretebilir. Amaç local customization'ı silmek değil önemli upstream değişikliği fark etmektir. Diff kategori bazında incelenebilir. Accessibility veya bug fix daha yüksek öncelikli olabilir. Sonuç ADR veya update issue içinde kısa karar kaydıyla tutulabilir.

Upstream Değişikliklerini İzlemek

Changelog ve repository release'leri düzenli izlenebilir. Core team belirli periyotta yeni değişiklikleri değerlendirir. Her product ekibinin bunu ayrı yapması gereksiz tekrar oluşturur. Önemli değişiklik internal changelog veya RFC ile paylaşılır. Böylece upstream takibi merkezi ancak uygulama kararı kontrollü olur.

Patch Alma Stratejisi

Küçük bug veya accessibility fix local component'e hedefli patch olarak taşınabilir. Full component overwrite her zaman gerekli değildir. Patch yanında test eklemek aynı problemin tekrarını önler. Değişikliğin upstream source referansı decision history içinde tutulabilir. Sonraki büyük update sırasında hangi local patch'lerin artık gereksiz olduğu görülebilir.

Breaking Change'leri Yönetmek

Breaking upstream değişiklik doğrudan internal API'ye uygulanmamalıdır. Önce şirket component API'sine gerçek faydası değerlendirilmelidir. Gerekliyse major release veya deprecation süreci planlanır. Consumer migration guide ve codemod hazırlanabilir. Geçiş için yeterli zaman verilmesi adoption sorununu azaltır.

Fork Drift'i Kontrol Altında Tutmak

Fork drift local component'in upstream'den giderek uzaklaşmasını ifade eder. Bazı uzaklaşma şirket markası ve UX standardı nedeniyle bilinçlidir. Sorun hangi değişikliklerin neden yapıldığının bilinmemesidir. Local customization comment, commit history veya ADR ile açıklanabilir. Periyodik audit gereksiz farkları temizleyerek future update maliyetini azaltır.

Design System Versioning Stratejisi

Versioning tasarım sistemi değişikliklerinin consumer ekipler tarafından öngörülebilir biçimde alınmasını sağlar. Package modeli kullanılıyorsa semantic versioning doğrudan uygulanabilir, registry ve monorepo modellerinde de lifecycle ve breaking change kavramları yine gereklidir. Patch, minor ve major ayrımı yalnızca teknik değişikliğe değil consumer etkisine göre değerlendirilmelidir. Component deprecation aniden removal yapmak yerine işaretleme, migration guide ve belirli deadline aşamalarından geçmelidir. Changelog ve release notes ürün ekiplerinin update kararını hızlı verebilmesi için anlaşılır tutulmalıdır.

Semantic Versioning

Semantic Versioning major, minor ve patch seviyeleriyle consumer etkisini ifade eden ortak sözleşme sunar. Breaking API değişiklikleri major seviyeye, backward-compatible yeni özellikler minor seviyeye, bug fix'ler patch seviyeye alınabilir. Her görsel değişikliğin teknik olarak patch sayılması doğru olmayabilir çünkü kullanıcı deneyimini önemli ölçüde etkileyebilir. Şirket kendi versioning yorumunu kısa politika olarak yazmalıdır. Registry modelinde item metadata veya release tag'leri benzer mantıkla kullanılabilir.

Patch Release

Patch release backward-compatible hata ve küçük iyileştirmeler için kullanılabilir. Accessibility veya browser bug fix'i bu kategoriye girebilir. Görsel fark bekleniyorsa release note'ta belirtilmelidir. Consumer testleri yine çalıştırılmalıdır. Patch'in düşük riskli olması test gerektirmediği anlamına gelmez.

Minor Release

Minor release yeni component, variant veya backward-compatible API ekleyebilir. Consumer mevcut kodu değiştirmeden update edebilmelidir. Yeni özellik dokümantasyon ve Storybook örneğiyle yayınlanmalıdır. Adoption zorunlu olmayabilir. Minor release'lerin çok sık çıkması ekiplerin update yorgunluğu yaşamasına neden olabileceği için release ritmi dengelenmelidir.

Major Release

Major release breaking component API veya token değişikliklerini içerir. Migration guide zorunlu hale gelir. Büyük değişiklik öncesi RFC veya beta sürümü ürün ekiplerinden feedback almak için kullanılabilir. Consumer migration effort önceden tahmin edilmelidir. Major release yalnızca temizlik amacıyla sık yapılmamalıdır.

Component Deprecation

Deprecation component'in artık yeni kullanım için önerilmediğini ancak geçici olarak desteklenmeye devam ettiğini belirtir. Replacement component veya pattern açıkça gösterilmelidir. IDE warning veya development log gibi teknik uyarılar eklenebilir. Yeni kullanım lint ile engellenebilir. Removal öncesinde adoption metriği izlenerek kalan consumer'lar belirlenebilir.

Deprecated İşareti

Deprecated component Storybook ve API dokümantasyonunda açıkça işaretlenmelidir. Figma library içinde de aynı durum görünür olmalıdır. TypeScript JSDoc deprecation etiketi IDE seviyesinde uyarı sağlayabilir. Yeni ürünlerin deprecated component kullanması engellenmelidir. İşaretleme tek başına yeterli değildir, replacement yolu da gösterilmelidir.

Migration Guide

Migration Guide eski component veya prop kullanımının yeni API'ye nasıl taşınacağını örneklerle gösterir. Basit before ve after snippet'leri çok değerlidir. Breaking davranış farkları açıkça belirtilmelidir. Büyük codebase için codemod sağlanabilir. Guide consumer ekibin design system core team'e sürekli soru sormadan migration yapabilmesini hedeflemelidir.

Removal Deadline

Removal deadline deprecation'ın süresiz kalmasını önler. Tarih veya major version hedefi açıkça duyurulabilir. Kalan kullanımlar dashboard ile izlenebilir. Kritik consumer geçiş yapamıyorsa istisna gerekçesi ve yeni plan belirlenir. Removal ancak migration için gerçekçi zaman sağlandıktan sonra yapılmalıdır.

Changelog Yönetimi

Changelog consumer açısından önemli değişiklikleri tek yerde özetlemelidir. Her release için added, changed, fixed ve deprecated gibi kategoriler kullanılabilir. Issue veya migration guide bağlantıları eklenebilir. Otomatik commit listesi doğrudan kullanıcı dostu changelog yerine geçmez. Core team değişikliğin consumer etkisini anlaşılır dille yazmalıdır.

Design System Governance Modeli

Governance, design system içinde kimin karar verdiğini, yeni component'in nasıl önerildiğini ve hangi kalite şartlarının release için gerekli olduğunu belirler. Merkezi ekip bütün UI kararlarını tek başına vermeye çalışırsa ürün ekiplerinde darboğaz oluşabilir. Tam serbest modelde ise component fork ve pattern farklılığı hızla büyür. Core team ile açık contribution modeli arasında denge kurulmalıdır. RFC, code review, design review ve acceptance criteria gibi süreçler büyük değişikliklerin ortak değerlendirilmesini sağlarken küçük bug fix'lerin gereksiz bürokrasiye takılmaması önemlidir.

Design System'ın Sahibi Kim Olmalı?

Design system sahipliği yalnızca frontend veya yalnızca tasarım ekibinde kalmamalıdır. Tasarım ve mühendislik kararları birbirine bağlıdır. Product Designer, Design Engineer ve Frontend Engineer gibi roller ortak core team içinde çalışabilir. Accessibility sorumluluğu da açıkça atanmalıdır. Organizasyon küçükse roller aynı kişilerde birleşebilir, ancak sorumluluk alanları yine tanımlı olmalıdır.

Core Team Yapısı

Core team design system roadmap, quality standard ve contribution review süreçlerini yönetir. Ekip ürün ekiplerinden kopuk ayrı platform grubu haline gelmemelidir. Düzenli product feedback ve adoption verisi takip edilmelidir. Core team bütün component'leri kendisi yazmak zorunda değildir. Katkıları değerlendiren ve sistem bütünlüğünü koruyan enablement rolü daha ölçeklenebilir olabilir.

Product Designer

Product Designer component'in kullanım bağlamı, interaction ve görsel standardını temsil eder. Figma library ve design guideline sahipliğinde rol alabilir. Gerçek ürün ihtiyacının sistemde doğru karşılandığını değerlendirir. Developer API kararlarına UX açısından katkı verir. Tasarım değişikliğinin birden fazla ürün üzerindeki etkisini göz önünde bulundurur.

Design Engineer

Design Engineer tasarım ve frontend uygulaması arasında teknik köprü kurabilir. Token pipeline, Figma code mapping ve component prototyping gibi alanlarda değer üretir. Tasarım kararlarının kodda sürdürülebilir karşılığını değerlendirir. Motion ve responsive pattern gibi iki disiplinin kesiştiği alanlarda özellikle faydalıdır. Her organizasyonda ayrı rol olmak zorunda değildir, ancak bu sorumluluk mutlaka birileri tarafından sahiplenilmelidir.

Frontend Engineer

Frontend Engineer component architecture, TypeScript API, performance ve test altyapısını yönetir. Upstream Shadcn değişikliklerini değerlendirebilir. Consumer feedback üzerinden API'nin gerçek kullanımını gözlemler. Package veya registry distribution süreçlerine katkı verir. Code review standardının design system genelinde uygulanmasını sağlar.

Accessibility Owner

Accessibility Owner bütün component'lerin WCAG ve şirket standardına uygunluğunu takip eder. Otomatik test altyapısını ve manuel review checklist'lerini geliştirebilir. Yeni pattern'lerde keyboard ve screen reader davranışını değerlendirir. Bu sorumluluk tek kişinin bütün accessibility işini yapması anlamına gelmez. Ama konu sahipsiz kalmadığı için kalite standardı daha tutarlı uygulanır.

Component Öneri Süreci

Ürün ekibi yeni component ihtiyacını kısa proposal ile sunabilir. Problem, mevcut alternatifler ve tekrar eden kullanım örnekleri açıklanmalıdır. Core team önce mevcut component ile çözülüp çözülemeyeceğini değerlendirir. Gerçek ortak ihtiyaç varsa contributor geliştirmeyi üstlenebilir. Bu model design system ekibinin bütün ihtiyaçları kendisinin keşfetmesini beklemekten daha ölçeklenebilirdir.

RFC Süreci

RFC büyük API, token veya architecture değişikliklerinde ortak değerlendirme sağlar. Problem, seçenekler, öneri ve migration etkisi yazılabilir. Her küçük bug için RFC gerekmez. Belirli süre açık feedback toplanır. Karar sonrasında document decision history olarak saklanabilir.

Code Review

Design system code review normal product code review'dan daha geniş consumer etkisi düşünmelidir. API stability, accessibility, bundle size ve extension davranışı değerlendirilir. Reviewer mümkünse core team ve contributor ekipten dengeli seçilebilir. Test ve story değişiklikle birlikte gelmelidir. Public API change'leri özellikle dikkatle incelenmelidir.

Design Review

Design review component'in görsel değerinden çok interaction ve pattern tutarlılığını değerlendirmelidir. Figma variant ve token kullanımı kontrol edilir. Existing component ile gereksiz duplication olup olmadığı incelenir. Responsive ve error state'ler review kapsamına alınmalıdır. Approval sonrasında code implementation ile drift oluşmaması için designer development sürecinde de erişilebilir olmalıdır.

Component Acceptance Criteria

Stable component için dokümantasyon, accessibility, tests, Figma eşleşmesi ve API review gibi minimum kriterler belirlenebilir. Experimental component daha düşük eşikle yayınlanabilir. Acceptance listesi kaliteyi kişiler arası yorumdan çıkarır. Her component için aynı ağırlıkta yüzlerce kontrol gerekmemelidir. Risk ve complexity seviyesine göre kriter derinliği ayarlanabilir.

Component Lifecycle Nasıl Yönetilmeli?

Component lifecycle yeni fikrin doğrudan stable API olarak yayınlanmasını önler. Proposed, Experimental, Beta, Stable, Deprecated ve Removed gibi aşamalar risk ve beklentiyi açık hale getirir. Product ekipleri Experimental component'in değişebileceğini bilir. Stable seviyesine çıkmak için adoption, test ve accessibility gibi kalite kriterleri aranabilir. Lifecycle hem component keşfini hızlandırır hem de design system'in API değişikliğinden korkarak hiç yenilik yapamaması problemini azaltır.

Proposed

Proposed aşamasında yalnızca problem ve olası çözüm tanımlanır. Component henüz kullanıma hazır değildir. Tekrar eden kullanım örnekleri toplanabilir. Existing component veya pattern ile çözüm olup olmadığı incelenir. Proposal kabul edilirse prototip geliştirme aşamasına geçilir.

Experimental

Experimental component sınırlı gerçek kullanım için yayınlanabilir. API değişebilir ve backward compatibility garantisi düşük olabilir. Dokümantasyonda bu durum açıkça belirtilmelidir. Bir veya iki product ekibi feedback sağlayabilir. Kullanım verisi Beta kararını destekler.

Beta

Beta component API'si büyük ölçüde şekillenmiş ancak geniş production doğrulaması henüz tamamlanmamış olabilir. Test ve accessibility seviyesi Experimental'dan daha yüksek olmalıdır. Consumer feedback toplanır. Breaking change ihtimali azalır ancak tamamen ortadan kalkmayabilir. Stable kriterleri için açık eksikler takip edilmelidir.

Stable

Stable component production kullanım için önerilen ve güçlü backward compatibility beklentisi taşıyan seviyedir. Storybook, test, accessibility ve design guideline tamamlanmış olmalıdır. Public API değişiklikleri semantic versioning kurallarına uymalıdır. Ownership ve support modeli bellidir. Yeni product ekipleri varsayılan olarak stable component tercih etmelidir.

Deprecated

Deprecated component yeni kullanım için önerilmez ancak mevcut consumer'lara migration süresi tanır. Replacement yolu açıkça gösterilmelidir. Figma ve code tarafı aynı deprecation durumunu taşımalıdır. Yeni importlar lint ile engellenebilir. Removal için deadline ve kalan kullanım metriği izlenmelidir.

Removed

Removed component artık design system dağıtımında bulunmaz. Öncesinde consumer migration tamamlanmış olmalıdır. Changelog ve major release note içinde removal açıkça belirtilmelidir. Registry item veya package export kaldırılır. Eski doküman gerekirse archive olarak saklanabilir.

Her Aşama İçin Kalite Kriterleri

Lifecycle aşamalarına göre farklı kalite eşikleri tanımlamak geliştirme hızını ve güvenilirliği dengeler. Experimental aşamada temel accessibility ve story yeterliyken Stable için visual regression, interaction test ve kapsamlı docs zorunlu olabilir. Security kritik component'lerde daha yüksek eşik uygulanabilir. Kriterler checklist ve CI ile mümkün olduğunca otomatik doğrulanmalıdır. Aşamalar yalnızca etiket değil gerçek kalite beklentisi taşımalıdır.

Accessibility Şirket Standardının Bir Parçası Nasıl Yapılır?

Accessibility design system'in sonradan kontrol edilen özelliği değil component acceptance standardının parçası olmalıdır. WCAG gereksinimleri, keyboard navigation, focus management, screen reader desteği, contrast ve reduced motion gibi konular primitive seviyesinde çözülürse bütün consumer ürünler bundan faydalanır. Storybook accessibility addon axe-core tabanlı otomatik kontrol sunuyor, ancak dokümantasyon otomatik araçların bütün WCAG problemlerini yakalayamadığını da açıkça ortaya koyuyor. :contentReference[oaicite:30]{index=30} Bu nedenle automated test, manual keyboard test ve gerektiğinde screen reader review birlikte kullanılmalıdır. Accessibility owner ve CI quality gate bu standardın yalnızca iyi niyetli öneri olarak kalmasını önler.

WCAG Gereksinimleri

Şirket hangi WCAG seviyesini hedeflediğini açıkça belirlemelidir. Bu hedef design system component acceptance kriterlerine çevrilmelidir. Contrast, focus, labels ve semantics gibi alanlar primitive seviyesinde kontrol edilebilir. Product-level content ve workflow erişilebilirliği yine consumer ekip sorumluluğundadır. Design system ortak foundation sağlarken bütün uygulamanın erişilebilirliğini tek başına garanti etmez.

Keyboard Navigation

Bütün interactive component'ler mouse olmadan kullanılabilmelidir. Tab sırası mantıklı ilerlemelidir. Custom widget'larda arrow, Escape ve Enter davranışları ilgili interaction pattern'e uygun olmalıdır. Visible focus indicator korunmalıdır. Storybook interaction testi yardımcı olabilir, ancak gerçek keyboard kullanımıyla manuel doğrulama yapılması yine önemlidir.

Focus Management

Dialog açıldığında focus uygun alana taşınmalı ve kapandığında tetikleyici öğeye geri dönmelidir. Error veya step değişimlerinde focus davranışı kullanıcıyı kaybettirmemelidir. Programatik focus yalnızca gerçekten gerekli durumlarda kullanılmalıdır. Composite component'ler bu davranışı consumer'a bırakmak yerine güvenli default sağlayabilir. Focus regression test senaryoları kritik component'lerde yazılabilir.

Screen Reader Desteği

Semantic HTML screen reader desteğinin en güçlü temelidir. Gereksiz ARIA kullanımı native semantics'i bozabilir. Icon-only action, custom Select ve Dialog gibi component'ler doğru accessible name ve role ilişkilerine sahip olmalıdır. Otomatik testler bazı hataları yakalar. Karmaşık interaction'lar gerçek screen reader ile dönemsel olarak doğrulanmalıdır.

Color Contrast

Text, icon ve interactive state'ler için yeterli contrast korunmalıdır. Semantic token çiftleri merkezi test edilirse çok sayıda component aynı anda güvence altına alınır. Hover ve disabled state de kontrol edilmelidir. Renk tek başına hata veya başarı anlamı taşımamalıdır. Multi-brand theme'lerde her marka palette'i ayrı accessibility testinden geçmelidir.

Reduced Motion

Kullanıcının reduced motion tercihi animation ve transition sisteminde dikkate alınmalıdır. Büyük hareket veya sürekli animation belirli kullanıcılar için sorun oluşturabilir. Motion token sistemi bu tercihe merkezi cevap verebilir. Tamamen bütün feedback'i kaldırmak yerine daha düşük hareketli alternatif sağlanabilir. Component dokümantasyonu hangi animation'ın reduced mode altında nasıl değiştiğini açıklayabilir.

Accessible Form Errors

Form error mesajı ilgili input ile programatik olarak ilişkilendirilmelidir. Renk dışında metin veya ikon desteği kullanılmalıdır. Submit sonrasında kullanıcı hangi alanların hatalı olduğunu anlayabilmelidir. Error summary uzun formlarda faydalı olabilir. Screen reader announcement davranışı gerçek senaryoda test edilmelidir.

Automated Accessibility Testing

Automated testing temel semantic ve contrast sorunlarının erken yakalanmasını sağlar. Storybook, axe ve Playwright benzeri araçlar farklı test seviyelerinde birlikte kullanılabilir. Otomatik test sonucunun temiz olması tam erişilebilirlik garantisi değildir. Manuel keyboard ve assistive technology testi hala gereklidir. En güçlü model otomasyonu sürekli ilk filtre, manuel review'ı kritik release kontrolü olarak kullanır.

Storybook

Storybook component'i bağımsız render ettiği için accessibility testleri için uygun fixture ortamıdır. Accessibility addon her story üzerinde otomatik kontroller çalıştırabilir. :contentReference[oaicite:31]{index=31} Component variant'ları ayrı story olduğu için hata hangi durumda oluşuyor kolayca görülebilir. CI entegrasyonu regression'ı erken yakalar. Designer da panel sonucunu component review sırasında görebilir.

axe

axe-core otomatik accessibility rule kontrolleri için yaygın kullanılan engine'dir. Storybook accessibility addon da bu altyapıyı temel alır. :contentReference[oaicite:32]{index=32} Test sonucu doğrudan çözüm yerine hangi rule'un ihlal edildiğini gösterir. Bazı kontroller manuel doğrulama gerektirebilir. Şirket false positive veya bilinçli istisnaları kayıtlı politika ile yönetmelidir.

Playwright

Playwright gerçek browser akışlarında accessibility ve keyboard davranışlarını test etmek için kullanılabilir. Component seviyesindeki kontrolleri product flow seviyesinde tamamlar. Dialog açma, form submit veya focus return gibi davranışlar uçtan uca doğrulanabilir. Testler kritik browser çeşitlerini kapsayabilir. Design system örnek uygulaması üzerinde merkezi smoke suite oluşturmak da mümkündür.

RTL ve Uluslararasılaştırma Desteği

Global veya çok dilli ürünlerde component'lerin yalnızca İngilizce ve soldan sağa layout üzerinde test edilmesi yeterli değildir. RTL, locale-aware date ve number formatting, uzun çeviriler ve farklı para birimleri UI yapısını etkiler. Design system component'leri sabit metin uzunluğu varsaymamalıdır. Icon yönü ve layout sırası RTL theme veya direction context üzerinden uyarlanabilir. Localization kaynaklı regression'lar Storybook ve screenshot testleriyle erken görünür hale getirilebilir.

RTL Layout

RTL desteği yalnızca text-align right uygulamak değildir. Flex direction, icon placement ve navigation davranışları etkilenebilir. CSS logical properties kullanımı layout'u direction bağımsız hale getirebilir. Direction context story seviyesinde test edilmelidir. Her ikon aynalanmamalıdır çünkü bazı semboller yön bağımsız semantic taşır.

Locale-Aware Formatting

Tarih, sayı ve para birimi gösterimi locale göre değişmelidir. Component içine hardcoded format string yazmak yerine ortak formatting utility kullanılabilir. Browser Intl API veya seçilen localization altyapısı bu işi destekler. UI component yalnızca formatted değeri göstermekle yetinebilir. Format davranışının business kurallarıyla karışmaması gerekir.

Tarih ve Saat

Tarih ve saat gösterimi timezone nedeniyle özellikle kurumsal ürünlerde hata kaynağı olabilir. Kullanıcı locale'i ile veri timezone'u ayrı kavramlardır. Date Picker'ın input formatı ve API formatı açıkça ayrılmalıdır. Relative time kullanımının hangi ekranda uygun olduğu guideline ile belirlenebilir. Test suite farklı timezone örnekleri içermelidir.

Sayı ve Para Birimi

Binlik ayırıcı, ondalık karakter ve para birimi sembol konumu locale'e göre değişir. Component içinde string birleştirmek yerine locale-aware formatter kullanılmalıdır. Finansal değerlerde precision business requirement ile belirlenmelidir. Negatif ve büyük değer layout testine dahil edilmelidir. Table column alignment farklı formatlarda bozulmamalıdır.

Uzun Metinlerde Component Dayanıklılığı

Çeviri metni kaynak dilden önemli ölçüde daha uzun olabilir. Button, Tab ve Card title sabit width varsayımıyla kırılmamalıdır. Text wrap, truncation ve tooltip kararları UX standardına göre verilmelidir. Storybook içinde uzun pseudo-localized metin kullanılabilir. Bu test responsive tasarım problemlerini de erken ortaya çıkarır.

Çeviri Kaynaklı Layout Regression'ları

Localization sonrası layout hataları visual regression testleriyle görünür hale getirilebilir. Pseudo-locale bütün metinleri uzatarak component dayanıklılığını test etmek için yararlıdır. RTL ile uzun text testinin birlikte yapılması özellikle değerlidir. Screenshot diff bütün çevirileri test etmez, ancak sistematik layout bozulmalarını yakalar. Tasarım sistemi ürün ekiplerine localization-ready component sağladığında sonradan yapılan düzeltme miktarı azalır.

Design System Test Stratejisi

Design system test stratejisi yalnızca unit test üzerine kurulamaz çünkü component'lerin önemli değeri görsel ve etkileşimsel davranıştan gelir. Unit, interaction, accessibility, visual regression, cross-browser, responsive ve consumer contract testleri farklı riskleri kapsar. Her component için bütün test türlerini aynı yoğunlukta uygulamak gereksiz olabilir. Primitive ve yüksek kullanımlı component'ler daha güçlü test kapsamına sahip olmalıdır. Test piramidi yerine risk bazlı test matrisi oluşturmak design system bakım maliyetini dengeli tutar.

Unit Test

Unit test helper function, variant mapping veya saf component logic için uygundur. Kullanıcı tarafından gözlemlenmeyen implementation detail'leri aşırı test etmek refactor maliyetini artırır. Kritik state dönüşümleri ve utility davranışları test edilebilir. UI rendering için interaction veya component test daha anlamlı olabilir. Unit test hızlı geri bildirim katmanı olarak kullanılmalıdır.

Interaction Test

Interaction test kullanıcı davranışını component seviyesinde doğrular. Click, typing, open veya selection akışları test edilebilir. Storybook story'leri bu testler için doğal fixture olabilir. :contentReference[oaicite:33]{index=33} Accessibility role ve visible text üzerinden assertion yapmak implementation bağımlılığını azaltır. Composite component'lerde interaction test özellikle değerlidir.

Accessibility Test

Accessibility test otomatik rule kontrolleri ve manuel behavior testlerini birleştirir. Axe tabanlı kontrol temel semantic ve contrast sorunlarını yakalayabilir. Keyboard flow ayrı test edilmelidir. Stable lifecycle aşamasına geçişte accessibility kriterleri zorunlu olabilir. Yeni variant eklenirken yalnızca default component'in eski testine güvenilmemelidir.

Visual Regression Test

Visual regression screenshot farkları üzerinden istemeden oluşan görsel değişiklikleri yakalar. Token ve CSS değişikliği birçok component'i etkilediği için design system'de özellikle değerlidir. Her pixel farkı gerçek bug olmayabilir. Onay sürecinde intentional design change ayrıştırılmalıdır. Stable story seti test fixture olarak kullanılabilir.

Cross-Browser Test

Browser'lar form control, focus ve layout davranışlarında farklılık gösterebilir. Kritik component'ler desteklenen browser matrisi üzerinde test edilmelidir. Her story'yi her browser'da çalıştırmak maliyetli olabilir. Riskli primitive ve regression geçmişi bulunan alanlara öncelik verilebilir. CI ile periyodik cross-browser suite dengeli çözüm sağlar.

Responsive Test

Responsive test component'in farklı container ve viewport büyüklüklerinde bozulmadığını doğrular. Özellikle Navigation, Table ve Form pattern'lerinde önemlidir. Sadece breakpoint screenshot yerine interaction davranışı da kontrol edilmelidir. Container query kullanılan component'ler uygun wrapper senaryolarında test edilmelidir. Uzun content ile responsive test birlikte yürütülebilir.

Consumer Contract Test

Consumer Contract Test design system public API'sinin gerçek uygulamaları kırmadığını doğrular. Monorepo içinde affected app build ve typecheck kolayca çalıştırılabilir. Package modelinde örnek fixture uygulamalar kullanılabilir. Registry component'lerinde install smoke test yapılabilir. Bu testler yalnızca component'in kendi içinde doğru olduğunu değil tüketim sözleşmesinin de korunduğunu gösterir.

Visual Regression Testing Nasıl Kurulur?

Visual regression testing design system değişikliklerinin component görünümünü beklenmedik biçimde bozup bozmadığını otomatik screenshot karşılaştırmasıyla değerlendirir. Storybook story'leri deterministik component state'leri sağladığı için güçlü kaynak olabilir. Theme, viewport ve interaction state kombinasyonları önceliklendirilmelidir. Her küçük animation veya timestamp farkı testleri gürültülü hale getirebilir, bu nedenle fixture'lar stabil tutulmalıdır. Tasarım değişikliği bilinçliyse screenshot update yalnızca geliştirici tarafından otomatik kabul edilmemeli ve design review süreciyle bağlantılı olmalıdır.

Storybook Snapshot Yaklaşımı

Storybook story'leri component'in belirli props ve context ile tekrar üretilebilir durumunu tanımlar. Bu durum visual snapshot için iyi temel oluşturur. Default ve kritik variant story'leri test setine alınabilir. Dynamic data sabit fixture ile kontrol edilmelidir. Story değişikliği de snapshot review kapsamında değerlendirilmelidir.

Component Screenshot Testleri

Screenshot test component'in gerçek browser render çıktısını karşılaştırır. Font yükleme ve animation gibi nondeterministic alanlar stabilize edilmelidir. Küçük pixel farkları threshold ile yönetilebilir. Büyük layout değişikliği hızlıca görünür olur. Test sonucu developer ve designer için görsel diff sunmalıdır.

Dark / Light Mode Testleri

Her kritik component hem light hem dark theme altında screenshot alınabilir. Token değişiklikleri iki tema üzerinde aynı anda doğrulanır. Sadece bir theme'deki border veya contrast hatası böylece yakalanır. Multi-brand sistemde bütün markaları her PR'da test etmek maliyetli olabilir. Risk bazlı smoke set ve periyodik full matrix kullanılabilir.

Farklı Viewport'lar

Desktop, tablet ve mobile gibi anlamlı viewport'lar test matrisi oluşturabilir. Component'in gerçekten desteklediği responsive davranışa göre sayı sınırlanmalıdır. Her pixel genişliği test etmek gerekli değildir. Boundary breakpoint değerleri özellikle önemlidir. Container-based component'ler viewport yerine wrapper size üzerinden de test edilmelidir.

Tasarım Değişikliklerinde Onay Süreci

Visual diff intentional ise design approval gerekir. PR içinde before ve after screenshot gösterilebilir. Designer değişikliğin Figma ve token standardıyla uyumunu kontrol eder. Approved diff baseline'a alınır. Bu süreç kazara UI değişikliğinin “snapshot güncelledim” yaklaşımıyla production'a taşınmasını önler.

Eski UI Library'den Shadcn UI'a Nasıl Geçilir?

Legacy UI library'den Shadcn tabanlı şirkete özel sisteme geçiş bütün component'leri bir anda değiştirmek yerine ölçümlü migration olarak planlanmalıdır. İlk olarak mevcut component envanteri, kullanım sıklığı, duplicate yapılar ve token farklılıkları çıkarılır. Ardından eski ile yeni component mapping hazırlanır ve düşük riskli pilot alan seçilir. Strangler Pattern benzeri yaklaşım yeni ekranlarda yeni sistemi kullanırken eski ürünün kademeli dönüşmesine izin verir. Migration tamamlanma kriteri yalnızca eski package'ın kaldırılması değil, visual consistency, accessibility ve adoption hedeflerinin karşılanması olmalıdır.

Mevcut Component Envanterini Çıkarmak

İlk adım repository'lerde hangi UI component'lerin bulunduğunu ve nerelerde kullanıldığını anlamaktır. Import analizi otomatik script ile yapılabilir. Benzer Button veya Modal implementasyonları gruplanabilir. Her component'in owner ve kullanım durumu belirlenebilir. Bu envanter migration scope'unun gerçek büyüklüğünü gösterir.

Kullanım Sıklığını Ölçmek

En çok kullanılan component'leri bilmek migration önceliğini belirlemeye yardımcı olur. Button, Input ve FormField gibi yüksek kullanım parçaları geniş etki yaratır. Ancak çok kritik ve riskli component'i ilk pilot seçmek doğru olmayabilir. Kullanım sıklığı ile migration kolaylığı birlikte değerlendirilmelidir. Düşük kullanılan component'ler bazen tamamen kaldırılabilir.

Component Mapping Oluşturmak

Legacy component ile yeni sistem karşılığı tablo halinde eşleştirilebilir. Doğrudan karşılığı olmayan parçalar belirlenir. API farkı ve migration notu eklenebilir. Aynı eski component'in birkaç farklı yeni pattern'e ayrılması gerekebilir. Mapping product ekiplerinin migration planını daha doğru oluşturmasını sağlar.

Token Mapping

Eski color, spacing ve typography değerleri yeni semantic token sistemine eşlenmelidir. Birebir karşılık bulunmadığında hangi değerlerin standardize edileceği design review ile kararlaştırılır. Hardcoded değerler migration sırasında görünür hale gelir. Token mapping visual değişikliğin neden oluştuğunu açıklar. Bu adım atlanırsa yeni component'ler bile eski rastgele değerleri taşımaya devam edebilir.

İlk Pilot Component'leri Seçmek

Pilot için sık kullanılan ancak yönetilebilir complexity'ye sahip component seçilebilir. Button ve Input iyi başlangıç olabilir. Gerçek bir ürün ekranında kullanım test edilmelidir. Developer experience, visual uyum ve migration effort ölçülür. Pilot sonucu architecture ve tooling kararları büyük rollout öncesinde düzeltilir.

Strangler Pattern ile Kademeli Migration

Kademeli migration eski ve yeni sistemi belirli süre birlikte çalıştırır. Yeni feature'lar yeni design system ile geliştirilir. Mevcut ekranlar fırsat oldukça taşınır. Legacy component'e yeni özellik eklemek sınırlanabilir. Bu yöntem büyük tek seferlik release riskini azaltır.

Legacy Component'leri Deprecated Etmek

Yeni karşılık stable olduğunda legacy component deprecated olarak işaretlenebilir. Yeni importlar lint ile engellenebilir. Migration guide consumer ekiplere sunulur. Existing kullanım belirli deadline'a kadar desteklenir. Adoption dashboard kalan migration miktarını gösterir.

Migration Tamamlanma Kriterleri

Migration yalnızca eski dependency package.json'dan silindiğinde tamamlanmış sayılmamalıdır. Hardcoded token kullanım oranı, legacy import sayısı ve visual regression seviyesi kontrol edilmelidir. Figma library de yeni sistemle uyumlu olmalıdır. Product ekiplerinin documentation ve contribution süreçlerini kullanabiliyor olması önemlidir. Son audit tamamlandıktan sonra legacy kod ve docs temizlenebilir.

Shadcn UI Migration'ında Sık Yapılan Hatalar

Shadcn migration sırasında en büyük hata hazır component'leri yeni theme ile kopyalamanın design system dönüşümünü tamamladığını düşünmektir. Token katmanı, governance, documentation ve update stratejisi kurulmadığında yeni sistem kısa süre içinde eski dağınıklığın farklı biçimine dönüşebilir. Bütün component'leri aynı sprintte değiştirmek regression riskini yükseltir. Her product ekibinin base component'i kendi ihtiyacına göre fork etmesine izin vermek ortak standardı kaybettirir. Migration teknik component replacement kadar süreç ve sahiplik dönüşümü olarak planlanmalıdır.

Tüm Component'leri Bir Anda Değiştirmek

Big-bang migration geniş regression yüzeyi oluşturur. Product ekipleri aynı anda feature geliştirmeyi durdurmak zorunda kalabilir. Hataların hangi component değişikliğinden geldiğini bulmak zorlaşır. Kademeli migration daha fazla süreye yayılsa da risk kontrolünü kolaylaştırır. Kritik deadline bulunan ürünlerde özellikle küçük batch tercih edilmelidir.

Default Shadcn Theme'i Şirket Tasarımı Sanmak

Default Shadcn theme iyi başlangıç örneğidir ancak şirketin marka ve UX standardını otomatik temsil etmez. Token, typography ve component hierarchy ayrıca tasarlanmalıdır. Ürünlerin tamamı örnek theme'e göre şekillenirse marka farklılaşması sınırlı kalır. Design review gerçek şirket ihtiyaçlarına dayanmalıdır. Shadcn altyapı, şirket tasarımı ise ürün stratejisinin parçası olarak görülmelidir.

Token Katmanı Oluşturmadan Component Özelleştirmek

Component dosyalarında doğrudan renk ve spacing değişikliği yapmak ilk aşamada hızlı görünür. Ancak her değişiklik local kaldığı için dark mode ve rebranding zorlaşır. Önce token mimarisi oluşturulmalıdır. Component customization semantic token kullanmalıdır. Bu temel kurulduğunda sonraki component'ler çok daha hızlı standartlaşır.

Her Ürün Ekibinin Component'i Fork Etmesine İzin Vermek

Fork özgürlüğü kısa vadede product velocity sağlayabilir. Uzun vadede aynı Button'ın onlarca versiyonu oluşur. Core API yetersizse contribution veya extension modeli kullanılmalıdır. Gerçek product-specific ihtiyaç local wrapper olarak kalabilir. Fork ancak bilinçli ve gerekçeli istisna olmalıdır.

className ile Kontrolsüz Override Yapmak

className ile bütün design system kararlarını override etmek component adoption metriğini yanıltıcı hale getirir. Görünüşte ortak Button kullanılırken gerçek UI tamamen farklı olabilir. Escape hatch politikasında layout ve limited styling sınırları belirlenmelidir. Hardcoded token override lint ile yakalanabilir. Sık override aynı ihtiyacı gösteriyorsa base API yeniden değerlendirilmelidir.

Dokümantasyon Yazmamak

Dokümantasyon yoksa geliştirici component API'sini source code okuyarak anlamak zorunda kalır. Designer kullanım kuralını bilmez. Yanlış variant ve custom wrapper sayısı artar. Storybook ve guideline migration ile birlikte hazırlanmalıdır. Docs sonradan yapılacak ayrı proje olarak bırakılmamalıdır.

Upstream Update Stratejisi Belirlememek

Shadcn copy modelinde update kararı şirkete aittir. Upstream fix'ler takip edilmezse önemli accessibility veya bug iyileştirmeleri kaçırılabilir. Tam overwrite yapmak da local customization'ı bozabilir. Diff ve patch süreci belirlenmelidir. Core team belirli release ritminde upstream değerlendirmesi yapmalıdır.

Çok Sayıda Ürün Ekibinde Tasarım Sistemi Nasıl Ölçeklenir?

Ürün ekibi sayısı arttıkça merkezi design system ekibinin her talebi tek başına geliştirmesi sürdürülemez hale gelir. Merkezi model başlangıçta consistency sağlar, federated model ürün bilgisini sisteme taşır, core plus contribution modeli ise bu iki yaklaşımı dengeler. Ürün ekipleri component ve pattern katkısı yapabilir, core team review ve quality standardı korur. Contribution guidelines ve cross-team review kritik hale gelir. Böylece design system yalnızca merkezi platform ekibinin roadmap'ine bağlı kalmadan şirket genelindeki gerçek ihtiyaçlarla gelişebilir.

Merkezi Model

Merkezi modelde design system component'lerinin ana geliştirme sorumluluğu tek core team'dedir. Consistency ve kalite kontrolü kolaydır. Küçük ve orta organizasyonda iyi çalışabilir. Ürün ekibi sayısı büyüdükçe talep kuyruğu oluşabilir. Core team'in product bağlamından uzaklaşmaması için düzenli feedback mekanizması gerekir.

Federated Model

Federated model farklı ürün ekiplerinin design system parçalarında daha fazla sahiplik almasını sağlar. Domain bilgisi doğrudan sisteme yansır. Ancak ortak standardı korumak daha fazla governance gerektirir. Token ve API kararları merkezi prensiplere bağlı kalmalıdır. Review ağı güçlü değilse component fragmentation riski oluşabilir.

Core + Contribution Model

Core plus contribution modelinde merkezi ekip roadmap ve kalite standardını yönetir, ürün ekipleri pull request yoluyla katkı sunar. Bu yaklaşım open source çalışma modeline benzer. Contribution template ve acceptance criteria süreci hızlandırır. Core team bütün kodu yazmak yerine review ve enablement yapar. Büyük organizasyonlarda dengeli ölçekleme modeli olabilir.

Product Team Katkıları

Product ekipleri gerçek ihtiyaçtan gelen component veya bug fix katkısını hazırlayabilir. Katkı design ve development owner tarafından desteklenebilir. Core team ortak kullanım ve API kalitesini değerlendirir. Gerekirse component önce Experimental olarak yayınlanır. Contributor ekibin bakım sorumluluğu belirli süre devam edebilir.

Contribution Guidelines

Contribution guideline yeni component'in nasıl önerileceğini ve hangi testlerin gerekli olduğunu açıklar. Figma, Storybook, test ve accessibility checklist içerebilir. Süreç çok ağır olursa ekipler local fork yoluna kaçar. Çok gevşek olursa kalite düşer. Guideline gerçek contributor feedback'iyle düzenli iyileştirilmelidir.

Cross-Team Review Süreci

Cross-team review component'in yalnızca tek ürün ihtiyaçlarına göre tasarlanmasını önler. Başka ürünlerden designer ve frontend engineer API'yi değerlendirebilir. Kullanım örnekleri ortaklaştırılır. Review toplantı olmak zorunda değildir, async RFC veya PR yorumlarıyla yürütülebilir. Karar süresi uzuyorsa belirli review deadline tanımlanmalıdır.

Tasarım Sistemi Kullanımını Nasıl Zorunlu Hale Getirebiliriz?

Design system adoption yalnızca “lütfen ortak component kullanın” mesajıyla sürdürülemez. ESLint, import rules, CI quality gate ve PR checklist ile bazı standartlar otomatik hale getirilebilir. Ancak her kuralın arkasında geliştiriciye daha iyi alternatif sunulmalıdır. Raw HTML veya hardcoded renk yasaklanırken gerekli component veya token bulunmuyorsa ekipler workaround üretir. Enforcement ile enablement dengesi kurulmalı, adoption verisi ve developer feedback düzenli izlenmelidir.

ESLint Kuralları

ESLint design system dışı import, hardcoded token ve belirli element kullanımını kontrol edebilir. Kural mesajı yalnızca hata vermemeli, doğru alternatifi göstermelidir. Autofix mümkün olduğunda developer experience iyileşir. Legacy code için yalnızca yeni değişikliklerde enforcement uygulanabilir. Rule set shared config package üzerinden bütün projelere dağıtılabilir.

Custom Component Import Kuralları

Product ekiplerinin design system iç dosyalarına doğrudan import yapması engellenebilir. Yalnızca public export path desteklenir. Bu sınır internal refactor yapmayı kolaylaştırır. Legacy package veya external UI importları da migration döneminde uyarılabilir. Import policy component ownership modelini kod seviyesinde güçlendirir.

Raw HTML Element Kullanımını Sınırlamak

Raw button veya input kullanımı design system component'inin sağladığı accessibility ve styling standardını atlayabilir. Lint bu elementleri belirli klasörlerde kısıtlayabilir. Ancak semantic HTML'in kendisi kötü değildir ve her div için wrapper component oluşturmak doğru olmaz. Yalnızca design system karşılığı gerçekten bulunan interactive elementlere odaklanılmalıdır. İstisna mekanizması açık olmalıdır.

Hardcoded Color Kontrolü

Hex, rgb veya raw palette utility kullanımı static analysis ile yakalanabilir. Semantic token kullanımı önerilir. Marketing veya data visualization gibi özel alanlar için kontrollü istisnalar gerekebilir. Yeni renk ihtiyacı varsa token proposal süreci bulunmalıdır. Bu kural dark mode ve multi-brand uyumluluğu doğrudan destekler.

CI Quality Gates

CI lint, typecheck, test, accessibility ve visual regression sonuçlarını release gate olarak kullanabilir. Her PR'da bütün test matrisi çalışmak maliyetli olabilir. Affected component analizi veya nightly full suite uygulanabilir. Stable package release daha güçlü gate'ten geçebilir. Quality gate hızlı geri bildirim sağlamalı ve gereksiz flaky testlerle ekip güvenini kaybetmemelidir.

Pull Request Checklist

PR checklist design system değişikliğinde Figma, docs, tests ve changelog gibi kolay unutulan alanları hatırlatır. Çok uzun checklist zamanla otomatik işaretlenen formaliteye dönüşebilir. Yalnızca gerçekten kritik maddeler tutulmalıdır. Otomatik doğrulanabilen kontroller CI'a taşınmalıdır. İnsan checklist'i semantic ve karar gerektiren konulara odaklanmalıdır.

Design System Adoption Nasıl Ölçülür?

Adoption metriği design system'in gerçekten ürünlerde kullanılıp kullanılmadığını gösterir. Component adoption rate, legacy kullanım oranı, coverage, duplicate component ve design-code mismatch gibi metrikler birlikte değerlendirilebilir. Tek yüksek kullanım oranı sistemin doğru kullanıldığını garanti etmez çünkü component sürekli className ile override ediliyor olabilir. Ekip memnuniyeti ve contribution süresi gibi nitel göstergeler de önemlidir. Ölçümün amacı ekipleri sıralamak değil sistemin hangi alanlarda kullanım engeli oluşturduğunu tespit etmektir.

Component Adoption Rate

Adoption Rate belirli UI kategorisinde ortak component'in ne kadar kullanıldığını gösterebilir. Import analizi otomatik yapılabilir. Yeni ürün ve legacy ürün ayrı değerlendirilmelidir. Hedef zaman içinde artan trend olabilir. Yüzde yüz adoption her product-specific ihtiyette gerekli değildir.

Legacy Component Kullanım Oranı

Legacy component import sayısı migration ilerlemesini görünür hale getirir. Yeni kullanım artıyorsa lint enforcement yetersiz olabilir. Eski kullanım sayısı sprint bazında takip edilebilir. Çok kullanılan legacy parça için codemod yatırımı gerekebilir. Oran sıfıra yaklaşınca removal planı aktive edilir.

Product Başına Design System Coverage

Coverage her ürünün ortak sistemden ne kadar yararlandığını gösterir. Button ve form gibi temel katmanlar yüksek coverage taşıyabilir. Product-specific visualization alanları doğal olarak düşük olabilir. Coverage kategorilere bölünürse daha anlamlı sonuç verir. Düşük coverage nedeni teknik engel mi yoksa gerçek ürün farklılığı mı ayrıca incelenmelidir.

Duplicate Component Sayısı

Repository'lerde tekrar eden benzer component sayısı design system fırsatlarını gösterir. Static analysis ve manuel inventory birlikte kullanılabilir. Her benzer isim gerçekten duplicate olmayabilir. Aynı interaction'ın farklı implementasyonları öncelikli incelenebilir. Duplicate sayısının azalması bakım maliyeti üzerinde doğrudan etki yaratabilir.

Tasarım–Kod Uyumsuzluk Sayısı

Design-code mismatch Figma'daki component ile production davranışının ayrıştığı durumları ölçebilir. Design QA veya visual audit sırasında kayıt tutulabilir. Sık mismatch belirli component API'sinin yetersiz olduğunu gösterebilir. İsim ve token eşleşmesi drift'i azaltır. Hedef bütün pixel farklarını sıfırlamak değil onaysız sistematik farkları azaltmaktır.

Ekip Memnuniyeti

Developer ve designer satisfaction düzenli kısa anketlerle ölçülebilir. Component bulma, dokümantasyon, update ve contribution deneyimi ayrı sorulabilir. Düşük memnuniyet adoption problemini açıklayan erken sinyal olabilir. Nitel yorumlar roadmap için değerlidir. Yalnızca sayısal skor yerine en sık tekrar eden engeller incelenmelidir.

Şirket İçi Tasarım Sisteminin ROI'si Nasıl Ölçülür?

Design system ROI yalnızca component geliştirme saatleriyle hesaplanmamalıdır. Feature geliştirme süresi, UI bug sayısı, tasarım revizyonu, duplicate kod, accessibility hata oranı ve yeni proje başlangıç süresi gibi etkiler birlikte incelenebilir. Migration öncesi baseline olmadan sonradan elde edilen kazanımı ölçmek zorlaşır. Pilot ekipler üzerinde önce ve sonra karşılaştırması yapılabilir. Tasarım sistemi yatırımının ilk aylarda core team maliyeti yaratacağı, faydanın ürün sayısı ve tekrar kullanım arttıkça büyüyeceği dikkate alınmalıdır.

Feature Development Süresi

Benzer UI feature'larının design system öncesi ve sonrası tamamlanma süresi karşılaştırılabilir. Form veya dashboard geliştirme örnekleri seçilebilir. Sadece coding değil design ve QA süresi de dahil edilmelidir. Product complexity farkı göz önünde bulundurulmalıdır. Trend uzun dönemde daha anlamlıdır.

UI Bug Sayısı

Common component kullanımı spacing, responsive ve interaction bug'larını azaltabilir. Bug tracker'da UI source kategorisi tutulabilir. Merkezi component bug'ı birden fazla ürünü etkileyebileceği için severity ayrıca değerlendirilmelidir. Fix'in bütün consumer'lara ulaşma süresi de önemlidir. Hedef yalnızca bug sayısını değil tekrar eden aynı bug sınıfını azaltmaktır.

Tasarım Revizyon Süresi

Designer ortak component kullandığında temel UI revizyonu daha hızlı olabilir. Yeni variant ihtiyacının design system sürecinden geçmesi başlangıçta ek zaman yaratabilir. Ancak sonrasında aynı karar bütün ürünlerde tekrar kullanılır. Design review süreleri baseline ile karşılaştırılabilir. Figma component adoption ölçümü bu veriyi destekler.

Tekrarlanan Component Sayısı

Duplicate component azalması doğrudan bakım yüzeyini küçültür. Aynı bug için birden fazla fix ihtiyacı ortadan kalkabilir. Repository inventory migration öncesi ve sonrası karşılaştırılabilir. Merkezi component sayısının artması tek başına başarı değildir. Gerçek duplicate implementasyonun azalması daha anlamlı ROI göstergesidir.

Accessibility Bug'ları

Primitive seviyesinde accessibility doğru çözüldüğünde birçok ürün aynı iyileştirmeyi tekrar kullanır. Audit bulgularındaki ortak form, button veya dialog hataları zaman içinde azalabilir. Automated test coverage metriği de izlenebilir. Product-level content hataları design system dışı ayrı kategori tutulmalıdır. Böylece ortak altyapının accessibility üzerindeki gerçek etkisi görünür olur.

Yeni Proje Başlatma Süresi

Design token, component, template ve config hazır olduğunda yeni frontend projesinin ilk production-ready ekranına ulaşma süresi kısalabilir. Starter veya monorepo template bunu destekler. Authentication veya business setup gibi design system dışı işleri ölçümden ayırmak gerekir. İlk hafta developer experience anketi alınabilir. Yeni ekip onboarding süresi de ROI içinde değerlendirilebilir.

Migration Öncesi ve Sonrası Karşılaştırma

Migration başlamadan baseline metrikleri toplanmalıdır. UI bug, development time ve duplicate count gibi değerler kayıt altına alınabilir. Sonrasında aynı ölçüm yöntemi korunmalıdır. Sadece başarılı örnekler seçilmemelidir. ROI raporu teknik ve ürün faydasını birlikte göstermelidir.

Shadcn UI ve Open Source İşbirliği

Shadcn/ui açık geliştirme modeli sayesinde şirket ekipleri upstream değişiklikleri izleyebilir, issue ve code katkılarıyla kullandıkları altyapının gelişimine dahil olabilir. Internal component ile genel amaçlı fix arasındaki sınır iyi belirlenmelidir. Şirkete özel brand veya business logic açık kaynağa taşınmamalı, ancak genel accessibility veya browser fix gibi katkılar uygun olduğunda upstream'e gönderilebilir. Bu yaklaşım uzun vadeli fork drift'ini de azaltabilir. Açık kaynak dependency governance ise kullanılan dış component ve package'ların güvenlik, lisans ve bakım durumunun şirket standardına göre izlenmesini sağlar.

Shadcn/ui Ekosisteminin Açık Kaynak Yapısı

Açık source erişimi component davranışının doğrudan incelenmesini sağlar. Şirket ekipleri yalnızca black-box package API'sine bağlı kalmaz. Update sırasında değişiklik nedeni repository üzerinden görülebilir. Bu şeffaflık debugging ve learning açısından değerlidir. Ancak açık kaynak kodun doğrudan production'a review yapılmadan alınması doğru değildir.

Upstream Değişiklikleri Takip Etmek

Core team release ve changelog değişikliklerini düzenli izleyebilir. Tailwind veya React uyumluluk değişimleri design system roadmap'ini etkileyebilir. Önemli değişiklik internal issue'ya dönüştürülür. Product ekiplerinin ayrı ayrı takip yapmasına gerek kalmaz. Merkezi değerlendirme sonucunda alınacak veya atlanacak değişiklik açıklanabilir.

Bug Fix'leri Topluluğa Geri Kazandırmak

Şirket genel bir bug'ı düzelttiyse uygun durumda upstream contribution yapabilir. Böylece sonraki official version'larda local patch taşıma ihtiyacı azalabilir. Fix şirket özel bilgisi içermemelidir. Minimal reproduction ve test hazırlanması contribution kalitesini artırır. Contribution süreci çalışanların açık kaynak politika ve güvenlik kurallarına uygun yürütülmelidir.

Internal Component ile Open Source Component Arasındaki Sınır

Business workflow ve marka özel component'ler internal kalmalıdır. Genel primitive veya accessibility fix'i open source katkıya daha uygun olabilir. Kod sahipliği ve lisans koşulları değerlendirilmelidir. Internal registry ile public dependency arasındaki sınır architecture dokümanında açıklanabilir. Böylece ekip hangi değişikliğin nerede yapılması gerektiğini daha hızlı anlar.

GitHub Issue ve Pull Request Süreçleri

Issue ve Pull Request süreçleri bug araştırması ve upstream katkı için kullanılabilir. Şirket çalışanı sensitive log veya internal screenshot paylaşmamalıdır. Reproduction generic örneğe indirgenmelidir. Upstream decision local roadmap'i bloke etmek zorunda değildir. Gerekirse internal patch uygulanır ve katkı sonucu ayrıca takip edilir.

Açık Kaynak Dependency Governance

Design system çok sayıda uygulama tarafından tüketildiği için eklenen her dependency geniş etki oluşturur. Yeni package için lisans, bakım durumu, bundle etkisi ve security değerlendirmesi yapılmalıdır. Dependency sayısını gereksiz büyütmemek önemlidir. Version update otomasyonu yardımcı olabilir. Critical dependency değişikliği consumer contract ve visual testlerle doğrulanmalıdır.

AI Kodlama Araçlarıyla Şirket Tasarım Sistemini Korumak

AI kodlama araçları hızlı UI üretirken şirket design system kurallarını bilmiyorsa raw Tailwind, hardcoded renk veya onaysız component üretme eğilimi gösterebilir. Bu nedenle design token sözlüğü, approved component listesi ve kullanım guideline'ları AI context'ine dahil edilmelidir. Private registry ve Storybook dokümantasyonu makine tarafından okunabilir şirket UI bilgisinin önemli kaynakları haline gelebilir. Üretilen kod normal code review, accessibility ve visual regression süreçlerinden geçmelidir. AI geliştirme hızını artırabilir, ancak design system governance kurallarını ortadan kaldırmak yerine bu kuralların daha otomatik ve görünür olmasını gerektirir.

AI'ın Raw Tailwind Üretmesini Önlemek

AI'a proje talimatında semantic class ve approved component kullanımı açıkça belirtilmelidir. Hardcoded color veya arbitrary value yasakları context içinde verilebilir. ESLint sonuçları AI feedback loop'una dahil edilebilir. Generated PR kural ihlali içeriyorsa CI bunu durdurur. Böylece model davranışına tamamen güvenmek yerine teknik enforcement korunur.

AI'a Design Token Kurallarını Öğretmek

Token naming ve kullanım örnekleri repository documentation içinde tutulabilir. AI yalnızca mevcut semantic token'ları kullanması gerektiğini öğrenebilir. Yeni token üretmesi gerekiyorsa proposal bırakması istenebilir. Figma ve code token mapping'i context olarak sağlanabilir. Bu yaklaşım generated code'un marka ve theme sistemine uyumunu artırır.

Yalnızca Onaylı Component'leri Kullandırmak

Approved component katalogu AI context içinde açık listelenebilir. Raw button yerine şirket Button import'u örneklerle gösterilebilir. Deprecated component'ler yasak olarak belirtilmelidir. Import lint kuralları teknik güvence sağlar. AI yeni component uydurmak yerine eksik ihtiyacı issue olarak işaretleyebilir.

Private Registry ile AI Context Sağlamak

Private registry şirket component metadata ve source yapısını merkezi noktada sunabilir. Yetkili internal AI tooling bu kaynaktan approved component listesini okuyabilir. Authentication ve code access politikaları korunmalıdır. Registry description ve meta alanları component discovery'yi iyileştirebilir. Böylece generated code güncel internal API'ye daha yakın olur.

Figma'dan Kod Üretiminde Design-System Kuralları

Figma component isimleri kod API'siyle eşleştiğinde design-to-code otomasyonu daha güvenilir olur. Generator raw style çıkarmak yerine component ve variant mapping kullanmalıdır. Unknown component durumunda fallback div üretmek yerine uyarı vermek daha güvenli olabilir. Token isimleri doğrudan semantic utility'lere çevrilebilir. Generated output yine human review ve visual testten geçmelidir.

AI Tarafından Üretilen UI İçin Review Süreci

AI generated UI diğer kodlardan daha düşük review standardına sahip olmamalıdır. Design system importları, accessibility ve responsive davranış kontrol edilmelidir. Screenshot diff designer tarafından değerlendirilebilir. Security veya dependency eklemeleri ayrıca incelenmelidir. AI hızından kazanılan sürenin bir bölümü kalite doğrulamasına ayrılmalıdır.

Shadcn UI İçin Hangi Frontend Teknolojileri Kullanılmalı?

Shadcn tabanlı şirket design systeminde teknoloji seçimi yalnızca popülerlik üzerinden yapılmamalıdır. TypeScript component API güvenliğini ve editor deneyimini güçlendirebilir, React component composition modeliyle uyumludur, Tailwind CSS semantic token utility'lerini hızlı tüketmeye imkan verir. Next.js belirli application türlerinde uygun olabilir, ancak design system mümkün olduğunca framework bağımlılığını sınırlamalıdır. Shadcn/ui güncel dokümantasyonu React 19 ve Tailwind CSS v4 desteğini doğrudan içeriyor. :contentReference[oaicite:34]{index=34} En iyi programlama dili aramak yerine şirketin ürün yapısı, ekip deneyimi, accessibility ve uzun vadeli bakım ihtiyaçlarına uyumlu teknoloji yığını seçilmelidir.

JavaScript mi TypeScript mi?

JavaScript hızlı başlangıç sağlayabilir, ancak büyük component API'sinde type güvenliği önemli değer üretir. TypeScript variant ve prop kombinasyonlarını compile aşamasında kontrol edebilir. Consumer ekip IDE autocomplete ile supported API'yi daha kolay keşfeder. Deprecated prop ve discriminated union gibi modeller migration'ı destekler. Şirket içi uzun ömürlü design system için TypeScript çoğu durumda güçlü tercih olur.

TypeScript'in Şirket İçi Component API'lerinde Avantajı

TypeScript public component API'sini açık sözleşmeye dönüştürür. Variant isimleri literal type olarak sınırlandırılabilir. Yanlış prop kombinasyonları union type ile engellenebilir. API documentation otomatik type bilgisinden yararlanabilir. Package veya registry consumer'larında refactor sırasında compile error erken geri bildirim sağlar.

React ve Next.js

React composition ve component modelinin Shadcn yaklaşımıyla doğal uyumu vardır. Next.js şirket ürünlerinde routing ve rendering altyapısı sağlayabilir. Ancak design system component'lerinin mümkün olduğu kadar framework-specific router veya server API'lerine bağımlı olmaması tekrar kullanımını artırır. Framework adapter'ları ayrı katmanda tutulabilir. Birden fazla React tabanlı application aynı core UI package'ı bu şekilde daha kolay tüketebilir.

Tailwind CSS

Tailwind CSS utility tabanlı styling modeli Shadcn component yapısının temel parçalarından biridir. Tailwind v4 theme variables design token'ları utility API'sine bağlamak için güçlü mekanizma sunuyor. :contentReference[oaicite:35]{index=35} Şirket arbitrary styling yerine semantic utility standardı oluşturmalıdır. Shared theme bütün ürünlere dağıtılabilir. Tailwind kullanımı design system yerine geçmez, yalnızca styling implementation aracıdır.

En İyi Programlama Dili Yerine Doğru Teknoloji Yığını Nasıl Seçilir?

Design system için teknoloji yığını consumer ürünlerle uyumluluk, ekip yetkinliği ve bakım maliyeti üzerinden seçilmelidir. Sadece benchmark veya trend kararı uzun vadede sorun yaratabilir. Type safety, test tooling, package dağıtımı ve accessibility library desteği birlikte değerlendirilmelidir. Mevcut frontend ekosistemi büyük geçiş maliyetini belirler. Küçük pilot gerçek developer experience hakkında teorik karşılaştırmadan daha doğru veri sağlar.

Design System Geliştiren Bir Frontend Yazılımcı Neleri Bilmeli?

Design system geliştiren frontend yazılımcının yalnızca React component yazabilmesi yeterli değildir. TypeScript API tasarımı, Tailwind ve CSS, accessibility, design tokens, Storybook, Figma, testing ve package dağıtımı birlikte çalışır. Component'in yüzlerce consumer tarafından kullanılacağını düşünerek backward compatibility ve documentation bilinci gerekir. Tasarımcıyla ortak dil kurabilmek en az teknik implementasyon kadar önemlidir. Güçlü design system engineer, yalnızca component üreten değil ürün ekiplerinin daha doğru component geliştirmesini sağlayan platform mantığıyla çalışır.

React Component Architecture

Composition, controlled state ve ref davranışı iyi anlaşılmalıdır. Component API küçük ve reusable tutulmalıdır. Context veya compound pattern ne zaman kullanılmalı bilinmelidir. Product business logic ile primitive UI ayrımı korunmalıdır. Performance optimizasyonu yalnızca gerçek ölçüm gereken yerlerde yapılmalıdır.

TypeScript

TypeScript public API sözleşmesini güvenli hale getirir. Generic, union ve utility type'ların nerede faydalı olduğu bilinmelidir. Aşırı type sihirbazlığı consumer experience'ı zorlaştırabilir. Type error mesajlarının anlaşılır olması önemlidir. API evolution sırasında backward compatibility düşünülmelidir.

Tailwind CSS

Tailwind utility yapısı kadar CSS cascade, specificity ve custom properties temelleri de bilinmelidir. Theme variable ve semantic token kullanımı anlaşılmalıdır. Arbitrary value kolaylığı kontrollü kullanılmalıdır. Responsive ve state variant'lar component architecture ile birlikte düşünülmelidir. Sadece class ezberlemek design system styling sorunlarını çözmek için yeterli değildir.

Accessibility

Semantic HTML ve keyboard interaction temel bilgi olmalıdır. ARIA yalnızca gerekli olduğunda kullanılmalıdır. Focus management ve form labeling pratik olarak test edilmelidir. Automated axe testlerinin sınırları bilinmelidir. Accessibility requirement design aşamasından başlayarak savunulmalıdır.

Design Tokens

Primitive ve semantic token farkı anlaşılmalıdır. Theme ve multi-brand planı token architecture kararlarını etkiler. Hardcoded styling yerine token API kullanılmalıdır. Figma mapping ve naming convention konusunda designer ile ortak çalışılmalıdır. Token breaking change'in geniş consumer etkisi olduğu unutulmamalıdır.

Storybook

Storybook yalnızca demo ekranı olarak değil test fixture ve documentation platformu olarak kullanılmalıdır. Story composition ve decorator yapısı bilinmelidir. Interaction ve accessibility addon'ları kalite sürecine entegre edilebilir. Story'ler deterministik tutulmalıdır. Product ekiplerine doğru kullanım örneği sunmak önemli sorumluluktur.

Figma Temelleri

Frontend geliştiricinin Figma'da component, variant ve variable kavramlarını anlaması handoff kalitesini artırır. Designer'ın kullandığı token yapısını okuyabilmelidir. Figma'da implementation ayrıntısı aramak yerine UX niyetini anlamalıdır. Design review'a erken katılmalıdır. Code-Figma drift fark edildiğinde ortak çözüm üretmelidir.

Testing

Unit, interaction, visual ve accessibility testlerinin hangi riski çözdüğü bilinmelidir. Her davranışı aynı test türünde doğrulamak gereksizdir. Stable primitive'lerde regression coverage yüksek olmalıdır. Flaky visual testler düzenli iyileştirilmelidir. Consumer impact testleri release öncesinde değerlendirilmelidir.

Package ve Registry Yönetimi

Design system engineer yalnızca source component'i değil dağıtım modelini de anlamalıdır. Semantic versioning, changelog ve dependency policy önemlidir. Registry copy modeli ile npm package modelinin farkları bilinmelidir. Authentication ve private distribution güvenlik gerektirir. Consumer update deneyimi platform tasarımının doğal parçasıdır.

Yazılım Topluluklarının Design System Yetkinliğine Katkısı

Design system geliştirme tasarım ve frontend disiplinlerini aynı problem etrafında buluşturduğu için topluluk çalışmaları açısından güçlü öğrenme alanıdır. Açık kaynak component geliştirme, code review ve accessibility çalışmaları geliştiricilere production benzeri deneyim kazandırabilir. Tasarımcı ve yazılımcının aynı proje üzerinde çalışması ortak terminoloji ve handoff becerilerini geliştirir. Yerel workshop'larda token sistemi, Storybook veya Figma-code mapping gibi konular uygulamalı ele alınabilir. Topluluk projeleri yalnızca eğitim çıktısı değil gerçek kullanılabilir open source component ve ortak çalışma kültürü oluşturabilir.

Open Source Component Geliştirme

Küçük bir open source component gerçek API ve documentation sorumluluğu öğretir. Farklı kullanıcıların ihtiyaçları API'nin ne kadar genel olması gerektiğini gösterir. Issue ve PR feedback geliştiriciyi kendi kullanım senaryosu dışına çıkarır. Accessibility ve testing release kriteri olarak uygulanabilir. Bu deneyim şirket içi design system çalışmalarına doğrudan aktarılabilir.

Code Review Kültürü

Code review yalnızca hata bulma değil ortak standart öğrenme alanıdır. Component API, semantics ve accessibility üzerine teknik tartışmalar ekip bilgisini yayar. Review yorumları gerekçe içermelidir. Yeni geliştiriciler mevcut karar mantığını öğrenir. Topluluk içinde açık ve saygılı review kültürü profesyonel proje işbirliğini güçlendirir.

Tasarımcı ve Yazılımcıları Aynı Projede Buluşturmak

Design system projesi tasarımcı ve frontend geliştiricinin aynı token ve component yapısını birlikte oluşturmasını gerektirir. Figma ile kod arasındaki gerçek farklar uygulama sırasında ortaya çıkar. Taraflar birbirinin kısıtlarını daha iyi öğrenir. Designer accessibility ve responsive teknikleri, developer visual hierarchy ve interaction kararlarını daha yakından görür. Ortak proje bu iki disiplin arasındaki iletişimi teorik eğitimden daha hızlı geliştirir.

Diyarbakır Yazılım Topluluğu Gibi Yerel Topluluklarda Workshop'lar

Yerel workshop'larda küçük bir Shadcn tabanlı design system sıfırdan kurulabilir. Katılımcılar design token oluşturup Figma ve Storybook ile eşleştirme pratiği yapabilir. Accessibility ve visual regression ayrı oturumlarda incelenebilir. Takım çalışması contribution ve code review alışkanlığı kazandırır. Diyarbakır Yazılım Topluluğu hakkında bilgi almak için https://www.diyarbakiryazilim.com.tr/about adresi kullanılabilir.

Açık Kaynak Design System Projelerine Katkı

Açık kaynak design system projelerine katkı gerçek governance ve review süreçlerini görmeyi sağlar. İlk katkı documentation veya accessibility fix olabilir. Daha sonra component API veya test geliştirmesine geçilebilir. Katılımcı breaking change ve backwards compatibility kavramlarını gerçek kullanıcılar üzerinden öğrenir. Topluluk projeleri için https://www.diyarbakiryazilim.com.tr/projects adresindeki çalışmalar da takip edilebilir.

Production'a Çıkmadan Önce Shadcn UI Design System Kontrol Listesi

Production öncesi kontrol yalnızca component'lerin ekranda doğru görünmesine odaklanmamalıdır. Design token, API standardı, accessibility, Storybook, visual regression, Figma eşleşmesi, versioning, dağıtım, governance ve migration politikası birlikte kontrol edilmelidir. Eksik alanların tamamı release blocker olmak zorunda değildir, ancak risk bilinçli biçimde kabul edilmelidir. Experimental lifecycle kullanılıyorsa bazı component'ler sınırlı kapsamla çıkabilir. Kontrol listesi design system'in yalnızca teknik demo değil gerçek ürün ekipleri tarafından güvenle tüketilebilecek şirket altyapısı olmasını sağlar.

Design Tokens Tamamlandı mı?

Primitive ve semantic token yapısı açık olmalıdır. Component'ler hardcoded temel renk veya spacing kullanmamalıdır. Light ve dark theme değerleri doğrulanmalıdır. Figma token mapping bulunmalıdır. Yeni token ekleme süreci dokümante edilmelidir.

Component API'leri Standart mı?

Variant ve size isimleri bütün component setinde tutarlı olmalıdır. Gereksiz prop sayısı azaltılmalıdır. TypeScript public API açık olmalıdır. Figma property isimleriyle mümkün olduğunca eşleşme sağlanmalıdır. Breaking değişiklik politikası belirlenmelidir.

Accessibility Testleri Geçiyor mu?

Automated axe veya benzeri kontroller stable story'lerde çalışmalıdır. Keyboard navigation manuel olarak test edilmelidir. Focus behavior dialog ve composite component'lerde doğrulanmalıdır. Form label ve error ilişkileri kontrol edilmelidir. Bilinen accessibility istisnaları owner ve plan ile kayıt altında olmalıdır.

Storybook Dokümantasyonu Var mı?

Her stable component için temel story bulunmalıdır. Variant ve kritik state'ler gösterilmelidir. Usage guideline ve API açıklaması erişilebilir olmalıdır. Theme ve responsive örnekleri kritik component'lerde eklenmelidir. Deprecated component durumu açıkça işaretlenmelidir.

Visual Regression Testleri Var mı?

Kritik component story'leri screenshot testine dahil edilmelidir. Light ve dark theme kapsanmalıdır. Responsive component'ler birkaç anlamlı viewport'ta test edilmelidir. Intentional görsel değişiklik için approval süreci bulunmalıdır. Flaky testler release güvenini zayıflatmadan düzenli temizlenmelidir.

Figma ve Kod Eşleşiyor mu?

Component isimleri ve variant'lar karşılaştırılmalıdır. Token isimleri aynı mapping standardını kullanmalıdır. Figma deprecated öğeler temizlenmelidir. Code'da yeni ancak Figma'da eksik component kalmamalıdır. Drift audit sonucu release öncesinde görünür olmalıdır.

Versioning Politikası Belirlendi mi?

Patch, minor ve major farkı company policy içinde açıklanmalıdır. Registry modelinde item veya release version yaklaşımı belirlenmelidir. Breaking change migration guide gerektirmelidir. Deprecation deadline mekanizması bulunmalıdır. Changelog consumer ekiplerin kolay okuyacağı formatta yayınlanmalıdır.

Registry veya Package Dağıtımı Hazır mı?

Consumer ekip component'i nasıl kuracağını veya import edeceğini bilmelidir. Private registry kullanılıyorsa authentication güvenli çalışmalıdır. Package modelinde version ve release pipeline test edilmelidir. Monorepo'da alias ve shared config doğru olmalıdır. Örnek consumer uygulama install smoke testten geçmelidir.

Governance Süreci Tanımlandı mı?

Core team ve owner rolleri belli olmalıdır. Yeni component proposal ve review süreci dokümante edilmelidir. Product team contribution kabul yöntemi açık olmalıdır. Accessibility ve design review sorumluları bilinmelidir. Karar kayıtları erişilebilir yerde tutulmalıdır.

Migration ve Deprecation Politikası Var mı?

Legacy component'lerin hangi sırayla taşınacağı planlanmalıdır. Deprecated yeni kullanım lint ile sınırlandırılabilir. Migration guide ve gerekirse codemod hazırlanmalıdır. Removal deadline gerçekçi olmalıdır. Adoption metriği geçişin tamamlanma durumunu göstermelidir.

Sıkça Sorulan Sorular

Shadcn UI Kullanarak Şirket İçi Tasarım Sistemi Kurmak isteyen ekiplerin soruları çoğunlukla Shadcn/ui'ın gerçek rolü, component ownership, Storybook, Figma, monorepo, registry, accessibility ve migration çevresinde yoğunlaşır. Temel nokta Shadcn/ui'ın tek başına şirket design system'i olmadığı, fakat güçlü primitive ve distribution mekanizmalarıyla böyle bir sistemin altyapısını oluşturabildiğidir. Başarılı sonuç için token, component API, test, documentation ve governance birlikte ele alınmalıdır. Dağıtım modelinin şirket organizasyon yapısıyla uyumlu olması da teknik seçim kadar önemlidir. Aşağıdaki cevaplar proje başlangıcında architecture ve platform ekiplerinin en sık değerlendirdiği noktaları kısa biçimde özetler.

Shadcn UI bir design system midir?

Shadcn/ui tek başına şirketinizin tamamlanmış design system'i olarak görülmemelidir. Component, theme ve registry altyapısı güçlü başlangıç sağlar. Şirketin kendi token, branding, accessibility ve governance kararlarını ayrıca oluşturması gerekir. Dokümantasyon ve Figma eşleşmesi de kurum tarafından yönetilir. Bu nedenle Shadcn/ui temel yapı taşı, gerçek design system ise bu altyapı üzerinde kurduğunuz şirket standardıdır.

Shadcn UI şirket içi tasarım sistemi için uygun mudur?

Evet, özellikle source code ownership ve customization isteyen ekipler için oldukça uygundur. Semantic CSS variable yaklaşımı theme ve branding çalışmalarını destekler. Monorepo ve registry özellikleri şirket içi dağıtımı kolaylaştırabilir. :contentReference[oaicite:36]{index=36} Bununla birlikte update, versioning ve governance şirket sorumluluğundadır. Bu sorumlulukları yönetebilecek platform modeli bulunuyorsa güçlü seçenek haline gelir.

Shadcn UI component library midir?

Shadcn/ui reusable component sunar, ancak dağıtım modeli klasik package tabanlı library'den farklıdır. Kod consumer projeye alınır ve sahiplenilir. Bu nedenle özelleştirme esnekliği yüksektir. Merkezi automatic update davranışı daha sınırlıdır. Şirket içinde bu farkın update ve ownership sürecine yansıtılması gerekir.

Shadcn UI component'leri doğrudan değiştirilir mi?

Evet, copy-and-own yaklaşımı doğrudan component kodunu değiştirmenize imkan verir. Ancak her değişikliği base component'e eklemek doğru değildir. Şirket genel standardı olan davranış base'e, product-specific davranış wrapper veya composite katmana alınabilir. Upstream diff kolaylığı da düşünülmelidir. Değişiklik governance ve test sürecinden geçmelidir.

Shadcn UI ile Storybook kullanılabilir mi?

Evet, Storybook Shadcn tabanlı component'leri bağımsız dokümante etmek ve test etmek için uygundur. Variant galerisi, theme story ve responsive state'ler hazırlanabilir. Interaction test ve accessibility addon'ları kalite sürecini destekler. :contentReference[oaicite:37]{index=37} Storybook şirket içi component portalı görevi görebilir. Figma linkleri ve design guideline ile zenginleştirilebilir.

Shadcn UI Figma ile nasıl eşleştirilir?

Figma component variant isimleri kod prop'larıyla mümkün olduğunca aynı tutulmalıdır. Design token'lar Figma Variables ve CSS theme variables arasında ortak naming convention kullanmalıdır. Component lifecycle iki tarafta aynı durumu göstermelidir. Designer developer handoff sırasında yeni pattern ve override'lar açıkça belirtilmelidir. Düzenli drift audit yapılması uzun vadeli uyumu korur.

Shadcn UI monorepo'da nasıl kullanılır?

Güncel Shadcn CLI monorepo yapılarını destekler ve workspace'lerde uygun components.json yapılandırmasıyla component'leri doğru yerlere kurabilir. :contentReference[oaicite:38]{index=38} UI, token ve config package'ları ayrı workspace olarak düzenlenebilir. Consumer app'ler shared UI package kullanır. Alias ve theme configuration bütün workspace'lerde tutarlı olmalıdır. Monorepo atomic refactor ve shared test açısından güçlü avantaj sağlar.

Private Shadcn Registry nedir?

Private registry şirket component'lerini yalnızca yetkili ekiplerin CLI üzerinden indirebildiği internal kaynak olarak yayınlamayı sağlar. Güncel registry sistemi authenticated namespaced URL yapılandırmasını destekliyor. :contentReference[oaicite:39]{index=39} Component, block, theme ve dependency bilgileri registry item içinde tanımlanabilir. Consumer kodu kendi repository'sine alır. Authentication ve update politikası şirket tarafından yönetilmelidir.

Registry mi npm package mı daha iyi?

Tek bir cevap yoktur. npm package merkezi implementation ve version kontrolü sağlar. Registry source ownership ve local customization konusunda daha esnektir. Monorepo sık birlikte değişen projelerde üçüncü seçenek sunar. Şirket repository yapısı, update ihtiyacı ve fork toleransına göre karar vermelidir.

Shadcn UI güncellemeleri nasıl yönetilir?

Upstream değişiklikler düzenli izlenmeli ve internal component ile diff edilmelidir. Her değişiklik otomatik overwrite edilmemelidir. Güvenlik, accessibility ve önemli bug fix'ler önceliklendirilebilir. Local customization korunarak hedefli patch uygulanabilir. Büyük update consumer testleri ve migration planıyla birlikte yapılmalıdır.

Multi-brand design system kurulabilir mi?

Evet, semantic token ve CSS variable modeli multi-brand sistem için uygundur. Aynı component farklı brand-specific token değerleriyle çalışabilir. Marka başına component fork etmekten mümkün olduğunca kaçınılmalıdır. Runtime theme switching white-label ürünlerde kullanılabilir. Figma Variables tarafında da aynı marka mode yapısı uygulanabilir.

Shadcn UI accessibility açısından uygun mudur?

Shadcn tabanlı component'ler erişilebilir primitive'lerle güçlü başlangıç sağlayabilir, ancak şirketinizin son implementasyonu yine test edilmelidir. Özelleştirme sırasında keyboard veya semantic davranış bozulabilir. Storybook axe testleri ilk kontrol katmanı olabilir. :contentReference[oaicite:40]{index=40} Manual keyboard ve screen reader review kritik component'lerde devam etmelidir. Accessibility design system acceptance kriterinin parçası olmalıdır.

Mevcut tasarım sistemi Shadcn UI'a nasıl geçirilir?

Önce mevcut component ve token envanteri çıkarılmalıdır. Legacy ile yeni component mapping hazırlanır. Küçük pilot üzerinden API ve styling yaklaşımı doğrulanır. Migration kademeli yürütülür ve legacy component'ler deprecation sürecine alınır. Figma, documentation ve visual regression dönüşümü code migration ile birlikte planlanmalıdır.

Şirket içi design system başarısı nasıl ölçülür?

Başarı yalnızca yayınlanan component sayısıyla ölçülmemelidir. Adoption rate, duplicate component sayısı, UI bug, accessibility hatası, feature geliştirme süresi ve ekip memnuniyeti birlikte değerlendirilmelidir. Migration öncesi baseline alınması ROI hesaplamasını kolaylaştırır. Product ekiplerinin contribution ve update deneyimi de önemli göstergedir. Şirketinizde bu yapıyı topluluk, eğitim ve ortak proje çalışmalarıyla geliştirmek için https://www.diyarbakiryazilim.com.tr adresi üzerinden Diyarbakır Yazılım Topluluğu çalışmalarına ulaşabilirsiniz.