Acessibilidade

Acessibilidade na Prática

WCAG 2.1 AA no mundo real

Guia prático com exemplos de código reais extraídos deste projeto: ARIA, foco, semântica HTML, contraste e um checklist para usar em todos os PRs.

Este guia foca em boas práticas de desenvolvimento. Para auditoria profissional de acessibilidade, consulte um especialista certificado em WCAG.

ARIA Roles, Labels e Live Regions

ARIA (Accessible Rich Internet Applications) completa o HTML onde a semântica nativa não é suficiente. Use apenas quando necessário — HTML semântico é sempre preferível.

Roles Comuns

role="dialog"	Modais e dialogs	Combine com aria-modal="true" e focus trap
role="alert"	Mensagens de erro urgentes	Lido automaticamente por screen readers
role="status"	Atualizações não urgentes	Menos intrusivo que alert
role="progressbar"	Barras de progresso	Adicione aria-valuenow, aria-valuemin e aria-valuemax
role="tablist"	Grupos de abas	Combine com role="tab" e role="tabpanel"

❌ Ruim — sem semântica

❌ ruim

<!-- ❌ Sem contexto — screen reader lê "botão" sem saber o que faz -->
<button>
  <X className="h-4 w-4" />
</button>
 
<!-- ❌ Placeholder não é acessível como label -->
<input type="email" placeholder="Email" />

✅ Bom — semântico

✅ bom

<!-- ✅ Botões com contexto semântico claro -->
<button aria-label="Fechar diálogo de configurações">
  <X className="h-4 w-4" />
</button>
 
<button aria-label="Editar perfil de João Silva">
  <Pencil className="h-4 w-4" />
</button>
 
<!-- ✅ aria-describedby para detalhes adicionais -->
<input
  id="email"
  type="email"
  aria-describedby="email-hint"
/>
<p id="email-hint" className="text-sm text-muted-foreground">
  Use seu email corporativo
</p>

Live Regions

Para conteúdo que atualiza dinamicamente sem reload de página:

aria-live="polite"

Lê quando o usuário para de digitar. Ideal para notificações.

aria-live="assertive"

Lê imediatamente. Apenas para erros críticos.

aria-live="off"

Desabilita atualizações dinâmicas (padrão).

Gerenciamento de Foco

Usuários de teclado dependem do foco visível e previsível. Focus traps, skip links e retorno ao elemento de origem são essenciais.

Skip Link

O primeiro elemento focável da página — permite pular para o conteúdo principal sem navegar por toda a navegação.

skip-link.tsx

// src/components/skip-link.tsx
export function SkipLink() {
  return (
    <a
      href="#main-content"
      className="
        sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4
        focus:z-50 focus:rounded-lg focus:bg-primary focus:px-4
        focus:py-2 focus:text-sm focus:font-medium focus:text-primary-foreground
      "
    >
      Pular para o conteúdo principal
    </a>
  );
}
 
// Em layout.tsx
<SkipLink />
<header>...</header>
<main id="main-content">...</main>

Focus Trap em Modais

Enquanto um modal está aberto, Tab e Shift+Tab devem circular apenas dentro do modal.

focus-trap.tsx

// Focus trap simples para modais
function trapFocus(container: HTMLElement) {
  const focusable = container.querySelectorAll<HTMLElement>(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];
 
  container.addEventListener("keydown", (e) => {
    if (e.key !== "Tab") return;
 
    if (e.shiftKey) {
      if (document.activeElement === first) {
        e.preventDefault();
        last.focus();
      }
    } else {
      if (document.activeElement === last) {
        e.preventDefault();
        first.focus();
      }
    }
  });
}

Foco Visível

Nunca remova o outline de foco sem fornecer um substituto visível. Este projeto usa Tailwind focus-visible.

→Ao abrir modal: mova o foco para o primeiro elemento interativo
→Ao fechar modal: retorne o foco ao elemento que o abriu
→Tab deve circular dentro do modal (focus trap)
→Escape deve fechar e retornar o foco
→Use focus-visible em vez de focus para não afetar mouse/touch

HTML Semântico

O HTML semântico correto é a base da acessibilidade. Screen readers usam landmarks para navegação rápida.

Landmarks e Hierarquia

Cada landmark cria um ponto de navegação para screen readers.

<header>	banner	Cabeçalho da página (logo, nav principal)
<nav>	navigation	Navegação principal ou secundária
<main>	main	Conteúdo principal — apenas 1 por página
<section>	region	Seção com aria-labelledby
<aside>	complementary	Conteúdo relacionado mas secundário
<footer>	contentinfo	Rodapé da página

❌ Ruim — sem semântica

❌ ruim

<!-- ❌ Div soup — nenhuma informação semântica -->
<div class="header">
  <div class="nav">
    <div class="nav-item">Home</div>
  </div>
</div>
<div class="main">
  <div class="title">Título</div>
  <div class="content">...</div>
</div>

✅ Bom — semântico

✅ bom

