ARIA Authoring Practices Guide

La specifica ARIA definisce un vocabolario di ruoli, stati e proprietà. L’ ARIA Authoring Practices Guide spiega come usarli concretamente: quali interazioni da tastiera ogni pattern richiede, come si sposta il focus all’interno di un widget, cosa annunciare al cambio di stato, e come deve apparire il DOM.

Cosa contiene l’APG

L’APG documenta l’implementazione canonica di ogni pattern di widget che la specifica ARIA è stata progettata a supportare:

• Combobox (il pattern di autocompletamento con un comportamento da tastiera complesso che quasi tutti implementano in modo errato).
• Dialoghi — modali e non modali, con gestione completa del focus-trap e del ritorno del focus alla chiusura.
• Widget di disclosure (il semplice pattern mostra/nascondi).
• Menu e menu bar — quelli che richiedono la navigazione con i tasti freccia, non solo con il tasto Tab.
• Tab — coppie tab/tabpanel con navigazione a freccia e semantica di attivazione automatica o manuale.
• Treeview — navigazione gerarchica a struttura ad albero.
• Listbox — selezione singola e multipla.
• Spin button, slider, caroselli e molti altri.

Ogni pagina di pattern è composta da tre parti: un esempio funzionante dal vivo, la tabella delle interazioni da tastiera e gli attributi ARIA utilizzati in modo preciso. Sono presenti anche i pattern landmark — indicazioni su <header>, <nav>, <main> e i ruoli ARIA corrispondenti — e una sezione sugli anti-pattern che spiega cosa non fare.

Quando consultarla

L’APG è particolarmente utile quando si sta per costruire un widget privo di un elemento HTML nativo. Prima di scrivere una sola riga di codice, è opportuno verificare se l’APG contiene già il pattern. Quasi sempre:

• Le interazioni da tastiera necessarie sono già specificate.
• La struttura del DOM è già documentata.
• Gli attributi ARIA sono già definiti.

Saltare questo passaggio è il motivo per cui i team distribuiscono widget «accessibili» che confondono gli screen reader in modi che nessuno strumento automatico riesce a rilevare. L’APG è la differenza tra una combobox che funziona per tutti e una che compila, ma non funziona per gli utenti di screen reader.

Cosa l’APG non è esplicitamente

L’APG non è una specifica normativa. I documenti normativi sono la specifica ARIA stessa e WCAG. L’APG è una guida: implementare un widget esattamente come mostrato dall’APG è il percorso raccomandato, ma non l’unico ammissibile. Detto questo, deviare dall’APG senza una ragione documentata è un segnale che il pattern potrebbe non essere stato compreso a fondo.

L’APG, inoltre, non sostituisce l’HTML nativo. Se <select> funziona per il proprio menu a tendina, è opportuno usare <select> — non è necessario ricorrere al pattern combobox dell’APG solo perché sembra più avanzato.