Zestaw narzędzi · Dla programistów

Dostępność internetowa dla programistów — stworzona dla inżynierów, którzy wolą usuwać przyczynę źródłową, niż dodawać overlay

Inżynierska część serwisu. Semantyczne szablony HTML, role ARIA działające rzeczywiście na produkcji, testy zgodne z czytnikami ekranu, przepisy na integrację z CI oraz aktualny stan obsługi klawiatury dla każdego frameworka.

Przygotowany jako punkt startowy: szablony, narzędzia, konfiguracje testów i przewodniki specyficzne dla frameworków, których inżynierowie faktycznie potrzebują, by dostarczać dostępne funkcjonalności bez teatru overlayowego. Połączony z bezpłatnym skanerem WCAG 2.2 do jednorazowego triaż i z przewodnikiem wyboru narzędzia do monitorowania na potrzeby ciągłej obserwacji.

Cztery praktyki inżynierskie, które naprawdę mają znaczenie

Kategoryczne, nie wyczerpujące. Szablony, których stosowanie eliminuje większość regresji dostępności przed code review.

Semantyczny HTML na pierwszym miejscu, ARIA na drugim

Gdy natywny HTML może wykonać zadanie, należy go użyć. <button> ma wbudowaną obsługę klawiatury, fokus, rolę i aktywację przez Enter/Space; <label> wiąże kontrolkę z jej opisem; <dialog> ma wbudowane zachowanie pułapki fokusa i wyszarzenie reszty strony, które inaczej trzeba by implementować ręcznie; <details> to widget ujawniania bez żadnego JavaScript. ARIA jest wyjściem awaryjnym — przydatnym, gdy nie istnieje natywny element do danego zadania, szkodliwym, gdy nakłada się ją na element, który już działa. Materiały pomocnicze: kryteria sukcesu WCAG 2.2 oraz przewodnik po praktykach autorskich W3C ARIA.

Obsługa klawiatury to nie punkt na liście do odhaczenia

Każdy element interaktywny musi działać wyłącznie za pomocą klawiatury. Tab i Shift+Tab do poruszania się; Enter lub Space do aktywacji; Esc do zamykania powierzchni przejściowych (modal, popover, menu). Fokus musi być widoczny — nigdy outline: none; bez zamiennika. Fokus musi przemieszczać się logicznie — gdy modal się otwiera, fokus wchodzi do niego; gdy modal się zamyka, fokus wraca do elementu, który go otworzył. Należy testować klawiaturą przed testowaniem myszą; mysz ukrywa błędy, które klawiatura natychmiast ujawnia.

Dostępne nazwy i opisy

Nie posypywać aria-label wszędzie. Dostępna nazwa pochodzi domyślnie z treści tekstowej elementu; aria-labelledby odwołuje się do tekstu innego węzła; aria-label zastępuje wszystko zakodowanym na stałe ciągiem znaków (i powinien być ostatecznością, gdyż omija tłumaczenie i jest podatny na rozbieżność z widoczną etykietą). Dostępny opis to osobna rzecz — aria-describedby odwołuje się do węzła z tekstem pomocniczym lub komunikatem o błędzie. Należy sprawdzać w drzewie dostępności DevTools, co czytnik ekranu rzeczywiście otrzymuje — założenia i rzeczywistość często się rozchodzą.

Testuj w rzeczywistym środowisku CI, nie tylko lokalnie

Lokalne sprawdzenie axe to test rozsądku. Zielone CI to bramka przeciwko regresji. Należy podłączyć eslint-plugin-jsx-a11y do każdego PR; dodać asercje axe-core w testach jednostkowych i e2e; uruchamiać przepływy AT-driver na reprezentatywnych stronach, by włączyć rzeczywisty czytnik ekranu. Przegląd narzędzi do testowania czytnikami ekranu opisuje, co warto automatyzować, a co nadal wymaga ręcznego przeglądu.

