Erişilebilirlik

Hedef ve kapsam

BigBang’in hedefi her yüzeyde WCAG 2.2 AA düzeyidir (D-11). Bu hedef bileşenlerde, kalıplarda, ekran şablonlarında ve bu doküman sitesinde aynıdır. Uygunluk raporu (ACR) ölçülen sonucu yazar; yasal uygunluk iddiası taşımaz.

Erişilebilirlik iki katmanda sağlanır:

1. Bileşen: Rol, ad, klavye, odak, kontrast ve hareket bileşenin içinde çözülür. Her bileşenin Erişilebilirlik sekmesi bunları yazar.
2. Ekran: Başlık sırası, sayfa başlığı, hata özeti, odak akışı ve içerik dili ekranı kuran ekibin işidir. Bileşen bunları tek başına çözemez.

İlkeler

İlke	Ne demek	Örnek
Önce yerel öğe	Tarayıcının hazır öğesi (<button>, <input>, <a>) varsa onu kullanın. ARIA yalnızca eksik anlamı tamamlar.	Button yerel <button> çizer; <div role="button"> yoktur.
Klavye her şeyi yapar	Fareyle yapılan her iş klavyeyle de yapılır; sıra görsel sırayla aynıdır.	Diyalog Esc ile kapanır, odak açan öğeye döner.
Renk tek başına anlatmaz	Durum, hata ve seçim metinle ya da şekille de görünür.	Badge rengin yanında durumu yazar.
Hareket isteğe bağlıdır	Azaltılmış hareket tercihinde hareket silinmez, sakin bir geçişe döner.	Yükleniyor göstergesi döner; azaltılmış harekette sabit durur.
İki dilde aynı erişim	Türkçe ve İngilizce arayüz aynı rolleri, adları ve duyuruları taşır.	Button’ın yükleniyor metni ui.* katalogundan iki dilde gelir.

Bileşen türüne göre kontrol listesi

Bir bileşeni ya da ekranı yayına almadan önce türüne uyan listeyi baştan sona geçin. Her satır bir WCAG 2.2 başarı ölçütüne bağlıdır.

Eylemler (Button, bağlantı, ikon buton)

Ölçüt	Kontrol
2.1.1 Klavye	Enter ve Boşluk işlemi başlatır; bağlantı yalnızca Enter ile açılır.
2.4.4 Bağlantı amacı	Bağlantı metni tek başına okunduğunda nereye gittiğini söyler; “buraya tıklayın” yoktur.
2.4.7 Odak görünür	Klavyeyle gelindiğinde 2 px odak halkası görünür.
2.5.3 Ada etiket dahil	Erişilebilir ad görünür etiketle başlar.
2.5.8 Hedef boyutu	Hedef en az 24 × 24 CSS px ya da çevresinde 24 px boşluk vardır.
4.1.2 Ad, rol, değer	Yalnızca ikon taşıyan butonun label özelliği vardır.

Form alanları (TextInput ve diğer girişler)

Ölçüt	Kontrol
1.3.1 Bilgi ve ilişkiler	Her alanın görünür bir <label> öğesi vardır; yer tutucu metin etiketin yerine geçmez.
1.3.5 Girdi amacı	Kişisel bilgi alanlarında autocomplete değeri doğrudur.
3.3.1 Hata tanımlama	Hata metinle yazılır ve aria-describedby ile alana bağlanır.
3.3.2 Etiket ya da yönerge	Zorunlu alan işaretlenir; biçim kuralı alanın altında yazar.
3.3.7 Gereksiz tekrar	Aynı süreçte önceden girilen bilgi yeniden istenmez.
1.4.11 Metin dışı kontrast	Alan kenarlığı yüzeye karşı en az 3:1’dir.

Durum ve geri bildirim (Badge, bildirim, ilerleme)

Ölçüt	Kontrol
1.4.1 Renk kullanımı	Durum yalnızca renkle değil, metinle de verilir.
4.1.3 Durum mesajları	Sonradan gelen mesaj kibar (polite) bir canlı bölgede bir kez okunur; acil hata alert ile okunur.
2.2.1 Ayarlanabilir süre	Kendiliğinden kapanan mesajın süresi uzatılabilir ya da mesaj kalıcı bir yerde de durur.
2.2.2 Duraklat, durdur, gizle	5 saniyeden uzun süren hareket durdurulabilir.

