Toolkit · Per sviluppatori

Accessibilità web per sviluppatori — pensata per ingegneri che preferiscono risolvere la causa radice piuttosto che aggiungere un overlay

La sezione ingegneristica del sito. Pattern HTML semantico, ruoli ARIA che funzionano davvero in produzione, framework di test compatibili con gli screen reader, ricette di integrazione CI e lo stato dell'arte per la gestione della tastiera in ogni framework.

Curato come punto di partenza: i pattern, gli strumenti, i framework di test e le guide specifiche per framework di cui gli ingegneri hanno realmente bisogno per rilasciare funzionalità accessibili senza il teatro degli overlay. Collegato allo scanner WCAG 2.2 gratuito per il triage una tantum e alla guida all'acquisto degli strumenti di monitoraggio per la copertura continuativa.

Le quattro pratiche ingegneristiche che fanno la differenza

Autorevoli. Non esaustive. I pattern che, se seguiti, eliminano la maggior parte delle regressioni di accessibilità prima della code review.

HTML semantico prima, ARIA dopo

Quando l'HTML nativo è sufficiente, è opportuno utilizzarlo. <button> include gestione della tastiera, focus, ruolo e attivazione con Enter/Space; <label> collega un controllo alla sua descrizione; <dialog> viene fornito con il comportamento di focus trap e inert del resto della pagina che altrimenti occorrerebbe implementare manualmente; <details> è un widget disclosure senza alcun JavaScript. ARIA è la via d'uscita — utile quando non esiste un elemento nativo per lo scopo, dannosa se aggiunta su uno che già funziona. Riferimento: i criteri di successo WCAG 2.2 e la W3C ARIA Authoring Practices Guide.

Il supporto da tastiera non è una casella da spuntare

Ogni elemento interattivo deve funzionare con la sola tastiera. Tab e Shift+Tab per spostarsi; Enter o Space per attivare; Esc per chiudere una superficie transitoria (modal, popover, menu). Il focus deve essere visibile — mai outline: none; senza sostituzione. Il focus deve spostarsi in modo logico — quando si apre un modal, il focus vi entra; quando il modal si chiude, il focus torna all'elemento che lo ha aperto. È opportuno testare con la tastiera prima di testare con il mouse; il mouse nasconde bug che la tastiera rivela immediatamente.

Nomi e descrizioni accessibili

Non si tratta di un uso indiscriminato di aria-label. Il nome accessibile deriva per impostazione predefinita dal contenuto testuale dell'elemento; aria-labelledby fa riferimento al testo di un altro nodo; aria-label sostituisce tutto con una stringa codificata (e dovrebbe essere usato come ultima risorsa, poiché bypassa la traduzione e tende a divergere dall'etichetta visibile). La descrizione accessibile è separata — aria-describedby fa riferimento al nodo con il testo di aiuto o il messaggio di errore. È opportuno verificare nell'albero di accessibilità di DevTools ciò che lo screen reader riceve effettivamente — le ipotesi e la realtà spesso non coincidono.

Testare nel CI reale, non solo in locale

Una verifica locale con axe è un test di sanità. Un CI verde è un gate contro le regressioni. È opportuno collegare eslint-plugin-jsx-a11y a ogni PR; aggiungere asserzioni con axe-core agli unit test e ai test e2e; eseguire flussi AT-driver su pagine rappresentative in modo che uno screen reader reale venga coinvolto. La rassegna degli strumenti di test con screen reader illustra cosa vale la pena automatizzare e cosa richiede ancora una verifica manuale.

Il toolkit — 13 strumenti e librerie selezionati

Ogni voce corrisponde a una fase del ciclo di vita — lint, unit test, e2e, runtime, monitoraggio o verifica manuale — per collegare lo strumento giusto al gate giusto.

Guide specifiche per framework

Le problematiche di accessibilità che si manifestano in modo diverso tra gli ecosistemi — e la copertura approfondita per ciascuno.

React

Key negli elenchi (elenchi con key errate confondono gli screen reader quando gli elementi vengono riordinati). Gestione del focus al cambio di route (senza di essa, il focus rimane sul link che ha avviato la navigazione e la nuova pagina risulta invisibile agli utenti di tecnologie assistive). Portal e focus trap — un modal renderizzato in document.body deve comunque mantenere il focus al proprio interno. Le mancate corrispondenze di idratazione che modificano la struttura del DOM tra SSR e client possono silenziosamente rompere le relazioni ARIA. Il nostro approfondimento sulle aria-live region nei framework moderni illustra il pattern di annuncio delle live region che la riconciliazione di React tende a interrompere.

Vue / Svelte / Solid