Zestaw narzędzi — 13 wyselekcjonowanych narzędzi i bibliotek

Każda pozycja odpowiada fazie cyklu życia — lint, test jednostkowy, e2e, runtime, monitorowanie lub przegląd ręczny — by dopasować właściwe narzędzie do właściwej bramki.

Przewodniki specyficzne dla frameworków

Problemy z dostępnością, które ujawniają się inaczej w różnych ekosystemach — i ich dogłębniejsze omówienie dla każdego z nich.

React

Klucze na listach (nieprawidłowo ustawione listy dezorientują czytniki ekranu przy zmianie kolejności elementów). Zarządzanie fokusem przy zmianie trasy (bez niego fokus pozostaje na łączu, które uruchomiło nawigację, a nowa strona jest niewidoczna dla użytkowników technologii wspomagających). Portale i pułapka fokusa — modal renderowany w document.body nadal musi trzymać fokus wewnątrz siebie. Niezgodności hydratacji zmieniające strukturę DOM między SSR a klientem mogą po cichu zrywać powiązania ARIA. Nasz szczegółowy artykuł o regionach aria-live we współczesnych frameworkach omawia wzorzec ogłaszania regionów live, który reconciliacja Reacta ma tendencję do naruszania.

Vue / Svelte / Solid

Podobne wzorce; zmiany stanu reaktywnego domyślnie nie wyzwalają aktualizacji regionów live. Model reaktywności każdego frameworka ma inną definicję „DOM się zmienił" i czytniki ekranu widzą — lub nie widzą — wynikową aktualizację węzła na subtelnie różne sposoby. v-if kontra v-show w Vue, reaktywne deklaracje Svelte i drobnoziarnista reaktywność Solid produkują różne aktualizacje drzewa dostępności dla pozornie identycznego kodu.

Natywne tworzenie aplikacji mobilnych (iOS + Android)

Zupełnie inny zestaw API. iOS udostępnia UIAccessibility (i .accessibilityLabel() / .accessibilityHint() dla SwiftUI) na potrzeby VoiceOver; Android udostępnia AccessibilityNodeInfo dla TalkBack. ARIA w stylu webowym nie ma tu zastosowania. Materiał o natywnych mobilnych API dostępności zestawia koncepcje webowe z ich natywnymi odpowiednikami, by inżynierowie wychowani na webie przestali zgadywać.

Biblioteki komponentów

Biblioteki bezgłowe (Radix UI, Headless UI, React Aria) przejmują trudne zadania — zarządzanie fokusem, obsługę klawiatury, wiązanie ARIA — pozostawiając projektowanie wizualne całkowicie w rękach zespołu. Biblioteki pełnofunkcjonalne (Material UI, Chakra, Ant) mają własne zdanie co do warstwy wizualnej, ale ich jakość pod kątem dostępności znacznie się różni, a „dostępny domyślnie" rzadko oznacza „testowany z rzeczywistymi czytnikami ekranu". Nasz przegląd dostępnych bibliotek komponentów ocenia główne opcje na podstawie rzeczywistych testów z technologiami wspomagającymi.

Lista kontrolna przeglądu PR pod kątem dostępności

Można wydrukować, wstawić do szablonu PR lub zautomatyzować w bocie. Minimum, na które każdy recenzent powinien zwrócić uwagę.

  • Elementy interaktywne działają wyłącznie za pomocą klawiatury (Tab + Enter + Space + Esc).
  • Wskaźnik fokusa jest widoczny na każdym elemencie interaktywnym.
  • Pola formularza mają skojarzony <label>.
  • Komunikaty o błędach są skojarzone z odpowiednimi polami (aria-describedby lub sąsiadujący tekst).
  • Zmiany treści dynamicznej są ogłaszane przez aria-live tam, gdzie jest to konieczne.
  • Okna dialogowe modal trzymają fokus i zwracają go do elementu otwierającego przy zamknięciu.
  • Obrazy mają znaczący tekst alternatywny; obrazy dekoracyjne mają alt="".
  • Listy używają <ul> / <ol> / <dl> — nie zupy <div>.
  • Hierarchia nagłówków jest logiczna (bez pominiętych poziomów).
  • Testy lint + axe przechodzą w CI przed scaleniem.