Kaplamalar (diyalog, açılır pencere, menü, ipucu)

Ölçüt	Kontrol
2.1.2 Klavye tuzağı yok	Esc kaplamayı kapatır; odak kaplamanın içinde döner ama çıkış her zaman vardır.
2.4.3 Odak sırası	Açılınca odak kaplamanın ilk anlamlı öğesine, kapanınca açan öğeye döner.
2.4.11 Odak görünürlüğü (asgari)	Yapışkan başlık ya da kaplama odaktaki öğeyi örtmez.
1.4.13 Üzerine gelince ya da odakta içerik	İpucu Esc ile kapanır, üzerine gelinince açık kalır, kendiliğinden kaybolmaz.
4.1.2 Ad, rol, değer	Diyalogun adı başlığından gelir (aria-labelledby).

Gezinme (sekmeler, kenar menü, sayfalama)

Ölçüt	Kontrol
2.4.1 Blokları atlama	Sayfanın başında ana içeriğe atlama bağlantısı vardır.
2.4.2 Sayfa başlığı	Her ekranın kendine özgü bir <title> değeri vardır.
2.4.8 Konum	Seçili menü öğesi aria-current="page" taşır.
3.2.3 Tutarlı gezinme	Menü her ekranda aynı sıradadır.

Veri (tablo, grafik, liste)

Ölçüt	Kontrol
1.3.1 Bilgi ve ilişkiler	Tablo <th> ve scope kullanır; sıralanan sütun aria-sort taşır.
1.1.1 Metin dışı içerik	Her grafiğin yanında aynı verinin tablo ya da metin özeti vardır.
1.4.1 Renk kullanımı	Seriler renkle birlikte çizgi deseni, işaretçi ya da doğrudan etiketle ayrılır.
1.4.10 Yeniden akış	Geniş tablo 320 CSS px’te kendi içinde yatay kayar; sayfa yatay kaymaz.

Görseller (ikon, illüstrasyon, logo)

Ölçüt	Kontrol
1.1.1 Metin dışı içerik	Süs ikon ve illüstrasyon aria-hidden="true" ve boş alt taşır; anlam taşıyan ikonun adı vardır.
1.4.11 Metin dışı kontrast	Anlam taşıyan ikon zemine karşı en az 3:1’dir.
1.4.5 Metin görselleri	Görselin içinde yazı yoktur.

Klavye haritası

Bu tablo bileşen kayıt dosyasından (apps/docs/src/data/components.ts) üretilir. Yeni bir bileşen kaydedildiğinde satırları buraya kendiliğinden gelir.

Bileşen	Tuş	Davranış
Badge	-	Odak almaz; kendine ait tuşu yoktur.
Button	Tab	Odaklanır; devre dışıysa atlanır.
	Enter	İşlemi başlatır ya da formu gönderir.
	Boşluk	İşlemi başlatır.
TextInput	Tab	Alana odaklanır; devre dışıysa atlanır.
	Shift + Tab	Önceki alana döner.
	Yazı tuşları	Değeri girer.
NumberField	Yukarı / Aşağı ok	Değeri bir adım değiştirir.
	Page Up / Page Down	Değeri büyük adımla değiştirir.
	Home / End	En küçük ya da en büyük değere atlar.
PasswordInput	Enter / Boşluk	Göz düğmesinde değeri gösterir ya da gizler.
SearchInput	Enter	Aramayı gönderir.
	Escape	Değeri temizler.
OtpInput	Sol / Sağ ok	Kutular arasında dolaşır.
	Backspace	Karakteri siler ve geri gider.
PhoneInput	Enter / Boşluk / Aşağı ok	Ülke listesini açar.
	Escape	Listeyi kapatır.
Calendar	Oklar	Gün ve hafta arasında dolaşır.
	Page Up / Page Down	Önceki ya da sonraki ay; Shift ile yıl.
	Home / End	Haftanın ilk ya da son günü.
	Enter / Boşluk	Günü seçer.
