Erişilebilir Buton İsimleri: button-name Hatasını Anlamak ve Düzeltmek

1. button-name hatası nedir?

axe-core'un button-name kuralı, bir <button> öğesinin (veya role="button" taşıyan herhangi bir öğenin) erişilebilir bir ada sahip olup olmadığını kontrol eder. Ad yoksa kural ihlal edilmiş sayılır. Bu durum WCAG 2.1 4.1.2 Name, Role, Value (A Seviyesi) kriterinin doğrudan karşılığıdır; yani erişilebilirlikte aşılması zorunlu olan en temel eşiktir.

Burada “erişilebilir ad”dan kasıt, ekran okuyucunun (NVDA, JAWS, VoiceOver, TalkBack) butona odaklanıldığında kullanıcıya seslendirdiği metindir. Bu metin tanımlı değilse cihazın söyleyebildiği tek şey “buton” kelimesi olur.

2. Neden önemli?

Konu yalnızca görme engelli kullanıcılarla sınırlı değildir. Sesli komut sistemleri (Apple Voice Control, Dragon NaturallySpeaking, Android Voice Access) da butonu adıyla tanımak zorundadır. Kullanıcının “Sepete ekle butonuna tıkla” diyebilmesi için sistemin o butonu önceden “Sepete ekle” olarak biliyor olması gerekir.

Ölçeği görmek açısından: Keysonar tarayıcısının yakın zamanda incelediği sitelerde bu kuraldan 22.000'in üzerinde buton düğümü hata aldı. Yani neredeyse her sitede yüzlerce ziyaretçi en temel etkileşimleri tamamlayamıyor. button-name, erişilebilirlik denetimlerinde en sık karşılaşılan üç sorundan biri konumundadır.

3. Hangi durumlarda tetiklenir?

Tarama verilerimizde tekrar tekrar karşılaştığımız beş tipik senaryo:

1. İçeriği boş buton: Etiketi de, metni de, çocuğu da olmayan tamamen boş bir öğe.
2. Yalnızca ikon barındıran buton: İçinde sadece bir SVG, bir FontAwesome ikonu veya CSS arka planıyla çizilmiş bir simge bulunur; okunabilir tek bir karakter yoktur.
3. Yalnızca görsel barındıran buton: İçindeki <img> öğesinin alt metni boştur.
4. Tek metnin aria-hidden ile gizlendiği buton: Görsel olarak metin görünür ama erişilebilirlik ağacında yer almaz.
5. Metnin display:none ile gizlendiği buton: Hem ekrandan hem ekran okuyucudan saklanır; sonuç olarak ad bulunamaz.

4. Doğru çözümler

4.1 Yalnızca ikon içeren butonlar

E-ticaret sayfalarında en sık karşılaşılan tablo budur: sepet, arama, favori, paylaş ikonları. Çoğu zaman ikon dışında hiçbir metin bulunmaz ve buton ekran okuyucu tarafından sadece “buton” olarak seslendirilir.

<button class="cart-btn">
  <svg viewBox="0 0 24 24">...</svg>
</button>

<button class="cart-btn" aria-label="Sepete ekle">
  <svg aria-hidden="true" viewBox="0 0 24 24">...</svg>
</button>

4.2 Modal kapatma butonu (×)

<button onclick="close()">
  <span aria-hidden="true">×</span>
</button>

<button onclick="close()" type="button">
  <span aria-hidden="true">×</span>
  <span class="sr-only">Kapat</span>
</button>

<style>
  .sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
  }
</style>

4.3 Görsel butonu (img içeren)

<button>
  <img src="/icons/search.svg">
</button>

<button>
  <img src="/icons/search.svg" alt="Ara">
</button>

4.4 React / Next.js bileşenleri

<button onClick={addToWishlist}>
  <Heart className="w-5 h-5" />
</button>

<button
  onClick={addToWishlist}
  aria-label={t("product.addToWishlist")}
>
  <Heart aria-hidden className="w-5 h-5" />
</button>

