Acessibilidade

Os componentes seguem HTML nativo quando existe uma semântica equivalente e usam os padrões WAI-ARIA APG somente para widgets que não têm equivalente completo. A referência de conformidade é WCAG 2.2 AA. Axe ajuda a encontrar regressões, mas não substitui testes manuais.

O que o consumidor precisa fornecer

• Um label visível para cada controle; o nome acessível deve conter o texto apresentado.
• Texto de ajuda e erro associado por aria-describedby ou aria-errormessage.
• Mensagem textual de correção, além de aria-invalid="true" quando o erro for mostrado.
• name, value, checked e selected coerentes quando o controle participar de formulário.
• IDs estáveis quando usar aria-labelledby, aria-describedby ou aria-controls.

Não use placeholder, cor, ícone ou tooltip como único meio de comunicar instrução, obrigatoriedade ou erro. Não adicione roles redundantes nem tabindex positivo.

Foco e teclado

Widget	Referência	Operação
botão/link	button/a	Tab; Enter e Espaço no botão
checkbox/switch	checkbox/switch APG	Espaço alterna
radio	radio group APG	setas, Home/End e roving tabindex
slider	slider APG	setas, Home/End e páginas
select/combobox	select/listbox APG	setas, Enter/Espaço e Escape
collapse	details/summary	Enter/Espaço; toggle
modal	dialog APG	foco inicial, contenção, Escape e retorno
tabs/menu	tabs/menu APG	roving tabindex, setas, Home/End e Escape
tooltip	tooltip APG	abre por foco/hover, fecha com Escape, nunca recebe foco

Os controles de formulário delegam focus() ao elemento nativo no Shadow DOM. Relações ARIA não atravessam automaticamente Shadow Roots: o componente mantém as referências internas ou o consumidor deve fornecer a relação no escopo correto.

Estados e mensagens

aria-invalid, aria-checked, aria-selected, aria-expanded, aria-current e valores de slider devem acompanhar o estado real. Para mensagens dinâmicas, use uma região de status com texto estável e não mova o foco sem necessidade. Em modais, devolva o foco ao acionador ao fechar.

Verificação

Antes de publicar uma aplicação, verifique em viewport de 320 CSS px e zoom de 200%/400%, contraste, forced colors, prefers-reduced-motion, navegação somente por teclado e leitores de tela. A checklist mínima é:

• NVDA + Firefox;
• VoiceOver + Safari;
• TalkBack + Chrome;
• Tab/Shift+Tab, setas, Home/End, Enter/Espaço e Escape.

Consulte o contrato de plataforma e APG para limitações de SSR/hydration e o guia de formulários para erros de formulário.