DatePicker	Rakamlar	Parçayı doldurur ve sonrakine geçer.
	Yukarı / Aşağı ok	Parçayı bir artırır ya da azaltır.
	Sol / Sağ ok	Parçalar arasında dolaşır.
	Backspace	Parçayı temizler.
	Escape	Takvimi kapatır.
TimeField	Rakamlar	Parçayı doldurur ve sonrakine geçer.
	Yukarı / Aşağı ok	Parçayı bir artırır ya da azaltır, sınırda başa döner.
	Sol / Sağ ok	Parçalar arasında dolaşır.
	Backspace	Parçayı temizler.
DateRangePicker	Rakamlar	Parçayı doldurur; başlangıç bitince bitişe geçer.
	Yukarı / Aşağı ok	Parçayı değiştirir; hazır aralıklarda gezinir.
	Enter / Boşluk	Takvimde aralığın ucunu seçer.
	Escape	Takvimi kapatır.
Slider	Oklar	Bir adım artırır ya da azaltır.
	Page Up / Page Down	Büyük adım; Shift + ok da aynı.
	Home / End	En küçük ya da en büyük değer.
RadioCard	Tab	Gruba girer; seçili karta odaklanır.
	Oklar	Önceki ya da sonraki kartı seçer.
	Boşluk	Odaktaki kartı seçer.
FileDropzone	Tab	Dosya girişine, sonra listedeki Kaldır düğmelerine.
	Enter / Boşluk	Dosya seçiciyi açar.
Form	Enter	Bir alandayken formu gönderir.
	Tab	Özetteki bağlantılar arasında dolaşır.
Stepper	Tab	Tamamlanmış adım düğmelerine, sonra Geri ve İleri'ye.
	Enter / Boşluk	Adıma döner ya da düğmeyi çalıştırır.
SaveBar	Tab	Vazgeç ve Kaydet düğmelerine; kapalıyken atlanır.
Timeline	Tab	Yalnızca olayların içindeki bağlantı ve düğmelere.
Copy	Enter, Space	Değeri kopyalar.
MaskedValue	Enter, Space	Göster düğmesinde değeri açar ya da gizler.
MoneyText	-	Odak almaz; kendine ait tuşu yoktur.
AmountInput	Rakamlar, virgül, nokta	Tutarı yazar; harfler alınmaz.
	Tab	Alandan çıkar ve tutarı biçimler (1.234,50).
IbanInput	Rakamlar	IBAN yazılır; boşluklar kendiliğinden eklenir, imleç yerinde kalır.
	Tab	Alandan çıkar; eksik IBAN için mesaj gösterilir.
DateTimeText	-	Odak almaz; kendine ait tuşu yoktur.
CountdownTimer	-	Odak almaz; kendine ait tuşu yoktur.
ConsentBlock	Tab	Metin alanına, bağlantıya ve onay kutusuna.
	Yukarı, Aşağı, Page Up, Page Down	Metin alanında kaydırır.
	Space	Onay kutusunu işaretler.
NativeSelect	Space, Alt + Aşağı	Tarayıcının listesini açar.
	Yukarı, Aşağı, harf tuşları	Seçeneği değiştirir.
CodeBlock	Tab	Kopyala düğmesine ve kaydırma bölgesine.
	Sol, Sağ	Kaydırma bölgesinde uzun satırları kaydırır.
PreviewCard	Tab	Bağlantıya odaklanır; önizleme gecikmeyle açılır.
	Enter	Bağlantıyı izler.
	Escape	Önizlemeyi kapatır.
MonthPicker	Ok tuşları	Hücreler arasında gezer.
	Page Up, Page Down	Önceki ya da sonraki sayfa.
	Enter, Space	Hücreyi seçer.
	Escape	Tabloyu kapatır.
YearPicker	Ok tuşları	Hücreler arasında gezer.
	Page Up, Page Down	Önceki ya da sonraki sayfa.
	Enter, Space	Hücreyi seçer.
	Escape	Tabloyu kapatır.
Autocomplete	Yukarı, Aşağı	Önerileri vurgular.
	Enter	Vurgulanan öneriyi alana yazar.
	Escape	Listeyi kapatır.
