Toolkit · Voor ontwikkelaars

Webtoegankelijkheid voor ontwikkelaars — gebouwd voor engineers die liever de grondoorzaak aanpakken dan een overlay uitrollen

Het engineeringgerichte deel van de site. Semantische HTML-patronen, ARIA-rollen die daadwerkelijk werken in productie, testharnesses die rekening houden met schermlezers, CI-integratierecipes en de stand van zaken per framework voor toetsenbordafhandeling.

Samengesteld als startpunt: de patronen, de tools, de testharnesses en de frameworkspecifieke gidsen die engineers daadwerkelijk nodig hebben om toegankelijke functies te leveren zonder overlay-theater. Gelinkt aan de gratis WCAG 2.2-scanner voor eenmalige triage en de monitoring-kopersguide voor doorlopende dekking.

De vier engineeringpraktijken die het verschil maken

Opinionated. Niet uitputtend. De patronen die, wanneer gevolgd, de meeste toegankelijkheidsregressies elimineren vóór code review.

Semantische HTML eerst, ARIA tweede

Wanneer native HTML het werk kan doen, gebruik het dan. <button> heeft toetsenbordafhandeling, focus, rol en Enter/Space-activering ingebouwd; <label> koppelt een besturingselement aan de beschrijving; <dialog> bevat het focusval- en inert-rest-of-page-gedrag dat men anders handmatig zou moeten implementeren; <details> is een disclosure-widget zonder enig JavaScript. ARIA is de nooduitgang — nuttig wanneer er geen native element beschikbaar is, schadelijk wanneer het wordt toegepast bovenop een element dat al werkt. Referentie: de WCAG 2.2-succescriteria en de W3C ARIA Authoring Practices Guide.

Toetsenbordondersteuning is geen afvinkpunt

Elk interactief element moet werken met alleen het toetsenbord. Tab en Shift+Tab om te navigeren; Enter of Space om te activeren; Esc om een tijdelijk oppervlak te sluiten (modaal, popover, menu). Focus moet zichtbaar zijn — nooit outline: none; zonder vervanging. Focus moet logisch bewegen — wanneer een modaal opent, gaat de focus daarin; wanneer het modaal sluit, keert de focus terug naar het element dat het opende. Test met het toetsenbord voordat u met de muis test; de muis verbergt fouten die het toetsenbord direct blootlegt.

Toegankelijke namen en beschrijvingen

Niet lukraak aria-label toevoegen. De toegankelijke naam komt standaard uit de tekstinhoud van het element; aria-labelledby verwijst naar de tekst van een ander knooppunt; aria-label overschrijft alles met een hardgecodeerde string (en moet uw laatste redmiddel zijn omdat het vertaling omzeilt en de neiging heeft te driften van het zichtbare label). De toegankelijke beschrijving is apart — aria-describedby verwijst naar het helptekst- of foutmeldingenknoop. Verifieer in de DevTools-toegankelijkheidsboom wat de schermlezer daadwerkelijk ontvangt — aannames en werkelijkheid lopen vaak uiteen.

Test in uw echte CI-omgeving, niet alleen lokaal

Een lokale axe-check is een sanity-test. Een groene CI is een regressiepoort. Koppel eslint-plugin-jsx-a11y aan elke PR; voeg axe-core-beweringen toe aan unit- en e2e-tests; voer AT-driver-flows uit op representatieve pagina's zodat een echte schermlezer meeweegt. Het overzicht van schermlezer-testtools behandelt wat de moeite waard is te automatiseren en wat nog een handmatige doorloop vereist.

De toolchain — 13 samengestelde tools en bibliotheken

Elk item komt overeen met een levenscyclusfase — lint, unit-test, e2e, runtime, monitoring of handmatige review — zodat u de juiste tool aan de juiste gate kunt koppelen.

Frameworkspecifieke gidsen

De toegankelijkheidsvalkuilen die per ecosysteem een andere vorm aannemen — en de diepere behandeling van elk.

React

Sleutels op lijsten (verkeerd gesleutelde lijsten verwarren schermlezers wanneer items herordenen). Focusbeheer bij routewijziging (zonder dit blijft focus op de link die de navigatie triggerde en is de nieuwe pagina onzichtbaar voor hulptechnologiegebruikers). Portals en focusvallen — een modaal gerenderd in document.body moet focus toch binnen zichzelf houden. Hydratatiemismatches die de DOM-structuur wijzigen tussen SSR en client kunnen ARIA-relaties stilletjes verbreken. Onze diepgaande behandeling van aria-live regions in moderne frameworks behandelt het live region-aankondigingspatroon dat React-reconciliatie neigt te verbreken.

Vue / Svelte / Solid