Pattern simili; i cambiamenti di stato reattivo non attivano aggiornamenti delle live region per impostazione predefinita. Il modello di reattività di ciascun framework ha una definizione diversa di «il DOM è cambiato», e gli screen reader vedono — o non vedono — il conseguente aggiornamento del nodo in modi sottilmente differenti. v-if rispetto a v-show in Vue, le dichiarazioni reattive di Svelte e la reattività a grana fine di Solid producono aggiornamenti diversi dell'albero di accessibilità per codice apparentemente identico.

Mobile nativo (iOS + Android)

Una superficie API completamente diversa. iOS espone UIAccessibility (e .accessibilityLabel() / .accessibilityHint() di SwiftUI) a VoiceOver; Android espone AccessibilityNodeInfo a TalkBack. ARIA in stile web non si traduce. Il materiale sulle API di accessibilità mobile nativo mappa i concetti web nei loro equivalenti nativi, in modo che gli ingegneri con formazione web smettano di procedere per tentativi.

Librerie di componenti

Le librerie headless (Radix UI, Headless UI, React Aria) gestiscono le parti difficili — gestione del focus, gestione della tastiera, cablaggio ARIA — lasciando il design visivo interamente allo sviluppatore. Le librerie complete (Material UI, Chakra, Ant) includono scelte visive predefinite ma variano notevolmente nella qualità dell'accessibilità, e «accessibile per impostazione predefinita» raramente significa «verificato con screen reader reali». La nostra rassegna delle librerie di componenti accessibili valuta le principali opzioni rispetto a test reali con tecnologie assistive.

Checklist di revisione PR per l'accessibilità

Da stampare, inserire nel template della PR o automatizzare in un bot. Il minimo a cui ogni revisore dovrebbe prestare attenzione.

  • Gli elementi interattivi funzionano con la sola tastiera (Tab + Enter + Space + Esc).
  • L'indicatore di focus è visibile su ogni elemento interattivo.
  • I campi del modulo hanno un <label> associato.
  • I messaggi di errore sono associati ai rispettivi campi (aria-describedby o testo adiacente).
  • Le modifiche ai contenuti dinamici vengono annunciate tramite aria-live quando appropriato.
  • I dialog modali intrappolano il focus e lo restituiscono all'elemento di apertura alla chiusura.
  • Le immagini hanno un testo alternativo significativo; le immagini decorative portano alt="".
  • Gli elenchi usano <ul> / <ol> / <dl> — non un'insalata di <div>.
  • La gerarchia dei titoli è logica (nessun livello saltato).
  • I test lint + axe superano il CI prima del merge.

Anti-pattern ingegneristici comuni

I pattern che superano la code review e poi si rompono in produzione. È opportuno intercettarli prima.

  • «L'overlay widget» — JavaScript di terze parti che sostiene di aggiungere accessibilità a un sito esistente. Non lo fa, spesso compromette il livello delle tecnologie assistive e ha generato una propria ondata di cause legali. Contesto: i vendor di overlay.
  • role="button" su un <div> — aggiunge l'annuncio del ruolo senza il comportamento da tastiera (Enter, Space) o la partecipazione all'ordine di tabulazione. È opportuno usare <button>.
  • aria-hidden="true" su elementi ricevibili con focus — crea un focus trap in cui gli utenti da tastiera possono posizionarsi su un elemento che lo screen reader è istruito a ignorare. Occorre o rimuovere l'elemento dall'ordine di tabulazione con tabindex="-1" o eliminare aria-hidden.
  • Menu a discesa personalizzato senza gestione da tastiera — un combobox basato su <div> che si apre al clic ma ignora i tasti freccia, Home/End, la digitazione anticipata e Esc. La rassegna delle librerie di componenti accessibili illustra le librerie che gestiscono correttamente questo aspetto fin dalla prima installazione.
  • Notifiche toast che non vengono annunciate — una superficie transitoria renderizzata senza role="status" (polite) o role="alert" (assertive). Gli utenti vedenti la vedono; gli utenti di screen reader no.
  • DOM generato che rompe l'albero di accessibilità — wrapper pesanti attorno a un input (un select personalizzato costruito con dodici <div> annidati) spesso nascono il controllo reale alle tecnologie assistive. È opportuno testare ciò che la tecnologia assistiva vede, non solo ciò che vede l'utente.

Il toolkit + la pipeline di monitoraggio