DateTimePicker	Tab	Tarih bölümlerine, takvim düğmesine ve saat bölümlerine.
	Yukarı, Aşağı, rakamlar	Bölüm değerini değiştirir.
ContextMenu	Yukarı, Aşağı	Öğeler arasında gezer.
	Enter, Space	Öğeyi çalıştırır.
	Sağ, Sol	Alt menüyü açar ya da kapatır.
	Escape	Menüyü kapatır.
Popconfirm	Tab	Vazgeç ve onay düğmeleri arasında.
	Enter, Space	Odaktaki düğmeye basar.
	Escape	Vazgeçer ve kapatır.
InlineEdit	Enter	Düzenle düğmesinde alanı açar; alanda kaydeder.
	Escape	Değişikliği bırakır ve kapatır.
Anchor	Tab	Bağlantılar arasında gezer.
	Enter	Bölüme gider.

Tüm bileşenlerin uyduğu ortak tuşlar:

Tuş	Davranış
Tab / Shift + Tab	Sıradaki ya da önceki odaklanabilir öğeye geçer.
Esc	Açık kaplamayı kapatır, odağı açan öğeye geri verir.
Ok tuşları	Bileşik öğelerin (sekmeler, menü, radyo grubu) içinde gezinir. Bileşik öğe Tab sırasında tek duraktır.
Home / End	Bileşik öğede ilk ya da son öğeye gider.

Pozitif tabindex değeri kullanmayın. Odak sırası DOM sırasından gelir.

Odak

• Odak halkası color-focus-ring renginde, 2 px kalınlığında (border-width-focus) ve öğeden 2 px dışarıda çizilir.
• Halka yalnızca klavyeyle gelindiğinde görünür (:focus-visible). Fareyle tıklamada görünmez; alanlarda yazı imleci zaten konumu gösterir.
• Halka bir kenarlık değil, outline olarak çizilir. Böylece Windows yüksek kontrast modunda da görünür.
• Odaktaki öğeyi yapışkan başlık, alt çubuk ya da bildirim örtmez (2.4.11). Kaydırma kapsayıcılarında scroll-padding verin.
• Bir kaplama kapandığında, bir satır silindiğinde ya da bir sayfa açıldığında odak bilinçli bir yere taşınır: açan öğeye, bir sonraki satıra ya da sayfa başlığına.

Birincil buton

YapınHalka öğenin dışında ve çevresinde boşlukla çizilir; kırpılmaz.

focus:outline-none

YapmayınOdak halkasını kaldırmak klavye kullanıcısının yerini kaybetmesine yol açar.

Renk kontrastı

Aşağıdaki oranlar seçili markanın derlenmiş token’larından, açık ve koyu mod için hesaplanır. Marka değiştirdiğinizde tablo da değişir. Derleme kapısı packages/tokens/test/contrast.test.mjs testidir; bir çift eşiğin altına düşerse marka derlenmez (BRAND-07).

Metin: en az 4.5:1

