DEV Community

frontendfacile.it
frontendfacile.it

Posted on Originally published at frontendfacile.it

Messaggi d’errore direttamente in CSS: rendi i componenti “anti-misuso”

Con pseudo-elementi e selettori intelligenti puoi segnalare subito markup incompleto, violazioni di layout e problemi di accessibilità.

Nel lavoro quotidiano capita spesso di scrivere CSS pulito e robusto… e poi vedere i componenti usati in modo improprio. Il problema non è (solo) “chi sbaglia”: è che l’errore è facile da fare e difficile da notare, soprattutto in codebase grandi o con molti contributor.

Un pattern sorprendentemente efficace è aggiungere messaggi d’errore direttamente in CSS: quando un componente non rispetta i requisiti minimi di markup o di accessibilità, lo evidenzi con un’outline e un testo esplicito. Il vantaggio è immediato: chi integra il componente vede subito cosa manca, senza dover interpretare layout “strani” o andare a caccia di documentazione.

Nota di contesto: questo approccio è pensato principalmente per ambienti di sviluppo e per team/design system; non è un sostituto di linting, test o audit di accessibilità, ma un acceleratore che sposta l’errore “più a sinistra” nel flusso di lavoro.


Il pattern: evidenziare l’errore + spiegare il motivo

L’idea è composta da due parti:

  1. Evidenza visiva (es. outline rosso) sul componente “non valido”.
  2. Messaggio testuale tramite pseudo-elemento (::before o ::after) con content:.

Esempio di base (da adattare al tuo componente):

.card:is(.card--featured, .card--default) {
  /* stile normale */
}

/* Stato “errore” in sviluppo */
.card[data-dev-error] {
  outline: 3px solid #e11d48; /* rosa/rosso ben visibile */
  outline-offset: 4px;
  position: relative;
}

.card[data-dev-error]::before {
  content: attr(data-dev-error);
  position: absolute;
  top: -0.75rem;
  left: 0;
  transform: translateY(-100%);

  background: #e11d48;
  color: white;
  font: 600 12px/1.2 system-ui;
  padding: 0.35rem 0.5rem;
  border-radius: 6px;
  white-space: nowrap;
  z-index: 9999;
}
Enter fullscreen mode Exit fullscreen mode

Qui la “regola d’errore” si attiva quando l’elemento ha data-dev-error. Nella pratica, però, vuoi che sia il CSS stesso a dedurre l’errore in base alla struttura interna.


Caso pratico: una card deve avere un heading

Mettiamo che una .card debba contenere almeno un titolo (ad esempio h2, h3 o h4). Se manca, segnaliamo l’errore.

Con i selettori moderni puoi farlo in modo molto pulito usando :has():

/* Se una .card NON ha al suo interno h2/h3/h4 => errore */
.card:not(:has(h2, h3, h4)) {
  outline: 3px solid #e11d48;
  outline-offset: 4px;
  position: relative;
}

.card:not(:has(h2, h3, h4))::before {
  content: "Errore: questa card richiede un heading (h2/h3/h4).";
  position: absolute;
  top: 0;
  left: 0;
  transform: translateY(-110%);
  background: #e11d48;
  color: #fff;
  padding: 0.35rem 0.5rem;
  border-radius: 6px;
  font: 600 12px/1.2 system-ui;
  z-index: 9999;
}
Enter fullscreen mode Exit fullscreen mode

Risultato:

  • a colpo d’occhio vedi quali card sono “rotte”;
  • aprendo DevTools, il selettore e il messaggio rendono immediata la diagnosi.

Compatibilità di :has()

:has() oggi è supportato dalla maggior parte dei browser moderni, ma non in tutti gli ambienti legacy. In un design system, puoi:

  • usarlo solo in dev (o in ambienti interni);
  • oppure proteggere le regole dentro una feature query (dove sensato) e mantenere fallback.

Guardrail per accessibilità: errori che vuoi scoprire subito

Questo pattern brilla quando lo usi per standard di accessibilità del tuo team. Alcuni esempi tipici:

1) Immagini senza alt

Se nel tuo codice ci sono immagini decorative e informative, l’assenza di alt è un errore frequente. Puoi evidenziare immagini senza attributo (o con alt="" quando non dovrebbe esserlo, a seconda delle regole interne).