<!-- ✅ HTML semântico — screen readers entendem a estrutura -->
<header>
  <nav aria-label="Navegação principal">
    <ul>
      <li><a href="/">Home</a></li>
    </ul>
  </nav>
</header>
 
<main id="main-content">
  <article>
    <h1>Título da Página</h1>
    <section aria-labelledby="section-title">
      <h2 id="section-title">Seção</h2>
      <p>Conteúdo...</p>
    </section>
  </article>
</main>
 
<footer>
  <p>© 2025 Dev Showcase</p>
</footer>

Live Region — Anúncios Dinâmicos

live-region.tsx

// ✅ Anúncio de estado para screen readers
function SearchResults({ count }: { count: number }) {
  return (
    <>
      {/* Visualmente escondido mas lido por screen readers */}
      <div
        role="status"
        aria-live="polite"
        aria-atomic="true"
        className="sr-only"
      >
        {count === 0
          ? "Nenhum resultado encontrado"
          : `${count} resultados encontrados`}
      </div>
 
      {/* Conteúdo visual */}
      <ul>{/* ... */}</ul>
    </>
  );
}

Contraste de Cores — WCAG AA

WCAG 2.1 AA exige contraste mínimo de 4.5:1 para texto normal e 3:1 para texto grande (18pt ou 14pt negrito).

Requisitos WCAG 2.1 AA

Texto normal (< 18pt)	4.5:1	AA
Texto grande (≥ 18pt ou 14pt bold)	3:1	AA
Componentes UI e gráficos	3:1	AA
Texto normal	7:1	AAA

Ferramentas de Verificação

WebAIM Contrast Checker

Verificador online simples e rápido

axe DevTools

Extensão do browser — auditoria automática

Lighthouse

Auditoria integrada ao Chrome DevTools

Color.review

Preview visual com foreground/background

Checklist de Acessibilidade para PRs

Revise estes itens antes de abrir um Pull Request com qualquer mudança de interface.

Todos os botões têm texto ou aria-label descritivo

Imagens têm alt text (ou alt="" se decorativas)

Contraste de texto ≥ 4.5:1 (WCAG AA)

Foco visível em todos os elementos interativos

Hierarquia de headings sem pular níveis

Navegação por Tab funciona sem mouse

Modais têm focus trap e fecham com Escape

Conteúdo dinâmico usa aria-live ou role="alert"

Skip link visível ao focar com Tab

Testado com screen reader (NVDA/VoiceOver/Orca)

Acessibilidade é para Todos

1 em cada 6 pessoas no mundo tem alguma deficiência. Código acessível não é opcional — é responsabilidade profissional.

Ver mais guias

Ver no GitHub

Conteúdo relacionado

Dicas de IA para DesenvolvedoresGuia prático de ferramentas IA, uso consciente de tokens e modelos: v0, Copilot, prompt engineering, boas práticas e ferramentas para produtividade dev.

Tailwind CSS + shadcn/ui — Guia PráticoSetup completo, componentes reutilizáveis, padrões de código e boas práticas com Tailwind CSS e shadcn/ui para projetos React e Next.js.

React Query Essencial — Cache e MutationsGuia completo de TanStack Query (React Query): cache inteligente, mutations, invalidação, otimistic updates e boas práticas para apps React.

12 min de leitura

</button>

</button>

</button>

<input

id="email"

type="email"

aria-describedby="email-hint"

Use seu email corporativo

</p>

// src/components/skip-link.tsx

export function SkipLink() {

return (

href="#main-content"

className="

sr-only focus:not-sr-only focus:fixed focus:left-4 focus:top-4

focus:z-50 focus:rounded-lg focus:bg-primary focus:px-4

focus:py-2 focus:text-sm focus:font-medium focus:text-primary-foreground

Pular para o conteúdo principal

</a>

);

}

// Em layout.tsx

// Focus trap simples para modais

function trapFocus(container: HTMLElement) {

const focusable = container.querySelectorAll<HTMLElement>(

'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'

);

const first = focusable[0];

const last = focusable[focusable.length - 1];

container.addEventListener("keydown", (e) => {

if (e.key !== "Tab") return;

if (e.shiftKey) {

if (document.activeElement === first) {

e.preventDefault();

last.focus();

}

} else {

if (document.activeElement === last) {

e.preventDefault();

first.focus();

}

});

}

</div>

<div class="title">Título</div>

</div>

<ul>

</ul>

</nav>

</header>

<h1>Título da Página</h1>

<h2 id="section-title">Seção</h2>

<p>Conteúdo...</p>

</section>

</article>

</main>

</footer>

// ✅ Anúncio de estado para screen readers

function SearchResults({ count }: { count: number }) {

return (

{/* Visualmente escondido mas lido por screen readers */}

<div

role="status"

aria-live="polite"

aria-atomic="true"

className="sr-only"

{count === 0

? "Nenhum resultado encontrado"

: `${count} resultados encontrados`}

</div>

{/* Conteúdo visual */}

</>

);

}