Częste antypatwerny inżynierskie

Wzorce przechodzące code review i psujące się na produkcji. Należy je wychwytywać wcześniej.

  • „Overlay widget" — skrypt JavaScript strony trzeciej, który twierdzi, że dodaje dostępność do istniejącej witryny. Nie robi tego, często narusza warstwę technologii wspomagających i sam w sobie wygenerował falę pozwów sądowych. Kontekst: dostawcy overlayów.
  • role="button" na <div> — dodaje ogłoszenie roli bez zachowania klawiaturowego (Enter, Space) ani udziału w kolejności tabulacji. Należy używać <button>.
  • aria-hidden="true" na elementach, które można sfokusować — tworzy pułapkę fokusa, w której użytkownicy klawiatury mogą trafić na element, który czytnik ekranu ma ignorować. Należy albo usunąć element z kolejności tabulacji przez tabindex="-1", albo usunąć aria-hidden.
  • Niestandardowa lista rozwijana bez obsługi klawiatury — combobox oparty na <div>, otwierający się kliknięciem, ale ignorujący klawisze strzałek, Home/End, wprowadzanie znaków i Esc. Przegląd dostępnych bibliotek komponentów omawia biblioteki, które obsługują to poprawnie od razu po instalacji.
  • Powiadomienia toast, które nie są ogłaszane — powierzchnia przejściowa renderowana bez role="status" (polite) lub role="alert" (assertive). Widzący użytkownicy ją widzą; użytkownicy czytników ekranu — nie.
  • Generowany DOM psujący drzewo dostępności — grube opakowania wokół input (niestandardowy select zbudowany z dwunastu zagnieżdżonych <div>) często ukrywają rzeczywistą kontrolkę przed technologiami wspomagającymi. Należy testować to, co widzi technologia wspomagająca, a nie tylko to, co widzi użytkownik.

Zestaw narzędzi + pipeline monitorowania

Większość zespołów potrzebuje trzech rzeczy po kolei: jednorazowego skanowania przy triaż, gdy coś wydaje się zepsute; inżynierskiego materiału referencyjnego, gdy chce się zrozumieć podstawowe wzorce; oraz ciągłej warstwy monitorowania, gdy dostępność weszła już do produkcyjnej mapy drogowej. Nasz bezpłatny skaner WCAG 2.2 pokrywa pierwszą potrzebę — wystarczy podać publiczny URL i otrzymać raport oparty na axe w nowej karcie. Inżynierska treść działu redakcyjnego pokrywa drugą — w tym analizy długu dostępności jako długu technicznego oraz incydentów dostępności jako postmortemów SRE dla zespołów zarządzających dostępnością w skali.

W przypadku warstwy ciągłej, przewodnik wyboru narzędzia do monitorowania jest najbardziej konkretnym materiałem w serwisie. Ocenia axe Monitor, Siteimprove, Level Access i Qualibooth — ten ostatni integruje monitorowanie z przekazaniem do ręcznego audytu, co jest brakującym ogniwem w większości stosów opartych wyłącznie na automatyzacji — pod kątem szerokości pokrycia, wskaźnika fałszywych trafień oraz tego, jak czysto dane integrują się z procesami inżynierskimi. Celem monitorowania jest zapewnienie, że poprawki dostarczone dziś nie ulegną regresji w następnym sprincie.

Często zadawane pytania inżynierskie

Pytania pojawiające się na każdej pierwszej rozmowie o dostępności. Odzwierciedlone w strukturze danych FAQPage.

