WAI-ARIA é uma especificação técnica do W3C que adiciona atributos HTML para tornar componentes web dinâmicos, como modais, accordions e menus, acessíveis a tecnologias assistivas. Mantida pela Web Accessibility Initiative desde 2014 e atualizada para a versão 1.2 em 2023, é o padrão que o próprio core do WordPress adota.
Se você gerencia um site WordPress em escala, com dezenas de editores publicando por dia e um time de TI sempre no limite, sabe que a acessibilidade quase nunca lidera a fila de prioridades. O problema é silencioso: você compra um tema no marketplace, instala um plugin de menu, adiciona um bloco Gutenberg customizado, e cada um desses componentes destrói a marcação WAI-ARIA que o core entregava de graça. Ninguém percebe até um usuário de leitor de tela abandonar a página ou até chegar uma notificação sobre a Lei Brasileira de Inclusão.
Neste guia mostramos o que é WAI-ARIA na prática, por que sites mid-market falham mesmo com o core acessível, como aplicar landmarks e componentes interativos, e quais ferramentas usar para auditar tudo isso em escala.
WAI-ARIA (Web Accessibility Initiative, Accessible Rich Internet Applications) é um conjunto de atributos que você adiciona ao HTML existente para descrever o papel, o estado e as propriedades de um elemento a tecnologias assistivas. Ele não muda nada visualmente na tela. Muda tudo para quem depende de um leitor de tela, um teclado ou um comando de voz para navegar.
A grande vantagem para times de desenvolvimento é que você não refaz componentes. Interfaces ricas construídas com JavaScript, React ou Gutenberg apenas ganham atributos extras na marcação que já existe. Você pode consultar a especificação oficial WAI-ARIA 1.2 do W3C para o detalhamento completo dos atributos.
O tamanho do problema é maior do que parece. Segundo o relatório WebAIM Million 2024, 95,9% das homepages analisadas apresentaram falhas de acessibilidade detectáveis segundo o WCAG. Ou seja, o site inacessível é a regra, não a exceção. E o público excluído é real: dados do Censo 2022 do IBGE apontam que cerca de 18% da população brasileira com mais de dois anos declara ter algum tipo de deficiência. Muitas dessas pessoas navegam exclusivamente com tecnologia assistiva.
Essa é a parte que raramente aparece nos artigos genéricos de front-end. O core do WordPress leva acessibilidade a sério desde 2014. O painel administrativo, os temas padrão (como Twenty Twenty-Four) e os blocos nativos do Gutenberg já vêm com marcação WAI-ARIA correta. Existe até um handbook de acessibilidade do WordPress mantido por um time dedicado.
O problema não mora no core. Mora em três lugares:
<div> sem role, sliders sem foco de teclado e headers sem landmarks.aria-expanded, aria-controls e o gerenciamento de foco, quebrando componentes que o usuário de leitor de tela nem consegue identificar.aria-expanded dinâmico simplesmente não comunica estado.Agora multiplique isso pela escala. Num WordPress mid-market com 200 editores publicando por dia, cada novo post pode reutilizar um bloco quebrado, embutir um shortcode de plugin inacessível ou herdar um template que já perdeu os landmarks. Auditar isso componente por componente, uma vez, não resolve. O problema volta no próximo deploy.
E há a camada legal. A Lei Brasileira de Inclusão (Lei 13.146/2015) determina que sites e serviços digitais brasileiros sejam acessíveis. Para empresas mid-market e enterprise, especialmente em Educação e Serviços, isso deixou de ser um item opcional de backlog e virou risco jurídico ativo.
O WAI-ARIA se organiza em três pilares. Entender essa divisão é o primeiro passo para aplicar a especificação sem cometer erros que pioram a experiência em vez de melhorá-la.
<div> usada como caixa de diálogo recebe role="dialog" para que o leitor de tela a anuncie como um modal, e não como texto solto.aria-expanded="true" e aria-expanded="false" conforme o usuário interage.aria-label.| Pilar | O que define | Exemplo de atributo | Quando usar |
|---|---|---|---|
| Roles | A função semântica do elemento na interface | role="dialog", role="search" | Quando o HTML nativo não comunica a função (ex: div usada como modal) |
| States | O estado atual e mutável do elemento | aria-expanded="true", aria-hidden="false" | Em componentes cujo estado muda via JavaScript (accordions, menus) |
| Properties | Características fixas que ajudam o usuário | aria-label, aria-describedby | Para rótulos, descrições e relações que o HTML sozinho não expressa |
Os landmarks são o ponto de partida mais simples e útil do WAI-ARIA. Eles marcam regiões navegáveis da página, como cabeçalho, conteúdo principal, navegação e busca. Com eles, um usuário de leitor de tela pula direto para a seção que precisa, sem percorrer a página inteira elemento por elemento.
Veja uma marcação comum de tema, sem landmarks, em um header.php ou footer.php:
<div class="wrapper"></div> <form class="frm-search">...</form> <nav class="menu">...</nav>
Agora a mesma estrutura com landmarks e rótulos:
<main class="wrapper" aria-label="Conteúdo principal"></main> <form class="frm-search" role="search" aria-label="Busca de conteúdo">...</form> <nav class="menu" aria-label="Menu de editorias">...</nav>
Repare que usamos a tag <main> em vez de role="main". Essa é a regra de ouro: HTML5 semântico primeiro, WAI-ARIA como complemento. O W3C resume isso na máxima “No ARIA is better than Bad ARIA”, ou seja, marcação errada é pior do que marcação nenhuma. Você pode aprofundar no guia de uso do ARIA pelo W3C.
O role="search" permanece porque não existe tag HTML nativa equivalente ao papel de busca. Já o aria-label é essencial em regiões que se repetem, como duas navegações na mesma página. Sem rótulo, o leitor de tela anuncia apenas “navegação” duas vezes, e o usuário não sabe qual é qual.
É nos widgets interativos que o WAI-ARIA mostra todo o seu valor. Accordions, modais, abas e menus mobile são construídos com <div> e JavaScript, sem semântica nativa. Sem atributos, o leitor de tela não sabe se um painel está aberto, fechado ou sequer existe.
Veja um accordion acessível, típico de uma seção de FAQ ou de detalhes de plano:
<button aria-expanded="false" aria-controls="painel-1"> Detalhes do plano </button> <div id="painel-1" role="region" aria-hidden="true"> ... </div>
Quando o usuário clica, o JavaScript alterna aria-expanded para true e aria-hidden para false. O leitor de tela anuncia a mudança em tempo real. Os atributos que mais aparecem nesse contexto são:
No Gutenberg, o cenário é ainda mais crítico porque a interface é React e muda constantemente sem recarregar a página. Ao criar um bloco customizado, você marca a acessibilidade dentro do próprio componente de edição e salvamento. Um exemplo simplificado da função save de um accordion custom:
export default function save( { attributes } ) {
const blockProps = useBlockProps.save();
return (
<div { ...blockProps }>
<button aria-expanded={ attributes.isOpen } aria-controls="painel-bloco">
{ attributes.titulo }
</button>
<div id="painel-bloco" role="region" aria-hidden={ ! attributes.isOpen }>
{ attributes.conteudo }
</div>
</div>
);
}O ponto de atenção: useBlockProps cuida das classes e da estrutura do bloco, mas não adiciona atributos WAI-ARIA sozinho. Quem garante o aria-expanded e o aria-hidden dinâmicos é o desenvolvedor. Para exemplos prontos de padrões acessíveis, vale consultar a documentação ARIA da MDN.
Você não descobre um problema de WAI-ARIA olhando a tela. Descobre auditando. Existem quatro ferramentas que cobrem a maior parte dos cenários de um WordPress em escala, e a escolha certa depende de onde você quer rodar a verificação.
| Ferramenta | Tipo de auditoria | Onde roda | Cobertura de regras WCAG | Integração CI/CD |
|---|---|---|---|---|
| axe DevTools | Estática + runtime | Extensão de navegador | ~57% (fonte: Deque) | Sim, via axe-core |
| Lighthouse | Estática | Chrome DevTools / CLI | Subset baseado em axe-core | Sim, via lighthouse-ci |
| WAVE | Estática visual | Extensão / API | WCAG 2.1 AA | Sim, via API paga |
| pa11y-ci | Estática automatizada | Node.js CLI | WCAG 2.1 AAA | Nativa, headless Chrome |
Na prática, o fluxo que recomendamos é este: use o axe DevTools da Deque ou o Lighthouse durante o desenvolvimento para pegar erros óbvios, o WAVE para uma inspeção visual das landmarks e do contraste, e o pa11y-ci dentro do pipeline de deploy para bloquear regressões automaticamente.
Esse último ponto é o que separa auditoria pontual de auditoria contínua. Rodar o axe uma vez numa landing page é fácil. O desafio real de um WordPress mid-market é que a acessibilidade quebra a cada plugin atualizado, a cada tema recompilado, a cada bloco novo publicado. Ferramenta automática cobre parte do problema, mas testes automatizados detectam apenas cerca de 57% das regras WCAG, segundo a Deque. O restante exige validação manual com leitor de tela real (NVDA, VoiceOver) e navegação por teclado.
Aqui na Apiki, dentro do nosso serviço de WP Care, tratamos acessibilidade como rotina, não como projeto. Medimos com ferramentas automáticas, marcamos os componentes que quebraram WAI-ARIA, validamos com leitor de tela e repetimos a verificação a cada deploy. Isso resolve o gap que nenhum time interno mid-market tem bandwidth para cobrir sozinho: auditar componente por componente, deploy após deploy, sem parar a operação de conteúdo.
Aplicar WAI-ARIA errado costuma ser pior do que não aplicar. Os equívocos que mais encontramos em temas e plugins WordPress seguem sempre a mesma lógica: alguém adicionou ARIA achando que ajudava, mas atropelou a semântica nativa.
<nav role="navigation"> é repetição pura. A tag <nav> já comunica essa função nativamente. O mesmo vale para <main role="main"> e <button role="button">.aria-expanded="false" e nunca atualizar o valor via JavaScript é um dos erros mais comuns em menus mobile de tema. O leitor de tela anuncia “fechado” mesmo com o menu aberto.O padrão por trás de todos eles é o mesmo: WAI-ARIA complementa o HTML, nunca o substitui. E, num site com múltiplos editores e dezenas de plugins, o problema quase nunca é falta de conhecimento técnico. É falta de auditoria contínua. Ninguém colocou esses erros de propósito. Eles entraram junto com um plugin novo, um tema atualizado ou um bloco reaproveitado, e ninguém tinha um processo para pegá-los antes do usuário.
Não. WAI-ARIA é um complemento, não um substituto. A regra do W3C é usar elementos HTML nativos sempre que possível, porque eles já trazem semântica, foco de teclado e estados embutidos. Só recorra ao WAI-ARIA quando o HTML nativo não expressa o comportamento necessário, como em um modal ou um accordion feito com <div>.
Não. Se o botão já tem texto visível descritivo, como “Enviar formulário”, o aria-label é desnecessário e pode até atrapalhar. O aria-label só é obrigatório quando o botão não tem texto, como um ícone de menu ou um X de fechar, onde o leitor de tela não teria o que anunciar.
De forma indireta, sim. WAI-ARIA em si não é fator de ranqueamento, mas a marcação semântica correta, os landmarks e a estrutura clara que acompanham uma boa implementação ajudam os buscadores a entender a página. Acessibilidade e SEO técnico compartilham a mesma base: um HTML bem estruturado.
Comece por ferramentas automáticas como axe DevTools, Lighthouse ou WAVE, que apontam erros de marcação sem exigir leitor de tela. Depois, navegue a página inteira usando apenas o teclado (Tab, Enter, Esc e setas). Se você consegue acionar todos os componentes pelo teclado e o foco fica sempre visível, você já corrigiu boa parte dos problemas.
Os blocos nativos do Gutenberg vêm com marcação WAI-ARIA correta, porque o core do WordPress cuida disso. Blocos customizados criados pelo seu time, porém, dependem inteiramente de quem os desenvolveu. O useBlockProps não adiciona atributos ARIA dinâmicos sozinho: cabe ao desenvolvedor marcar aria-expanded, aria-hidden e afins.
A Lei Brasileira de Inclusão (Lei 13.146/2015) exige que sites e serviços digitais sejam acessíveis, mas não cita o WAI-ARIA por nome. Na prática, atingir esse nível de acessibilidade em componentes dinâmicos sem WAI-ARIA é inviável. Portanto, ele se torna a ferramenta técnica para cumprir a obrigação legal.
O WCAG (Web Content Accessibility Guidelines) é o conjunto de diretrizes que define o que torna um conteúdo acessível, com critérios de sucesso mensuráveis. O WAI-ARIA é uma especificação técnica com atributos concretos que ajudam a atingir vários desses critérios em componentes dinâmicos. Em resumo: WCAG diz o objetivo, WAI-ARIA oferece parte das ferramentas.
WAI-ARIA é o que mantém acessíveis os componentes dinâmicos do seu site: modais, accordions, menus e blocos Gutenberg que o HTML sozinho não descreve. O core do WordPress já faz a sua parte. O risco real mora nos temas de terceiros, plugins e blocos customizados que, a cada deploy, podem destruir essa marcação sem que ninguém perceba.
Num WordPress mid-market com múltiplos editores publicando todos os dias, auditar isso uma única vez não resolve. A acessibilidade quebra de novo no próximo plugin atualizado. É por isso que tratamos WAI-ARIA como rotina dentro do nosso WP Care: medimos com ferramentas automáticas, marcamos os componentes que falharam, validamos com leitor de tela e repetimos a cada deploy. Se o seu time não tem bandwidth para auditar componente por componente enquanto a operação de conteúdo continua rodando, fale com o nosso time e transforme acessibilidade em processo contínuo, não em incêndio pontual.
Bruno Pulis 
Leandro Vieira Pinho 
Ngoma Fortuna 