La maggior parte dei team ha bisogno di tre cose in sequenza: una scansione una tantum per il triage quando qualcosa sembra non funzionare; un riferimento ingegneristico per comprendere i pattern sottostanti; e un livello di monitoraggio continuo una volta che l'accessibilità entra nella roadmap di produzione. Il nostro scanner WCAG 2.2 gratuito copre il primo punto — si incolla un URL pubblico e si ottiene un rapporto basato su axe in una nuova scheda. La copertura ingegneristica della redazione copre il secondo — incluse analisi del debito di accessibilità come debito tecnico e degli incidenti di accessibilità come postmortem SRE per i team che gestiscono l'accessibilità su larga scala.

Per il livello continuativo, la guida all'acquisto degli strumenti di monitoraggio è il contenuto più autorevole del sito. Valuta axe Monitor, Siteimprove, Level Access e Qualibooth — l'ultimo dei quali integra il monitoraggio con il passaggio a un audit manuale, il pezzo mancante nella maggior parte degli stack solo automatizzati — rispetto all'ampiezza della copertura, ai tassi di falsi positivi e alla facilità con cui i dati si integrano nei flussi di lavoro ingegneristici. Il senso del monitoraggio è garantire che le correzioni rilasciate oggi non regrediscano nel prossimo sprint.

Domande frequenti degli ingegneri

Le domande che emergono in ogni riunione di avvio sull'accessibilità. Specchiate nei dati strutturati FAQPage.

aria-label è preferibile alle etichette testuali visibili?
No. Il testo visibile è quasi sempre preferibile — è utile per gli utenti vedenti, per gli utenti vedenti con disabilità cognitive, per gli utenti che usano il controllo vocale (che pronunciano ciò che vedono) e per gli strumenti di traduzione. Si dovrebbe ricorrere a aria-label solo quando non esiste testo visibile da associare (pulsanti con sola icona) o quando il testo visibile non corrisponde al nome accessibile desiderato.
È necessario utilizzare i ruoli ARIA per tutto?
No. La prima regola di ARIA è "do not use ARIA". Gli elementi HTML nativi includono già il ruolo corretto, il comportamento da tastiera corretto e la semantica corretta nell'albero di accessibilità. È opportuno usare ARIA solo quando (e soltanto quando) non esiste un elemento nativo adatto allo scopo — ad esempio un tab list, un tree o un dialog personalizzato in cui non è possibile utilizzare <dialog>.
Come si testa l'accessibilità in CI?
Tre livelli, ordinati per costo. (1) Lint: eslint-plugin-jsx-a11y su ogni PR. (2) Unit test: @testing-library/jest-dom più jest-axe (o @axe-core/react) su ogni componente. (3) End-to-end: @axe-core/playwright sui percorsi utente rappresentativi. Si aggiunge un gate Pa11y o Lighthouse CI nell'ambiente di staging per rilevare le derive che i livelli inferiori non intercettano.
axe-core e Lighthouse sono la stessa cosa?
Lighthouse utilizza axe-core sotto al cofano per il proprio audit di accessibilità, ma esegue un sottoinsieme selezionato delle regole e le presenta all'interno di un rapporto più ampio su performance, SEO e best practice. axe-core è il motore vero e proprio — quando si desidera il set completo di regole o si vuole estenderlo, si usa axe-core direttamente. Per la maggior parte dei team: Lighthouse per il monitoraggio delle tendenze, axe-core per il gate effettivo.
Qual è la configurazione minima per testare l'accessibilità in un progetto React?
Si aggiunge eslint-plugin-jsx-a11y alla configurazione ESLint esistente (incluso per impostazione predefinita in create-react-app e Next.js). Si aggiungono @testing-library/jest-dom e jest-axe alla configurazione per unit test e si chiama expect(await axe(container)).toHaveNoViolations() in almeno un test per ogni componente. Questo è il minimo indispensabile — rileva circa il 40% dei problemi WCAG reali con alcune ore di configurazione.
È necessario testare con screen reader reali?
Sì, per qualsiasi funzionalità del prodotto che un utente di tecnologia assistiva utilizzerà concretamente. Gli strumenti automatizzati rilevano gli errori strutturali (etichette mancanti, contrasto, mancata corrispondenza dei ruoli) ma non quelli funzionali (focus che salta al footer, live region che non annunciano, un modal «accessibile» che intrappola il focus nel sottoalbero sbagliato). È opportuno prevedere almeno una verifica manuale ad ogni rilascio principale con NVDA su Windows e VoiceOver su macOS / iOS.

Prossimi passi

Si esegue una verifica rapida con lo scanner WCAG 2.2 gratuito se si sta effettuando il triage di una pagina specifica. Si legge la rassegna degli strumenti di test con screen reader prima di collegare AT-driver al CI. E se l'accessibilità sta passando da «audit una tantum» a «impegno continuativo in produzione», la guida all'acquisto degli strumenti di monitoraggio è il contenuto più concreto del sito per scegliere un fornitore.