Bileşen kütüphanesi nasıl kurulur?

Kısaca

Bileşen kütüphanesi, arayüzün tekrar eden parçalarının tek bir yerde durduğu koddur. Bir ekranda buton gerekiyorsa geliştirici onu baştan yazmaz, kütüphaneden çağırır. Tasarımcı da Figma'da aynı adı taşıyan parçayı kullanır.

Kütüphane, bir tasarım sisteminin parçasıdır, tamamı değildir. Sistemin kurallarını ve onu yöneten ekibi o rehberde anlattım. Bu sayfa yalnızca kütüphanenin nasıl kurulduğunu anlatıyor.

• Bir bileşen tek bir işi yapar ve ham renk bilmez. Renkleri ve ölçüleri design token denen adlandırılmış değerlerden okur.
• Kütüphanenin asıl ürünü bileşenlerin API'sidir: hangi ayarı aldığı, neyi varsayılan saydığı.
• UI kit oluşturma işi de aynı sırayla ilerler. Fark, UI kit'in çoğu zaman yalnızca tasarım dosyasında kalmasıdır.

Önce envanter: kütüphaneye ne girecek?

Kütüphane boş bir sayfayla başlamaz. Ürününüzde zaten onlarca buton, form alanı ve kart var. İlk iş bunları toplamaktır.

Ben her ekranın görüntüsünü alıp parçaları türlerine göre aynı panoya yapıştırırım. Brad Frost'un arayüz envanteri dediği yöntemi tasarım sistemi rehberinde adım adım yazdım. Burada envanterden nasıl bir öncelik sırası çıkardığımı anlatıyorum.

Envanter bitince her türün yanına iki sayı yazarım: kaç ekranda geçiyor ve kaç farklı görünümü var. En çok geçen ve en dağınık olan parça listenin başına gelir. Benim baktığım ürünlerde bu parça çoğu zaman butondur.

Atomic design: parçaları adlandırmak

Envanterdeki parçaları gruplarken ben Brad Frost'un modeline bakarım. Frost 2016 tarihli Atomic Design kitabında arayüzü beş aşamada anlatır. Tablodaki tanımlar, onun metninden yaptığım kısa çevirilerdir.

Frost iki uyarı da yapar. Birincisi, atomic design doğrusal bir süreç değildir, bir düşünme modelidir. İkincisi, şablon aşamasına gelince kimya benzetmesine veda eder. Benzetmeyi fazla zorlamanın paydaşların kafasını karıştırabileceğini yazar.

Yine de kodda "atom" ya da "molekül" klasörü açmam. Bileşenlere işlerine göre ad veririm: Button, SearchForm, ProductCard. Model, neyin neyi içerdiğini konuşurken işe yarar.

Bileşen API'si: props nasıl tasarlanır?

Bir bileşenin API'si, onu çağıran kişinin verebileceği ayarlardır. React'te bunlara props denir. React belgesi props'u bileşenin tek argümanı diye anlatır. Üst bileşen alt bileşene bilgiyi props ile geçirir.

Aynı belge iki kuralın altını çizer. Props salt okunurdur, bileşen kendi props'unu değiştirmez. Etkileşim gerekiyorsa state kullanılır. Varsayılan değer de props yazılırken verilir, örneğin size = 100.

React bileşen kütüphanesi kurarken ben şu kurallara uyarım:

1. Prop'a anlamına göre ad verin. color="black" yerine variant="primary" yazın. Marka rengi değişince API değişmez.
2. Seçenekleri sınırlı tutun. size yalnızca sm, md ve lg değerlerini alsın. Serbest değer, envanterdeki dağınıklığı geri getirir.
3. Varsayılan, en sık kullanılan hal olsun. Hiç ayar vermeden çağrılan bileşen ekranlarınızın çoğunda doğru görünmeli.
4. Açık/kapalı durumlar için mantıksal prop kullanın. disabled ya da loading varsayılan olarak kapalı olur.
5. Etiketi metin olarak alın. Butonun yazısı çağıran kişiden gelir. Böylece CTA butonu metni her ekranda eyleme göre yazılabilir.

Kaçış kapısını dar tutun

Her kütüphane bir gün öngörmediği bir ihtiyaçla karşılaşır. Bu yüzden bileşen, HTML öğesinin kendi özniteliklerini olduğu gibi aktarabilmeli. type, aria-label ya da form gibi değerler doğrudan alttaki <button> öğesine iner.

Stil için ise kapıyı dar tutarım. Her bileşene serbest bir style ya da sınıf ayarı açmak, kopyalamanın daha kibar bir hali olur. Bir ekip aynı stili ikinci kez dışarıdan veriyorsa, o stil kütüphanede yeni bir varyant olmayı hak ediyordur.