Ön plan / arka plan	Örnek	Açık mod	Koyu mod
text-default surface-default	Aa	16.73:1 Geçer16.73:1 Geçer16.73:1 Geçer	15.97:1 Geçer15.97:1 Geçer15.97:1 Geçer
text-subtle surface-default	Aa	9.67:1 Geçer9.67:1 Geçer9.67:1 Geçer	11.24:1 Geçer11.24:1 Geçer11.24:1 Geçer
text-subtlest surface-raised	Aa	7.81:1 Geçer7.81:1 Geçer7.81:1 Geçer	5.85:1 Geçer5.85:1 Geçer5.85:1 Geçer
text-placeholder surface-raised	Aa	4.74:1 Geçer4.74:1 Geçer4.74:1 Geçer	5.85:1 Geçer5.85:1 Geçer5.85:1 Geçer
text-link surface-default	Aa	7.57:1 Geçer16.73:1 Geçer16.73:1 Geçer	7.70:1 Geçer15.97:1 Geçer15.97:1 Geçer
action-on-primary-default action-primary-default	Aa	5.92:1 Geçer17.17:1 Geçer17.17:1 Geçer	9.15:1 Geçer14.23:1 Geçer14.23:1 Geçer
action-on-danger-default action-danger-default	Aa	6.45:1 Geçer6.45:1 Geçer6.45:1 Geçer	9.73:1 Geçer9.73:1 Geçer9.73:1 Geçer
status-success-foreground status-success-background	Aa	7.09:1 Geçer7.09:1 Geçer7.09:1 Geçer	10.48:1 Geçer10.48:1 Geçer10.48:1 Geçer
status-warning-foreground status-warning-background	Aa	7.41:1 Geçer7.41:1 Geçer7.41:1 Geçer	10.48:1 Geçer10.48:1 Geçer10.48:1 Geçer
status-danger-foreground status-danger-background	Aa	7.68:1 Geçer7.68:1 Geçer7.68:1 Geçer	10.54:1 Geçer10.54:1 Geçer10.54:1 Geçer
status-info-foreground status-info-background	Aa	7.28:1 Geçer7.28:1 Geçer7.28:1 Geçer	10.44:1 Geçer10.44:1 Geçer10.44:1 Geçer
data-positive surface-raised	Aa	5.68:1 Geçer5.68:1 Geçer5.68:1 Geçer	10.21:1 Geçer10.21:1 Geçer10.21:1 Geçer
data-negative surface-raised	Aa	6.45:1 Geçer6.45:1 Geçer6.45:1 Geçer	9.60:1 Geçer9.60:1 Geçer9.60:1 Geçer

En az: 4.5:1

Kenarlık, ikon ve odak: en az 3:1

Ön plan / arka plan	Örnek	Açık mod	Koyu mod
border-input surface-raised	Aa	3.36:1 Geçer3.36:1 Geçer3.36:1 Geçer	3.19:1 Geçer3.19:1 Geçer3.19:1 Geçer
focus-ring surface-raised	Aa	5.92:1 Geçer4.74:1 Geçer4.74:1 Geçer	6.99:1 Geçer4.50:1 Geçer4.50:1 Geçer
border-focus surface-default	Aa	5.52:1 Geçer16.73:1 Geçer16.73:1 Geçer	7.70:1 Geçer13.23:1 Geçer13.23:1 Geçer
icon-default surface-default	Aa	14.12:1 Geçer14.12:1 Geçer14.12:1 Geçer	15.29:1 Geçer15.29:1 Geçer15.29:1 Geçer
icon-subtle surface-raised	Aa	4.74:1 Geçer4.74:1 Geçer4.74:1 Geçer	5.85:1 Geçer5.85:1 Geçer5.85:1 Geçer
icon-danger surface-raised	Aa	5.04:1 Geçer5.04:1 Geçer5.04:1 Geçer	7.43:1 Geçer7.43:1 Geçer7.43:1 Geçer
icon-success surface-raised	Aa	4.39:1 Geçer4.39:1 Geçer4.39:1 Geçer	8.19:1 Geçer8.19:1 Geçer8.19:1 Geçer
action-primary-default surface-default	Aa	5.52:1 Geçer16.73:1 Geçer16.73:1 Geçer	7.70:1 Geçer13.23:1 Geçer13.23:1 Geçer

En az: 3:1

Oranlar yuvarlanmaz; 4.49:1 kalır. Logolar bu kuralın dışındadır. Süs çizgileri (border-default, border-subtle) bir kontrolü tanıtmadığı için 3:1 aramaz.

Hedef boyutu

İşaretçiyle kullanılan her hedef en az 24 × 24 CSS px’tir ya da çevresinde 24 px’lik boş alan vardır (2.5.8). Birincil kontroller masaüstünde 40 px, 390 px kırılımında 48 px yüksekliktedir. Metin içi bağlantılar bu kuralın dışındadır.

Yakınlaştırma ve yeniden akış

• Ekran %200 yakınlaştırmada içerik ya da işlev kaybetmez (1.4.4).
• 320 CSS px genişlikte (1280 px’te %400) sayfa yatay kaymaz; yalnızca tablo ve grafik gibi iki boyutlu içerik kendi içinde kayar (1.4.10).
• Satır yüksekliği 1.5, paragraf aralığı 2, harf aralığı 0.12 ve kelime aralığı 0.16 katına çıktığında metin kesilmez (1.4.12). Metin kutularına sabit yükseklik vermeyin.
• Tutar, IBAN, referans numarası, tarih ve hata metni kısaltılmaz; sığmazsa alt satıra geçer (I18N-16).