Vergelijkbare patronen; reactieve statuswijzigingen triggeren standaard geen live region-updates. Het reactieve model van elk framework heeft een andere definitie van "de DOM is gewijzigd", en schermlezers zien de resulterende knooppuntupdate — of zien die niet — op subtiel verschillende manieren. Vue's v-if tegenover v-show, Svelte's reactieve declaraties en Solid's fijnmazige reactiviteit produceren allemaal verschillende toegankelijkheidsboomupdates voor wat er hetzelfde code uitziet.

Native mobiel (iOS + Android)

Een volledig ander API-oppervlak. iOS stelt UIAccessibility bloot (en SwiftUI's .accessibilityLabel() / .accessibilityHint()) aan VoiceOver; Android stelt AccessibilityNodeInfo bloot aan TalkBack. Web-stijl ARIA vertaalt zich niet. Het artikel over native mobiele toegankelijkheids-API's brengt de webconcepten in kaart naar hun native tegenhangers zodat web-opgeleide engineers kunnen stoppen met gissen.

Componentbibliotheken

Headless bibliotheken (Radix UI, Headless UI, React Aria) nemen de moeilijke delen voor hun rekening — focusbeheer, toetsenbordafhandeling, ARIA-koppeling — en laten het visuele ontwerp volledig aan u. Volledige bibliotheken (Material UI, Chakra, Ant) leveren opinionated visuals maar variëren sterk in toegankelijkheidskwaliteit, en "standaard toegankelijk" betekent zelden "geauditeerd tegen echte schermlezers". Ons overzicht van toegankelijke componentbibliotheken beoordeelt de belangrijkste opties aan de hand van daadwerkelijk AT-testen.

PR-reviewchecklist voor toegankelijkheid

Afdrukken, in uw PR-template plakken of in een bot automatiseren. Het minimum waarop elke reviewer een blik moet werpen.

  • Interactieve elementen werken met alleen het toetsenbord (Tab + Enter + Space + Esc).
  • Focusindicator zichtbaar op elk interactief element.
  • Formulierinvoervelden hebben een gekoppeld <label>.
  • Foutmeldingen zijn gekoppeld aan hun invoervelden (aria-describedby of aangrenzende tekst).
  • Dynamische inhoudswijzigingen kondigen zich aan via aria-live waar van toepassing.
  • Modale dialogen houden focus vast en herstellen deze naar het openende element bij sluiting.
  • Afbeeldingen hebben betekenisvolle alternatieve tekst; decoratieve afbeeldingen dragen alt="".
  • Lijsten gebruiken <ul> / <ol> / <dl> — geen <div>-salade.
  • Koppenhiërarchie is logisch (geen overgeslagen niveaus).
  • Lint + axe-tests slagen in CI vóór samenvoegen.

Veelvoorkomende engineeringanti-patronen

De patronen die code review passeren en dan in productie stukgaan. Vang ze eerder.

  • De "overlay-widget" — JavaScript van derden dat beweert toegankelijkheid toe te voegen aan een bestaande site. Dat doet het niet, het verbreekt regelmatig de hulptechnologielaag en heeft zijn eigen golf van rechtszaken gegenereerd. Achtergrond: overlay-leveranciers.
  • role="button" op een <div> — voegt de rolmelding toe zonder het toetsenbordgedrag (Enter, Space) of deelname aan de focusvolgorde. Gebruik <button>.
  • aria-hidden="true" op focusbare elementen — creëert een focusval waarbij toetsenbordgebruikers op een element kunnen tabben dat de schermlezer wordt opgedragen te negeren. Verwijder het element uit de tabulatievolgorde met tabindex="-1" of verwijder de aria-hidden.
  • Aangepast uitklapmenu zonder toetsenbordafhandeling — een <div>-gebaseerde combobox die opent bij klik maar pijltoetsen, Home/End, type-ahead en Esc negeert. Het overzicht van toegankelijke componentbibliotheken behandelt de bibliotheken die dit standaard correct doen.
  • Toastmeldingen die niet aankondigen — een tijdelijk oppervlak gerenderd zonder role="status" (beleefd) of role="alert" (assertief). Ziende gebruikers zien het; schermlezergebruikers niet.
  • Gegenereerde DOM die de toegankelijkheidsboom verbreekt — zware wrappers rond een invoerveld (een aangepaste select gebouwd van twaalf geneste <div>s) verbergen het eigenlijke besturingselement vaak voor hulptechnologie. Test wat de hulptechnologie ziet, niet alleen wat de gebruiker ziet.

De Toolkit + monitoringpipeline

De meeste teams willen drie dingen in volgorde: een eenmalige triagescan wanneer iets er kapot uitziet, een engineeringreferentie wanneer men de onderliggende patronen wil begrijpen, en een doorlopende monitoringlaag zodra toegankelijkheid in de productieplanning is opgenomen. Onze gratis WCAG 2.2-scanner dekt het eerste — plak een publieke URL, ontvang een axe-gedreven rapport in een nieuw tabblad. De engineeringdekking bij de redactiedesk dekt het tweede — inclusief toegankelijkheidsschuld-als-technische-schuld en toegankelijkheidsincidenten-SRE-postmortem-analyses voor teams die toegankelijkheid op schaal beheren.

Voor de doorlopende laag is de monitoring-kopersguide het meest opinionated stuk op de site. Het beoordeelt axe Monitor, Siteimprove, Level Access en Qualibooth — het laatste integreert monitoring met een handmatige-audit-overdracht, het ontbrekende stuk in de meeste uitsluitend geautomatiseerde stacks — op dekkingsbreedte, percentage valse positieven en hoe schoon de data aansluit op engineeringworkflows. Het hele punt van monitoring is ervoor zorgen dat de fixes die u vandaag uitrolt niet regresseren in de volgende sprint.

Veelgestelde engineeringvragen

De vragen die bij elke toegankelijkheidskickoff terugkomen. Gespiegeld in de FAQPage-gestructureerde data.

Is aria-label beter dan zichtbare tekstlabels?
Nee. Zichtbare tekst is bijna altijd beter — het is nuttig voor ziende gebruikers, ziende gebruikers met cognitieve beperkingen, gebruikers van spraakbediening (die zeggen wat ze zien) en vertaalhulpmiddelen. Gebruik aria-label alleen wanneer er geen zichtbare tekst te koppelen is (knoppen met alleen een pictogram) of wanneer de zichtbare tekst werkelijk niet de gewenste toegankelijke naam is.
Moet ik ARIA-rollen voor alles gebruiken?
Nee. De eerste regel van ARIA is "do not use ARIA". Native HTML-elementen bevatten de juiste rol, het juiste toetsenbordgedrag en de juiste toegankelijkheidsboomsemantieken ingebouwd. Gebruik ARIA wanneer (en alleen wanneer) er geen native element is dat past — bijvoorbeeld een tabulijst, een boomstructuur of een aangepast dialoogvenster waarvoor u geen <dialog> kunt gebruiken.
Hoe test ik toegankelijkheid in CI?
Drie lagen, geordend op kosten. (1) Lint: eslint-plugin-jsx-a11y bij elke PR. (2) Unit-tests: @testing-library/jest-dom plus jest-axe (of @axe-core/react) bij elk component. (3) End-to-end: @axe-core/playwright op representatieve gebruikersreizen. Voeg een Pa11y- of Lighthouse CI-gate toe op staging om de drift te vangen die de lagere lagen missen.
Zijn axe-core en Lighthouse hetzelfde?
Lighthouse gebruikt axe-core onder de motorkap voor zijn toegankelijkheidsaudit, maar voert een samengestelde subset van de regels uit en presenteert deze binnen een breder prestatie- / SEO- / best-practices-rapport. axe-core zelf is de motor — wanneer u de volledige regelset wilt of wilt uitbreiden, gebruikt u axe-core rechtstreeks. Voor de meeste teams: gebruik Lighthouse voor trendopvolging, axe-core voor de daadwerkelijke gate.
Wat is de minimale toegankelijkheidstestopzet voor een React-project?
Voeg eslint-plugin-jsx-a11y toe aan de bestaande ESLint-configuratie (standaard meegeleverd met create-react-app en Next.js). Voeg @testing-library/jest-dom en jest-axe toe aan uw unit-testopzet en roep expect(await axe(container)).toHaveNoViolations() aan in ten minste één test per component. Dat is de ondergrens — het vangt circa 40% van de echte WCAG-problemen voor een paar uur installatiewerk.
Moet ik testen met echte schermlezers?
Ja, voor elke productfunctie die een gebruiker van hulptechnologie daadwerkelijk zal gebruiken. Geautomatiseerde tooling vangt de structurele fouten (ontbrekende labels, contrast, rolmismatches) maar niet de ervaringsgerichte (focus die naar de voettekst springt, live regions die niet aankondigen, een "toegankelijk" modaal dat focus vasthoudt in de verkeerde substructuur). Plan ten minste één handmatige doorloop per grote release met NVDA op Windows en VoiceOver op macOS / iOS.

Volgende stappen

Voer een snelle check uit met de gratis WCAG 2.2-scanner als u een specifieke pagina triageert. Lees het overzicht van schermlezer-testtools voordat u AT-driver in CI integreert. En als toegankelijkheid verschuift van "eenmalige audit" naar "doorlopende productiezorg", is de monitoring-kopersguide het meest concrete stuk op de site voor het kiezen van een leverancier.