Adlandırmayı tasarım dosyasıyla eşleyin. Figma'daki bileşenin ayarı "Size: Large" ise kodda size="lg" olmalı. Tasarımcı ile geliştirici aynı kelimeyi kullanınca devir sırasında çeviri gerekmez.

Bir API'yi denemenin en kolay yolu, onu çağıran tek satırı yazmaktır. Satır kısa ve okunur kalıyorsa API iyidir. Aşağıda bir butonun ayarlarını değiştirip bu satırın nasıl değiştiğine bakabilirsiniz.

Deneyin: buton API'si

Ayarları seçin. Önizleme ve iki kod satırı birlikte değişir. Ok tuşlarıyla bir grup içinde gezinebilirsiniz.

button("Kaydet", variant="primary")

<Button variant="primary">Kaydet</Button>

disabled'ı açınca önizleme butonu soluklaşır ve tıklamayı almaz. Bunu sağlayan stil bileşenin CSS dosyasında bir kez yazılıdır. Hiçbir ekran bu kuralı kendisi yazmaz.

Varyant mı, ayrı bileşen mi?

Kütüphane büyüdükçe en sık karşılaştığım soru bu oluyor. Yeni bir buton çeşidi mi geldi, yoksa yeni bir bileşen mi? Benim ölçütüm davranıştır.

Parça aynı işi yapıyor, yalnızca görünüşü değişiyorsa varyanttır. Birincil ve ikincil buton aynı şeyi yapar: basılınca bir eylemi başlatır. Bu yüzden ikisi tek bileşenin variant ayarıdır.

Parçanın davranışı, içeriği ya da erişilebilirlik rolü değişiyorsa ayrı bileşendir. Başka sayfaya giden bir bağlantı, butona benzese de bir bağlantıdır. Bir menüyü açıp kapatan buton da kendi klavye kurallarını taşır.

Bir uyarı işareti de var: bir prop eklemek için bileşenin içine üçüncü if bloğunu yazıyorsanız, büyük ihtimalle iki bileşeni tek dosyaya sıkıştırıyorsunuz.

Durumları baştan yazın

Envanterde göremediğiniz şey durumlardır. Ekran görüntüsü butonu yalnızca durağan haliyle gösterir. Oysa kullanıcı butonu başka anlarda da görür: imleç üstündeyken, klavyeyle odaklandığında, basarken ve bir işlemi beklerken.

Ben her bileşen için şu durumları yazmadan kodu bitmiş saymam: varsayılan, üstüne gelme, odak, basılma, devre dışı ve yükleniyor. Form alanlarına bir de hata durumu eklenir. Hata metninin nasıl yazılacağını hata mesajları kalıbında topladım.

Erişilebilirlik kuralları da durumlara bağlıdır. W3C'nin buton kalıbına göre butona odaklanınca Space ya da Enter tuşu onu çalıştırır. Eylem kullanılamıyorsa aria-disabled="true" verilir.

Aynı kalıp, basılı kalan butonlar için de net bir kural koyar. Durum aria-pressed ile bildirilir ve butonun etiketi durum değişince değişmez. Etiket değişecekse, örneğin "Sesi kapat" yerine "Sesi aç" yazacaksa, aria-pressed kullanılmaz.

Dokunma hedefinin boyutu da bileşenin işidir. Küçük boyutlu varyant bile parmakla rahat basılabilmeli. Ölçüleri dokunma alanı kalıbında, kriterlerin tamamını WCAG rehberinde bulabilirsiniz.

Dokümantasyon ve Storybook

Belgesi olmayan bileşen, kopyalanıp değiştirilen bileşendir. Ben her bileşenin sayfasına şunları yazarım: ne işe yaradığı, ne zaman kullanılmadığı, aldığı ayarlar ve varsayılanları, durumları ve kopyalanabilir bir kod örneği.

Bu sayfaları elle güncel tutmak zordur. Bu iş için Storybook adlı aracı kullanabilirsiniz. Storybook kendini, arayüz bileşenlerini ve sayfaları uygulamadan ayrı geliştirmek için bir ön yüz atölyesi olarak tanımlar.

Storybook'ta her duruma bir "story" denir. Belgeye göre bir story, bir bileşenin çizilmiş bir halini yakalar. Bileşenin ayarları ise "args" adlı tek bir JavaScript nesnesinde durur. Bir arg değişince bileşen yeniden çizilir.

Yukarıdaki buton için iki story şöyle görünebilir:

