Falhas de acessibilidade no Lighthouse

O que esta verificação faz

Conta quantas auditorias de acessibilidade do Lighthouse falharam na página. O Lighthouse corre o axe-core por baixo e agrupa os resultados em pass/fail/manual. Esta regra reporta a contagem de falhas e lista-as — o medidor da pontuação de acessibilidade Lighthouse é o número de destaque, esta regra é a lista de tarefas.

Os infratores típicos que o MetricSpot expõe:

• color-contrast — texto abaixo do rácio de contraste 4.5:1 AA.
• image-alt — <img> sem alt (diferente da qualidade do texto alternativo, que pontua o significado).
• link-name / button-name — elementos interativos sem nome acessível (botões só com ícone são os culpados habituais).
• label — controlos de formulário sem <label> associado.
• html-has-lang / html-lang-valid — cobertos por declarar idioma da página.
• document-title — <title> vazio ou em falta.
• aria-* — papéis inválidos, atributos obrigatórios em falta, ou aria-hidden em elementos focáveis.
• list / listitem — <li> fora de um pai <ul>/<ol>.

Porque é importante

As falhas do Lighthouse são a metade corrigível da acessibilidade. Cada auditoria nesta lista é algo que um agente de build pode verificar mecanicamente — sem julgamento humano. São também as auditorias com maior probabilidade de surgir numa queixa legal: contraste e labels em falta em formulários são as duas questões mais citadas em processos de acessibilidade web ADA nos EUA, e a Lei da Acessibilidade da UE (em vigor desde junho de 2025) lê a mesma checklist.

Levar esta contagem a zero não torna o site totalmente conforme com WCAG — cerca de um terço dos critérios WCAG 2.1 AA exigem revisão manual — mas remove as objeções de menor esforço.

Como corrigir

Lê as falhas por ordem. Cada falha do Lighthouse inclui um snippet “Failing elements” — esse é o teu ponto de partida.

Vê a lista por auditoria:

• Lighthouse CLI / DevTools — corre uma auditoria, faz scroll até “Accessibility”, clica em cada entrada vermelha para a lista de elementos em falha.
• PageSpeed Insights — pagespeed.web.dev/?url=<o-teu-url> devolve as mesmas auditorias com seletores de elementos.
• DevTools → painel Issues — o Chrome 109+ expõe problemas axe-core em direto enquanto navegas.

Liga-o à CI. Não dependas de humanos a clicar no Lighthouse. Adiciona o axe-core à tua suite e2e:

bun add -D @axe-core/playwright axe-playwright

// e2e/a11y.spec.ts
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

test("home has no detectable a11y violations", async ({ page }) => {
  await page.goto("/");
  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21aa"])
    .analyze();
  expect(results.violations).toEqual([]);
});

Para builds React/Next/Astro, adiciona também eslint-plugin-jsx-a11y para apanhar as óbvias em lint time.

As 5 correções top de uma linha:

Falha	Correção
color-contrast	Sobe o primeiro plano ou o fundo até o rácio passar 4.5:1 (3:1 para texto 18pt+). Usa o color picker do DevTools — mostra o rácio em direto.
image-alt	Adiciona alt="...". Para imagens puramente decorativas, usa alt="" (vazio, não ausente). Vê texto alternativo de imagens.
button-name	<button>s só com ícone precisam de aria-label="Fechar menu". Os SVGs por dentro precisam de aria-hidden="true".
link-name	Igual a botões. Envolve links de ícone com texto descritivo ou aria-label. Vê texto de ligação descritivo.
label	Envolve o <input> num <label>, ou usa <label for="id"> + id="id". Vê etiquetas de formulário.

Se a pontuação for n/a em vez de uma contagem, vê Lighthouse acessibilidade indisponível — a auditoria não correu.

Perguntas frequentes

Corrigir todas as falhas leva-me aos 100?

Costumas ficar nos 90+. A pontuação de acessibilidade do Lighthouse é ponderada mas não linear — color-contrast pesa muito, outras pouco. Os pontos restantes vêm muitas vezes de verificações manuais (ordem de foco, narração de leitor de ecrã) que a auditoria automática lista como “Additional items to manually check.”

Posso suprimir auditorias com que discordo?

Sim, via o array skipAudits da config do Lighthouse, mas pensa bem antes de suprimir. O falso-positivo comum é color-contrast em hero banners com texto sobre imagem — corrige o contraste (adiciona um overlay ou fundo sólido) em vez de saltar a auditoria.

Em que é diferente do axe-core nas DevTools?

Não é mesmo. O Lighthouse empacota o axe-core e corre um subconjunto das suas regras. A extensão axe das DevTools corre o conjunto completo, pelo que podes ver mais problemas lá — esses extras costumam ter tag best-practice e não são exigidos pelo WCAG.