Çok dilli sitelerde etiketin sayfa diliyle aynı dilde olması zorunludur. Türkçe bir sayfada İngilizce bir aria-label bırakırsanız ekran okuyucu, metni İngilizce telaffuzla seslendirir; sonuç Türk kullanıcı için anlaşılmaz hale gelir. Bu nedenle etiketleri her zaman çeviri sözlüğünden alın.

5. Erişilebilir ad nasıl belirlenir?

Tarayıcı, butonun adını aşağıdaki öncelik sırasına göre hesaplar. Listede üstten aşağıya inilir ve ilk dolu olan değer butonun adı olarak kabul edilir:

1. aria-labelledby (başka bir öğenin metnini referans alır)
2. aria-label
3. Butonun kendi içerdiği metin (yazı, img alt, vb.)
4. title özniteliği (en güvenilmez yöntem — bu listede son çaredir)

<button aria-label="Onayla">
  Sepete ekle
</button>

<button>Sepete ekle</button>

6. Gözden kaçan durumlar

• Geç yüklenen SPA butonları: React/Vue uygulamalarında modal, sekme veya açılır menü içeriği kullanıcı etkileşiminden sonra render edilir. Otomatik tarayıcılar yalnızca ilk yüklemeyi gördüğünde bu butonları atlayabilir; gerçek kullanım senaryosunda kullanıcı oraya ulaştığında ise içerik mevcut olur. Bu yüzden geç yüklenen alanlar mutlaka ayrı test edilmelidir.
• Sembol metinler (×, +, →): × karakteri ekran okuyucuda “çarpı” ya da “kapalı çarpı” olarak seslendirilebilir. Bu semboller anlam taşımaz. Yanlarına mutlaka sr-only sınıfıyla anlamlı bir metin (“Kapat”, “Ekle”) eklenmelidir.
• title özniteliği: Dokunmatik cihazlarda hover olmadığı için görünmez, ekran okuyucularda da tutarsız davranır. Erişilebilir ad kaynağı olarak title'a güvenilmez.
• İkon kütüphanelerinin varsayılanı: FontAwesome, Material Icons, Heroicons ve benzerleri hiçbir zaman kendiliğinden bir aria-label üretmez. Her ikon butonun ayrı ayrı etiketlenmesi gerekir.

7. Nasıl test edilir?

1. axe DevTools tarayıcı eklentisi: Tek sayfayı anlık tarar. Geliştirme esnasında hızlı geri bildirim almak için en pratik araç.
2. Keysonar SEO Tools: Tüm siteyi otomatik tarar, etkilenen sayfaların listesini çıkarır, zaman içindeki gerilemeleri takip eder. DevTools açma zahmetine girmeden tüm raporu doğrudan panelden alabilirsiniz.
3. NVDA (Windows) / VoiceOver (macOS): Gerçek kullanıcı deneyimini görmek için manuel test. Tab tuşuyla tüm butonları gezin ve ekran okuyucunun ne seslendirdiğini not edin.
4. Lighthouse: Chrome DevTools'un erişilebilirlik denetimi. Daha kısa rapor üretir, sürekli entegrasyon (CI) süreçlerine kolaylıkla dahil edilebilir.

8. Hızlı kontrol listesi

• ✓Her <button> öğesi ya görünür bir metin ya aria-label ya da aria-labelledby içeriyor.
• ✓Yalnızca ikondan oluşan butonlar, sayfa diliyle aynı dilde bir aria-label taşıyor.
• ✓İçinde <img> bulunan butonların alt metni boş değil ya da butonun kendisinde aria-label var.
• ✓Sembol içerikli butonların (×, +) yanına sr-only sınıfıyla anlamlı metin ekledim.
• ✓Zaten görünür metni olan butona gereksiz yere aria-label EKLEMEDİM.
• ✓Buton içindeki dekoratif ikona aria-hidden="true" ekledim.
• ✓Modal, açılır menü gibi geç yüklenen butonları da test ettim.
• ✓title özniteliğini erişilebilir ad kaynağı olarak KULLANMADIM.

9. Referanslar

• WCAG 2.1 SC 4.1.2 — Name, Role, Value (Level A)
• WAI-ARIA Authoring Practices: Button pattern
• HTML Living Standard — The button element
• Accessible Name and Description Computation 1.2 (W3C)