export default { component: Button, args: { children: 'Kaydet' } };
export const Birincil = { args: { variant: 'primary' } };
export const DevreDisi = { args: { variant: 'primary', disabled: true } };

İlk satırdaki args bileşen düzeyindedir ve her story'ye uygulanır. Story içindeki args yalnızca o story için geçerlidir. Storybook belgesi bu iki düzeyi ayrı ayrı anlatır.

Storybook resmi olarak React, Vue, Angular, Svelte ve Web Components ile çalışır. Belgesine göre bileşenleri inceleyip story'lerin yanında otomatik belge de üretebilir. Story'ler ayrıca arayüz testleri için hazır bir temel olur.

Sürümleme: değişikliği nasıl duyurursunuz?

Kütüphaneyi birden fazla proje kullanıyorsa her değişiklik birini etkiler. Sürüm numarası, o değişikliğin ne kadar riskli olduğunu söyleyen kısa bir mesajdır. Ben Semantic Versioning 2.0.0 kurallarını kullanırım.

• MAJOR: Geriye uyumsuz bir değişiklik. Örnek: color prop'unu kaldırıp yerine variant koymak.
• MINOR: Geriye uyumlu yeni bir özellik. Örnek: butona size="lg" eklemek.
• PATCH: Geriye uyumlu bir hata düzeltmesi. Örnek: odak halkasının kaybolduğu bir hatayı gidermek.

Semver'e göre 0.y.z sürümleri ilk geliştirme içindir ve her şey her an değişebilir. 1.0.0, genel API'yi tanımlayan ilk sürümdür. Belgenin SSS bölümüne göre üretimde kullanılan bir yazılım muhtemelen zaten 1.0.0 olmalıdır.

Bir prop'u kaldırmadan önce onu kullanımdan kalkacak diye işaretleyin. Semver bu işaretlemeyi bir MINOR sürümle yapmayı ister. SSS bölümü de kaldırmadan önce en az bir MINOR sürümün bu uyarıyla yayımlanmasını önerir. Böylece kullananlar geçiş için zaman bulur.

Bu sitedeki örnek

ux.center'ın kendi arayüzü küçük bir bileşen kütüphanesiyle çalışıyor. Yapıyı sitenin DESIGN.md dosyası anlatıyor. Katmanlar şöyle: tokenlar, bileşenler, bölümler ve sayfa. Her katman yalnızca altındakine dayanıyor.

Kural basit: bir bileşen, bir CSS dosyası ve çoğu zaman bir Python fonksiyonudur. Buton için src/ds/components/button.css ve ui.py içindeki button() fonksiyonu var. Fonksiyon etiketi, bağlantıyı, variant, size ve arrow ayarlarını alıyor.

Varyantlar CSS'te değiştirici sınıflarla ekleniyor: btn--primary, btn--accent, btn--sm, btn--lg. Temel .btn kuralına dokunulmuyor. Bileşenler ham renk değil, --surface ya da --accent gibi anlamsal tokenlar okuyor.

Dürüst olayım: button() bir bağlantı üretiyor, bu yüzden disabled ayarı almıyor. Devre dışı görünüm CSS'te tanımlı ve yukarıdaki demo gibi gerçek <button> öğelerinde çalışıyor. Bu, kütüphanede hâlâ açık duran bir boşluk.

Derleme betiği tüm bileşen dosyalarını tek bir CSS dosyasında topluyor. Yeni bir parça gerektiğinde önce bileşen klasörüne bir dosya ekleniyor, sonra tasarım belgesindeki tabloya bir satır yazılıyor.

Benim notum

Audit'lerde en sık gördüğüm sorun kopyalanmış bileşendir. Ekip kütüphanedeki butonu kullanmak yerine benzerini yazmış, çünkü ihtiyacı olan ayar yokmuş. Bir süre sonra aynı butonun birkaç hali ürünün içinde dolaşır.

Bunu önlemenin yolu, kütüphaneye istek açmayı kopyalamaktan daha kolay hale getirmektir. Ben her bileşen sayfasına "Bu bileşen işinizi görmüyorsa" diye bir satır ve bir iletişim yolu eklerim.

Küçük bir ekipte kütüphaneye on bileşenle başlamanızı öneririm. Önce buton ve form alanı gibi en sık kullanılan parçaları iyi kurun. Kalanını ihtiyaç doğdukça ekleyin. Tasarımı Figma'dan koda taşırken nelerin kaybolduğunu tasarımdan koda rehberinde anlattım.

Kütüphanenizi benimle birlikte kurmak isterseniz Tasarla & Yayınla Sprinti tam bu iş için. İki haftada tasarımı ve kodu reponuza teslim ederim.