Errori di accessibilità in Lighthouse

Cosa verifica questo controllo

Conta quanti audit di accessibilità di Lighthouse sono falliti sulla pagina. Lighthouse esegue axe-core sotto al cofano e raggruppa i risultati in pass/fail/manual. Questa regola riporta il conteggio dei fail e li elenca — l’indicatore del punteggio di accessibilità Lighthouse è il numero principale, questa regola è la to-do list.

I colpevoli tipici che MetricSpot fa emergere:

• color-contrast — testo sotto il rapporto di contrasto AA 4,5:1.
• image-alt — <img> senza alt (diverso da qualità dell’alt-text immagini, che ne valuta il significato).
• link-name / button-name — elementi interattivi senza nome accessibile (i pulsanti con sola icona sono il sospetto classico).
• label — controlli di form senza un <label> associato.
• html-has-lang / html-lang-valid — coperti da dichiarare la lingua della pagina.
• document-title — <title> vuoto o mancante.
• aria-* — ruoli non validi, attributi obbligatori mancanti o aria-hidden su elementi focalizzabili.
• list / listitem — <li> fuori da un genitore <ul>/<ol>.

Perché è importante

I fallimenti di Lighthouse sono la metà risolvibile dell’accessibilità. Ogni audit di questa lista è qualcosa che un build agent può verificare meccanicamente — niente giudizio umano richiesto. Sono anche gli audit che più spesso finiscono in un reclamo legale: contrasto e label di form mancanti sono le due questioni più citate nelle cause USA sull’accessibilità web ai sensi dell’ADA, e l’European Accessibility Act (in vigore da giugno 2025) legge la stessa checklist.

Portare a zero questo conteggio non rende il sito pienamente conforme a WCAG — circa un terzo dei criteri WCAG 2.1 AA richiede revisione manuale — ma elimina le obiezioni a costo minore.

Come sistemarlo

Leggi i fallimenti in ordine. Ogni fallimento di Lighthouse include uno snippet “Failing elements” — quello è il punto di partenza.

Vedi la lista per audit:

• Lighthouse CLI / DevTools — esegui un audit, scorri ad “Accessibility”, clicca su ogni voce rossa per la lista degli elementi falliti.
• PageSpeed Insights — pagespeed.web.dev/?url=<tuo-url> restituisce gli stessi audit con i selettori degli elementi.
• DevTools → Issues panel — Chrome 109+ mostra in diretta gli issue di axe-core mentre navighi.

Cablarli in CI. Non affidarti a un umano che clicca Lighthouse. Aggiungi axe-core alla 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([]);
});

Per build React/Next/Astro, aggiungi anche eslint-plugin-jsx-a11y per intercettare i più ovvi a tempo di lint.

Le 5 correzioni da una riga più frequenti:

Errore	Soluzione
color-contrast	Alza il primo piano o lo sfondo finché il rapporto supera 4,5:1 (3:1 per testo da 18pt+). Usa il color picker dei DevTools — mostra il rapporto in tempo reale.
image-alt	Aggiungi alt="...". Per immagini puramente decorative usa alt="" (vuoto, non assente). Vedi alt-text delle immagini.
button-name	I <button> con sola icona vogliono aria-label="Chiudi menu". Le SVG dentro devono avere aria-hidden="true".
link-name	Come i pulsanti. Avvolgi i link icona con testo descrittivo o aria-label. Vedi testo descrittivo dei link.
label	Avvolgi <input> in <label>, oppure usa <label for="id"> + id="id". Vedi etichette campi form.

Se il punteggio è n/a invece di un conteggio, vedi accessibilità Lighthouse non disponibile — l’audit non è partito.

Domande frequenti

Sistemare ogni fallimento mi porta a 100?

Di solito atterri tra i 90 alti. Il punteggio di accessibilità di Lighthouse è pesato ma non lineare — color-contrast pesa molto, altri pesano poco. I punti restanti spesso arrivano da controlli manuali (focus order, narrazione screen-reader) che l’audit automatico elenca come “Additional items to manually check”.

Posso silenziare gli audit con cui non sono d’accordo?

Sì, tramite l’array skipAudits della config di Lighthouse, ma pensaci bene. Il falso positivo classico è color-contrast su testo sopra immagini hero — sistema il contrasto (aggiungi un overlay o uno sfondo pieno) invece di silenziare l’audit.

In cosa differisce da axe-core nei DevTools?

In realtà non differisce. Lighthouse impacchetta axe-core ed esegue un sottoinsieme delle sue regole. L’estensione axe per DevTools esegue il set completo, quindi potresti vedere più issue lì — gli extra sono di solito taggati best-practice e non sono richiesti da WCAG.