Czy aria-label jest lepsze od widocznych etykiet tekstowych?
Nie. Widoczny tekst jest prawie zawsze lepszy — jest przydatny dla widzących użytkowników, widzących użytkowników z dysfunkcjami poznawczymi, użytkowników sterowania głosem (mówią to, co widzą) oraz narzędzi do tłumaczenia. Należy sięgać po aria-label wyłącznie wtedy, gdy nie ma widocznego tekstu do skojarzenia (przyciski tylko z ikoną) lub gdy widoczny tekst naprawdę nie jest pożądaną dostępną nazwą.
Czy należy używać ról ARIA do wszystkiego?
Nie. Pierwsza zasada ARIA brzmi "do not use ARIA". Natywne HTML elementy mają właściwą rolę, właściwe zachowanie klawiaturowe i właściwą semantykę w drzewie dostępności. Należy używać ARIA tylko wtedy (i wyłącznie wtedy), gdy nie istnieje natywny element odpowiedni do danego celu — na przykład lista kart, drzewo lub niestandardowe okno dialogowe, w przypadku którego nie można użyć <dialog>.
Jak testować dostępność w CI?
Trzy warstwy ułożone według kosztu. (1) Lint: eslint-plugin-jsx-a11y przy każdym PR. (2) Testy jednostkowe: @testing-library/jest-dom plus jest-axe (lub @axe-core/react) dla każdego komponentu. (3) End-to-end: @axe-core/playwright na reprezentatywnych ścieżkach użytkownika. Należy dodać bramkę Pa11y lub Lighthouse CI w środowisku staging, aby wychwycić regresje pominięte przez niższe warstwy.
Czy axe-core i Lighthouse to to samo?
Lighthouse używa axe-core pod maską do przeprowadzania audytu dostępności, ale uruchamia wyselekcjonowany podzbiór reguł i prezentuje je w ramach szerszego raportu dotyczącego wydajności / SEO / dobrych praktyk. axe-core to sam silnik — gdy potrzebny jest pełny zestaw reguł lub gdy chce się go rozszerzyć, należy używać axe-core bezpośrednio. Dla większości zespołów: Lighthouse do śledzenia trendów, axe-core jako właściwa bramka.
Jaka jest minimalna konfiguracja testowania dostępności w projekcie React?
Należy dodać eslint-plugin-jsx-a11y do istniejącej konfiguracji ESLint (dostarczany domyślnie z create-react-app i Next.js). Dodać @testing-library/jest-dom i jest-axe do konfiguracji testów jednostkowych i wywoływać expect(await axe(container)).toHaveNoViolations() w co najmniej jednym teście dla każdego komponentu. To jest minimum — wychwytuje około 40% rzeczywistych problemów WCAG przy kilku godzinach konfiguracji.
Czy testowanie za pomocą rzeczywistych czytników ekranu jest konieczne?
Tak, dla każdej funkcjonalności produktu, z której rzeczywiście będzie korzystać użytkownik technologii wspomagającej. Automatyczne narzędzia wykrywają błędy strukturalne (brakujące etykiety, kontrast, niezgodności ról), ale nie funkcjonalne (fokus przeskakujący do stopki, regiony live nieogłaszające zmian, „dostępny" modal trzymający fokus w złym poddrzewie). Należy zaplanować co najmniej jeden ręczny przegląd każdego głównego wydania z NVDA na Windows i VoiceOver na macOS / iOS.

Następne kroki

Warto przeprowadzić szybkie sprawdzenie za pomocą bezpłatnego skanera WCAG 2.2, jeśli przeprowadza się triaż konkretnej strony. Należy przeczytać przegląd narzędzi do testowania czytnikami ekranu przed podłączeniem AT-driver do CI. A jeśli dostępność przechodzi z „jednorazowego audytu" do „stałej troski produkcyjnej", przewodnik wyboru narzędzia do monitorowania jest najbardziej konkretnym materiałem w serwisie dotyczącym wyboru dostawcy.