img:not([alt]) {
  outline: 3px solid #e11d48;
  outline-offset: 3px;
}

img:not([alt])::after {
  content: "Errore a11y: immagine senza alt.";
  display: inline-block;
  margin-left: 0.5rem;
  background: #e11d48;
  color: white;
  padding: 0.2rem 0.4rem;
  border-radius: 4px;
  font: 600 12px/1.2 system-ui;
}
Enter fullscreen mode Exit fullscreen mode

Nota: applicare pseudo-elementi su img funziona in molti casi ma può dipendere dal contesto e dal layout. In alternativa, evidenzia un wrapper o usa un outline senza testo.

2) Dialog senza label/relazioni ARIA richieste

Se il tuo standard prevede che un dialog debba avere aria-labelledby (o un titolo interno ben definito), puoi controllare e segnalare:

dialog:not([aria-labelledby]) {
  outline: 3px solid #e11d48;
  outline-offset: 4px;
  position: relative;
}

dialog:not([aria-labelledby])::before {
  content: "Errore a11y: dialog senza aria-labelledby.";
  position: absolute;
  top: 0;
  left: 0;
  transform: translateY(-110%);
  background: #e11d48;
  color: #fff;
  padding: 0.35rem 0.5rem;
  border-radius: 6px;
  font: 600 12px/1.2 system-ui;
}
Enter fullscreen mode Exit fullscreen mode

Questo tipo di feedback “in tempo reale” riduce i casi in cui l’errore arriva solo in fase di audit o test a valle.


Non solo “manca qualcosa”: validare setup specifici di layout

Gli errori non sono sempre omissioni. A volte un componente o un layout richiede una struttura precisa.

Esempio: hai un contenitore principale pensato per avere header + main + footer (o comunque un numero massimo di figli). Se qualcuno inserisce un quarto blocco e rompe la griglia, puoi segnalarlo.

Con :has() puoi ragionare anche sul numero di figli (approccio indicativo):

/* Se il layout ha 4 o più figli diretti, evidenzia */
.page-layout:has(> :nth-child(4)) {
  outline: 3px solid #e11d48;
  outline-offset: 4px;
  position: relative;
}

.page-layout:has(> :nth-child(4))::before {
  content: "Errore: .page-layout supporta max 3 figli (header/main/footer).";
  position: absolute;
  top: 0;
  left: 0;
  transform: translateY(-110%);
  background: #e11d48;
  color: #fff;
  padding: 0.35rem 0.5rem;
  border-radius: 6px;
  font: 600 12px/1.2 system-ui;
}
Enter fullscreen mode Exit fullscreen mode

È un guardrail pragmatico: non sostituisce regole architetturali o test, ma evita che l’errore passi inosservato mentre si lavora.


Buone pratiche per usarlo bene (senza impazzire)

  • Limitare ai soli ambienti di sviluppo: queste regole possono essere verbose e “rumorose”. Se hai pipeline, valuta di includerle solo in build dev/staging.
  • Messaggi brevi, prescrittivi: indica cosa manca e come correggere (es. “Aggiungi un h2/h3/h4”).
  • Selettori mirati: evita regole troppo generiche che potrebbero colpire markup legittimo.
  • Non affidarti solo al CSS: linting (HTML/JSX), test e controlli di accessibilità restano fondamentali. Il CSS qui è un feedback immediato, non una certificazione.
  • Preferisci l’outline al border: l’outline non altera il layout e comunica chiaramente “attenzione”.

Sintesi: CSS come rete di sicurezza per componenti condivisi

Aggiungere messaggi d’errore in CSS è un modo semplice e potente per rendere i componenti più resilienti in team: evidenzi subito l’uso scorretto, spieghi il motivo direttamente sul pezzo di UI interessato e riduci il tempo perso a diagnosticare problemi “silenziosi”.

Se lavori su un design system o su una codebase con molti contributor, questi guardrail trasformano lo stile da “pennello” a strumento di prevenzione: meno ambiguità, integrazioni più veloci e standard (soprattutto di accessibilità) rispettati fin dall’inizio.


Articolo originale: https://frontendfacile.it/blog/messaggi-d-errore-direttamente-in-css-rendi-i-componenti-anti-misuso

Top comments (0)