Contrato da plataforma, APG e WCAG
Este documento registra o contrato de implementação. A referência normativa é o HTML Standard, complementada pelos padrões APG quando HTML não oferece o widget completo. ARIA descreve comportamento existente; não substitui teclado, foco ou estado.
Mapeamento
| Família | Referência preferida | Teclado e foco essenciais |
|---|---|---|
| botão, magic button | button | Enter e Espaço ativam; foco visível |
| link, breadcrumb, skip link, paginação | a, nav, listas | Tab; Enter segue o link; página atual com aria-current |
| input, textarea, upload | input, textarea | comportamento nativo, label associado e erro descrito |
| checkbox e switch | checkbox / APG switch | Espaço alterna; checked ou aria-checked sincronizado |
| radio | radio group | setas mudam opção; um único item na ordem de Tab |
| select | select, combobox/listbox | setas, Home/End e Escape conforme o modo |
| slider | range / APG slider | setas, Home, End, Page Up e Page Down |
| collapse | details/summary | Enter e Espaço alternam; evento toggle |
| modal | dialog | foco inicial, contenção, Escape e retorno ao acionador |
| tooltip | APG tooltip | abre por foco/hover, fecha com Escape e não recebe foco |
| tabs | APG tabs | roving tabindex, setas, Home/End e painel associado |
| menu | APG menu | setas, Home/End, Enter/Espaço e Escape |
| carousel | APG carousel | pausa controlável, alternativa a arrastar e anúncios moderados |
| table | tabela nativa; grid apenas se editável | navegação nativa ou teclado completo do grid |
| step e wizard | lista/roving tabindex | estado atual determinável e foco previsível |
IDs usados por aria-labelledby, aria-describedby, aria-errormessage e aria-controls precisam existir no mesmo escopo de árvore. Uma referência textual não atravessa automaticamente um Shadow Root. Quando a relação cruza esse limite, o componente deve manter a relação dentro do próprio Shadow DOM ou usar referências de elementos do ElementInternals quando disponíveis.
SSR e hydration
Não leia window, document, medidas de layout ou preferências de mídia durante a renderização no servidor. Essas APIs pertencem aos callbacks executados no cliente e devem ter guarda de ambiente. Timers e observers precisam ser removidos em disconnectedCallback.
Quando o ID participa do HTML hidratado, forneça custom-id estável a partir dos dados da aplicação. O gerador automático atual garante unicidade no cliente, mas usa tempo e aleatoriedade e, portanto, não é uma fonte determinística entre servidor e cliente. Essa é uma limitação conhecida da série 2.x; fixtures de SSR devem sempre fornecer IDs explícitos até a migração para uma estratégia determinística compatível com múltiplas requisições.
