Acessibilidade não é um recurso que você adiciona após o lançamento – é um atributo fundamental de qualidade, assim como desempenho ou segurança.
Parte da nossa série Conformidade e regulamentação
Leia o guia completoA conformidade com WCAG 2.1 AA é agora legalmente exigida na UE (Lei Europeia de Acessibilidade, aplicada em junho de 2025), nos EUA (jurisprudência do Título III da ADA) e em muitas outras jurisdições. Além da conformidade, as interfaces acessíveis convertem melhor, têm uma classificação mais elevada nas pesquisas e atendem cerca de 1,3 bilhão de pessoas com deficiência em todo o mundo.
Este guia é um manual prático de implementação e não uma lista de verificação. Você aprenderá os quatro princípios WCAG, as técnicas mais impactantes, como testar sistematicamente e como integrar a acessibilidade em seu fluxo de trabalho de desenvolvimento React/Next.js para que permaneça fixo.
Principais conclusões
- WCAG 2.1 AA exige todos os quatro princípios POUR: Perceptível, Operável, Compreensível, Robusto
- Comece com HTML semântico — ele fornece 70% de acessibilidade gratuitamente antes de qualquer ARIA ser adicionado
- Relação mínima de contraste de cores: 4,5:1 para texto normal, 3:1 para texto grande (18pt/14pt em negrito)
- Cada elemento interativo deve ser focalizável pelo teclado com um indicador de foco visível
- Os leitores de tela anunciam com base na árvore de acessibilidade — teste com NVDA (Windows) e VoiceOver (Mac)
- ARIA é um último recurso - apenas muda a forma como as tecnologias assistivas interpretam o DOM, não o comportamento
- Automatize com axe-core em seu pipeline de CI; o teste manual detecta o que a automação perde
- Documente sua declaração de acessibilidade e forneça um mecanismo de feedback para os usuários relatarem problemas
Os Quatro Princípios POUR
As WCAG 2.1 estão organizadas em torno de quatro princípios. Cada critério de sucesso pertence a um deles.
Perceptível: as informações devem ser apresentáveis de forma que os usuários possam percebê-las. Isso abrange alternativas de texto para imagens, legendas para vídeo, contraste de cores suficiente e conteúdo que não depende apenas da cor para transmitir significado.
Operável: todas as funcionalidades devem ser operáveis via teclado, com tempo suficiente para interagir, sem conteúdo que desencadeie convulsões e com estrutura navegável (pular links, títulos de páginas, ordem de foco).
Compreensível: o conteúdo deve ser legível e previsível. O idioma deve ser identificado, as mensagens de erro devem ser descritivas e os formulários devem ter rótulos claros e feedback de validação.
Robusto: o conteúdo deve ser interpretável por tecnologias assistivas atuais e futuras. Isso significa HTML válido, uso adequado de ARIA e mensagens de status anunciadas sem necessidade de foco.
HTML semântico primeiro
HTML semântico é o investimento único em acessibilidade de maior aproveitamento. Os elementos HTML nativos vêm com funções de acessibilidade, estados e comportamento de teclado integrados – sem necessidade de ARIA.
// BAD: Generic divs with no semantics
<div class="button" onclick="submit()">Submit</div>
<div class="nav">
<div class="link" onclick="navigate('/home')">Home</div>
</div>
// GOOD: Native semantics, free keyboard and screen reader support
<button type="submit" onClick={submit}>Submit</button>
<nav aria-label="Main navigation">
<a href="/home">Home</a>
</nav>
As regiões de referência ajudam os usuários de leitores de tela a navegar rapidamente, saltando entre as seções:
// Every page should have these landmarks
<header> {/* banner landmark */}
<nav aria-label="Main">...</nav>
</header>
<main> {/* main landmark */}
<h1>Page Title</h1>
<article>...</article>
<aside aria-label="Related content">...</aside>
</main>
<footer> {/* contentinfo landmark */}
<nav aria-label="Footer">...</nav>
</footer>
A hierarquia de títulos deve ser lógica e ininterrupta:
// BAD: Skipped heading levels
<h1>Page Title</h1>
<h3>Section</h3> {/* Skipped h2! */}
// GOOD: Sequential hierarchy
<h1>Page Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>
Contraste de cores
WCAG 2.1 AA requer:
- 4,5:1 relação de contraste para texto normal (abaixo de 18pt/14pt em negrito)
- Relação de contraste 3:1 para texto grande (18pt+ / 14pt+ negrito)
- 3:1 para componentes de UI e objetos gráficos (botões, ícones, bordas de entrada)
// Tailwind color contrast examples
// FAIL: gray-400 on white (#9ca3af on #fff = 2.8:1)
<p className="text-gray-400">This fails AA</p>
// PASS: gray-700 on white (#374151 on #fff = 10.7:1)
<p className="text-gray-700">This passes AA</p>
// For dark mode, test both themes separately
<p className="text-gray-700 dark:text-gray-300">
gray-700 on white (10.7:1) / gray-300 on gray-900 (9.2:1)
</p>
Use o WebAIM Contrast Checker ou a ferramenta de contraste DevTools do navegador durante o desenvolvimento. Adicione isto ao seu Storybook ou sistema de tokens de design para capturar regressões:
// contrast-checker.ts
import { getContrast } from 'polished';
function assertContrast(fg: string, bg: string, level: 'AA' | 'AAA' = 'AA') {
const ratio = getContrast(fg, bg);
const required = level === 'AA' ? 4.5 : 7;
if (ratio < required) {
throw new Error(
`Contrast ratio ${ratio.toFixed(2)}:1 fails WCAG ${level} (requires ${required}:1)`
);
}
}
Navegação pelo teclado
Cada elemento interativo – links, botões, campos de formulário, widgets personalizados – deve ser acessível e operável via teclado.
Gerenciamento de foco
// Skip link: first element on every page
// Allows keyboard users to jump past navigation
export function SkipLink() {
return (
<a
href="#main-content"
className="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4
focus:z-50 focus:px-4 focus:py-2 focus:bg-blue-600 focus:text-white
focus:rounded focus:ring-2 focus:ring-white"
>
Skip to main content
</a>
);
}
// Main content target
<main id="main-content" tabIndex={-1}>
{/* tabIndex={-1} allows programmatic focus without appearing in tab order */}
Focus Trapping em modais
Quando uma caixa de diálogo é aberta, o foco deve estar preso dentro dela. Quando fechado, o foco retorna ao gatilho:
// focus-trap.tsx using @radix-ui/react-focus-trap (used internally by shadcn Dialog)
import { Dialog, DialogContent, DialogTitle } from '@/components/ui/dialog';
import { useRef } from 'react';
export function AccessibleModal({ trigger, children, title }: Props) {
const triggerRef = useRef<HTMLButtonElement>(null);
return (
<Dialog>
<DialogTrigger ref={triggerRef} asChild>
<button>Open</button>
</DialogTrigger>
<DialogContent
// shadcn Dialog handles focus trap and returns focus to trigger on close
aria-describedby="dialog-description"
>
<DialogTitle>{title}</DialogTitle>
<p id="dialog-description" className="sr-only">
{/* Screen reader description of dialog purpose */}
</p>
{children}
</DialogContent>
</Dialog>
);
}
Indicadores de foco visíveis
WCAG 2.1 SC 2.4.11 (AA em WCAG 2.2) requer um contorno de foco mínimo de 2px. Nunca suprima o foco sem um substituto:
/* globals.css */
/* NEVER do this: */
:focus { outline: none; }
/* DO this: custom, visible focus ring */
:focus-visible {
outline: 2px solid hsl(var(--ring));
outline-offset: 2px;
border-radius: 4px;
}
/* Remove for mouse users (only show for keyboard) */
:focus:not(:focus-visible) {
outline: none;
}
ARIA: quando e como usá-lo
Os atributos ARIA (Accessible Rich Internet Applications) modificam a forma como as tecnologias assistivas interpretam o DOM. A primeira regra do ARIA: não use se existir um elemento HTML nativo para o seu caso de uso.
Etiquetas ARIA
// Icon-only button — screen reader has nothing to announce without aria-label
<button aria-label="Close dialog">
<X className="h-4 w-4" aria-hidden="true" />
</button>
// Form field with visible label — use htmlFor, not aria-label
<label htmlFor="email">Email address</label>
<input id="email" type="email" />
// Input with visible description
<input
id="password"
type="password"
aria-describedby="password-requirements"
/>
<p id="password-requirements">Must be at least 12 characters.</p>
Regiões ativas ARIA
Anuncie mudanças dinâmicas de conteúdo sem mudar o foco:
// Status messages (search results count, form submission status)
function SearchResults({ count, loading }: Props) {
return (
<>
{/* aria-live="polite" waits for user to finish current action */}
<div aria-live="polite" aria-atomic="true" className="sr-only">
{loading ? 'Loading results...' : `${count} results found`}
</div>
{/* Visual result count (not for screen readers — aria-hidden) */}
<span aria-hidden="true">{count} results</span>
</>
);
}
// Error messages (aria-live="assertive" interrupts immediately)
function FormError({ error }: { error: string | null }) {
return (
<div
role="alert"
aria-live="assertive"
className={cn('text-red-500 text-sm', !error && 'hidden')}
>
{error}
</div>
);
}
ARIA para widgets personalizados
Quando você precisar construir um widget personalizado (painel de guias, visualização em árvore, caixa de combinação), siga exatamente os padrões do ARIA Authoring Practices Guide (APG):
// Accessible tabs (ARIA tab pattern)
export function Tabs({ items }: { items: Tab[] }) {
const [active, setActive] = useState(0);
return (
<div>
<div role="tablist" aria-label="Content tabs">
{items.map((item, i) => (
<button
key={item.id}
role="tab"
aria-selected={active === i}
aria-controls={`panel-${item.id}`}
id={`tab-${item.id}`}
tabIndex={active === i ? 0 : -1} // Roving tabindex
onClick={() => setActive(i)}
onKeyDown={(e) => {
if (e.key === 'ArrowRight') setActive((active + 1) % items.length);
if (e.key === 'ArrowLeft') setActive((active - 1 + items.length) % items.length);
}}
>
{item.label}
</button>
))}
</div>
{items.map((item, i) => (
<div
key={item.id}
role="tabpanel"
id={`panel-${item.id}`}
aria-labelledby={`tab-${item.id}`}
hidden={active !== i}
>
{item.content}
</div>
))}
</div>
);
}
Formulários e tratamento de erros
Os formulários acessíveis estão entre as melhorias de maior impacto para usuários com deficiências cognitivas e motoras.
// Accessible form field with error state
function TextField({
id,
label,
error,
required,
hint,
...props
}: TextFieldProps) {
const hintId = hint ? `${id}-hint` : undefined;
const errorId = error ? `${id}-error` : undefined;
const describedBy = [hintId, errorId].filter(Boolean).join(' ') || undefined;
return (
<div>
<label htmlFor={id} className="font-medium">
{label}
{required && <span aria-hidden="true" className="text-red-500 ml-1">*</span>}
{required && <span className="sr-only">(required)</span>}
</label>
{hint && (
<p id={hintId} className="text-sm text-gray-500 mt-1">
{hint}
</p>
)}
<input
id={id}
aria-required={required}
aria-invalid={!!error}
aria-describedby={describedBy}
className={cn('input', error && 'border-red-500')}
{...props}
/>
{error && (
<p id={errorId} className="text-sm text-red-500 mt-1" role="alert">
{error}
</p>
)}
</div>
);
}
Imagens e mídia
// Informative image
<img src="/chart.png" alt="Bar chart showing 40% revenue growth in Q4 2025" />
// Decorative image — empty alt hides it from screen readers
<img src="/divider.png" alt="" role="presentation" />
// Complex image — use aria-describedby for long descriptions
<figure>
<img
src="/architecture.png"
alt="System architecture diagram"
aria-describedby="arch-desc"
/>
<figcaption id="arch-desc">
The diagram shows three tiers: frontend Next.js on port 3000,
NestJS API on port 3001, and PostgreSQL database on port 5433.
Redis sits between the API and database layers.
</figcaption>
</figure>
// SVG icons used as decoration
<svg aria-hidden="true" focusable="false">
<use href="#icon-search" />
</svg>
Teste automatizado com axe-core
pnpm add -D @axe-core/playwright axe-core
// tests/a11y/homepage.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test.describe('Homepage accessibility', () => {
test('should have no WCAG 2.1 AA violations', async ({ page }) => {
await page.goto('/');
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
.exclude('#third-party-widget') // Exclude known external violations
.analyze();
expect(results.violations).toEqual([]);
});
test('should be keyboard navigable', async ({ page }) => {
await page.goto('/');
// Tab through interactive elements and verify focus is visible
await page.keyboard.press('Tab');
const focusedElement = await page.evaluate(
() => document.activeElement?.getAttribute('href')
);
expect(focusedElement).toBe('#main-content'); // Skip link
});
});
Adicionar ao pipeline de CI:
# .github/workflows/ci.yml
- name: Run accessibility tests
run: cd apps/web && npx playwright test tests/a11y --reporter=html
- uses: actions/upload-artifact@v4
with:
name: a11y-report
path: apps/web/playwright-report/
Perguntas frequentes
Qual é a diferença entre WCAG 2.1 A, AA e AAA?
O Nível A é o mínimo – falhar no Nível A significa que o conteúdo é inacessível para alguns usuários de maneiras fundamentais. O nível AA é o padrão legal na maioria das jurisdições e atende às necessidades mais amplas dos usuários. O nível AAA é aspiracional – alguns critérios não podem ser atendidos para todos os tipos de conteúdo. Almeje a conformidade com AA como sua linha de base e busque AAA sempre que possível.
Usar uma biblioteca de componentes como shadcn/ui torna meu aplicativo acessível?
shadcn/ui é construído em primitivas de UI Radix, que são acessíveis por design – elas incluem funções ARIA corretas, navegação por teclado e gerenciamento de foco. No entanto, você ainda precisa adicionar rótulos significativos, lidar com estados de erro de forma acessível, garantir contraste de cores suficiente com seu tema personalizado e testar com tecnologias assistivas reais. As bibliotecas de componentes reduzem a carga, mas não eliminam a necessidade de testes de acessibilidade.
Como faço para testar com um leitor de tela?
No Windows, use o NVDA (gratuito) com Firefox ou Chrome. No macOS, use o VoiceOver (integrado, Cmd+F5) com Safari. No celular, use TalkBack (Android) ou VoiceOver (iOS). Teste as principais jornadas do usuário: preenchimento de formulários, interações modais, navegação por pontos de referência e leitura de conteúdo dinâmico. O teste do leitor de tela detecta anúncios, ordem de leitura e comportamento de foco que as ferramentas automatizadas não percebem.
Qual é o padrão de tabindex itinerante?
Roving tabindex é o padrão de teclado para widgets compostos (listas de guias, barras de ferramentas, grupos de rádio, visualizações em árvore). Apenas um item do grupo possui tabIndex={0} por vez — o item ativo. Todos os outros recebem tabIndex={-1}. As teclas de seta movem o foco dentro do grupo e atualizam qual item tem tabIndex 0. Isso evita que o usuário navegue por todos os itens do grupo - eles entram no grupo com Tab, navegam com as teclas de seta e saem com Tab.
Como lidar com a acessibilidade de conteúdo dinâmico carregado via AJAX?
Use regiões aria-live para atualizações de status (contagem de resultados de pesquisa, salvamento de confirmações). Para substituições de seções de páginas inteiras, mova o foco para o título ou contêiner do novo conteúdo após o carregamento. Para carregar estados, use aria-busy="true" na região que está sendo atualizada e uma região aria-live="polite" para anunciar a conclusão. Sempre teste com um leitor de tela para verificar se os anúncios são claros e oportunos.
Próximas etapas
A acessibilidade na Web é uma prática contínua, não uma auditoria única. Comece corrigindo seu HTML semântico e contraste de cores, depois coloque a navegação no teclado e ARIA para widgets complexos e automatize a validação WCAG em seu pipeline de CI para capturar regressões.
ECOSIRE constrói aplicativos da web compatíveis com WCAG 2.1 AA como um padrão básico em cada projeto. Se você precisar de uma auditoria de acessibilidade ou quiser criar conformidade desde o início, explore nossos serviços de engenharia de front-end.
Escrito por
ECOSIRE Research and Development TeamRedação técnica
A equipe de redação técnica da ECOSIRE escreve sobre Odoo ERP, e-commerce com Shopify, agentes de IA, análise de dados com Power BI, automação com GoHighLevel e boas práticas de software empresarial. Nossos guias ajudam as empresas a tomar decisões de tecnologia bem fundamentadas.
ECOSIRE
Expanda o seu negócio com ECOSIRE
Soluções empresariais em ERP, comércio eletrônico, IA, análise e automação.
Artigos Relacionados
ERP para Indústria Química: Segurança, Conformidade e Processamento em Lote
Como os sistemas ERP gerenciam documentos SDS, conformidade com REACH e GHS, processamento em lote, controle de qualidade, envio de materiais perigosos e gerenciamento de fórmulas para empresas químicas.
ERP para comércio de importação/exportação: multimoedas, logística e conformidade
Como os sistemas ERP lidam com cartas de crédito, documentação alfandegária, incoterms, lucros e perdas em várias moedas, rastreamento de contêineres e cálculo de taxas para empresas comerciais.
Relatórios de Sustentabilidade e ESG com ERP: Guia de Conformidade 2026
Navegue pela conformidade dos relatórios ESG em 2026 com sistemas ERP. Abrange emissões CSRD, GRI, SASB, escopo 1/2/3, rastreamento de carbono e sustentabilidade Odoo.
Mais de Conformidade e regulamentação
Cibersegurança para comércio eletrônico: proteja sua empresa em 2026
Guia completo de segurança cibernética de comércio eletrônico para 2026. PCI DSS 4.0, configuração WAF, proteção de bot, prevenção de fraudes em pagamentos, cabeçalhos de segurança e resposta a incidentes.
ERP para Indústria Química: Segurança, Conformidade e Processamento em Lote
Como os sistemas ERP gerenciam documentos SDS, conformidade com REACH e GHS, processamento em lote, controle de qualidade, envio de materiais perigosos e gerenciamento de fórmulas para empresas químicas.
ERP para comércio de importação/exportação: multimoedas, logística e conformidade
Como os sistemas ERP lidam com cartas de crédito, documentação alfandegária, incoterms, lucros e perdas em várias moedas, rastreamento de contêineres e cálculo de taxas para empresas comerciais.
Relatórios de Sustentabilidade e ESG com ERP: Guia de Conformidade 2026
Navegue pela conformidade dos relatórios ESG em 2026 com sistemas ERP. Abrange emissões CSRD, GRI, SASB, escopo 1/2/3, rastreamento de carbono e sustentabilidade Odoo.
Lista de verificação de preparação para auditoria: preparando seus livros
Lista de verificação completa para preparação de auditoria, cobrindo a preparação das demonstrações financeiras, documentação de suporte, documentação de controles internos, listas de PBC de auditores e descobertas comuns de auditoria.
Guia GST australiano para empresas de comércio eletrônico
Guia completo de GST australiano para empresas de comércio eletrônico, cobrindo registro ATO, limite de US$ 75.000, importações de baixo valor, apresentação de BAS e GST para serviços digitais.