18 novembre 2026
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à.
Quando un componente viene usato male, il problema spesso emerge tardi: in QA, nei test o (peggio) in produzione. Con un piccolo pattern CSS puoi trasformare le regole di stile in un sistema di “guardrail” per chi integra i componenti: outline evidenti e messaggi d’errore leggibili direttamente in DevTools (e anche in pagina in ambiente di sviluppo).
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:
- Evidenza visiva (es.
outlinerosso) sul componente “non valido”. - Messaggio testuale tramite pseudo-elemento (
::beforeo::after) concontent:.
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;
}
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;
}
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;
}
Nota: applicare pseudo-elementi su
imgfunziona 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;
}
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;
}
È 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.