Azaltılmış hareket

İşletim sisteminde hareket azaltıldığında ya da üründe data-motion="reduce" seçildiğinde süre token’ları 0-1 ms’ye iner. Hareket silinmez, yerine kısa bir saydamlık geçişi gelir (en çok 110 ms). Başarı işaretleri sabit görünür. Ayrıntılar Hareket sayfasındadır.

• 5 saniyeden uzun hareket durdurulabilir; sonsuz döngü yalnızca yükleniyor göstergesindedir (2.2.2).
• Saniyede üçten fazla yanıp sönme yoktur (2.3.1).
• Paralaks, kayan arka plan ve otomatik oynayan video ürün ekranlarında kullanılmaz.

Ekran okuyucu testi

Otomatik test hataların yalnızca bir kısmını bulur. Her bileşen yayına çıkmadan önce aşağıdaki eşleştirmelerle elle test edilir; tarih components.ts dosyasındaki a11yTested alanına yazılır.

Ekran okuyucu	Tarayıcı	Platform	Zorunlu
NVDA	Firefox ve Chrome	Windows	Evet
VoiceOver	Safari	macOS	Evet
VoiceOver	Safari	iOS (390 px)	Evet
TalkBack	Chrome	Android	Android uygulamalarında
JAWS	Chrome	Windows	Müşteri isterse

Test adımları

1. Sayfayı yalnızca klavyeyle baştan sona gezin. Her odak durağının görünür olduğunu ve sıranın mantıklı olduğunu not edin.
2. Ekran okuyucuyu açın ve bileşene Tab ile gelin. Okunan adı, rolü ve durumu (seçili, genişletilmiş, devre dışı, geçersiz) yazın.
3. Aynı bileşene okuma kipinde (NVDA’da göz atma kipi, VoiceOver’da VO + ok tuşları) gelin. Okunan metin aynı olmalıdır.
4. Bileşenin her durumunu tetikleyin: yükleniyor, hata, başarı, açık ve kapalı. Her değişikliğin bir kez ve doğru öncelikle duyurulduğunu kontrol edin.
5. Arayüz dilini İngilizceye çevirin ve 2-4. adımları tekrarlayın. Okunan metnin dili sayfanın lang değeriyle aynı olmalıdır.
6. Her bulguyu depoda bir hata kaydı olarak açın: tarih, ekran okuyucu ve sürümü, tarayıcı ve sürümü, bulgu.

Okunan metni yazma biçimi

Beklenen çıktıyı tırnak içinde, ekran okuyucunun okuduğu sırayla yazın. Örnek: “Kaydet, düğme”. Farklı ekran okuyucular farklı sıra kullanabilir; ad ve rol aynı olduğu sürece sıra farkı hata değildir.

Otomatik testler

• packages/ui testleri her bileşeni jsdom’da klavye, odak ve duyuru açısından sınar.
• Storybook hikâyeleri axe ile taranır; hedef violations = 0. axe’nin “incomplete” sonuçları elle kapatılır.
• Ekran şablonlarında Playwright ve axe her rota ve durum için çalışır (A11Y-01..20).
• Bir erişilebilirlik engeli oturum açma, tek kullanımlık şifre, onay ya da izin akışında bulunursa sürüm yayına çıkmaz.

Yönergeler

Etiketi yer tutucuyla değiştirmeyin

<TextInput label=“E-posta adresi” />

YapınGörünür etiket yazı yazılırken de kalır; ekran okuyucu adı etiketten okur.

<input placeholder=“E-posta adresi” />

YapmayınYer tutucu yazmaya başlayınca kaybolur ve kontrastı düşüktür.

Yalnızca ikon taşıyan kontrole ad verin

<IconButton icon=“x” label=“Kapat” />

YapınEkran okuyucu ikonun anlamını adından okur.

<button><XIcon /></button>

YapmayınAdı olmayan ikon buton yalnızca "düğme" diye okunur.