Toast

⚠️ Limitazioni di accessibilità — leggere prima dell’uso

Il pattern toast ha vincoli intrinseci che non possono essere eliminati per design:

• Area ridotta: il toast occupa poco spazio visivo e può essere ignorato da utenti con bassa visione.
• Auto-dismiss: il messaggio può sparire prima che l’utente lo legga o che lo screen reader lo annunci completamente. Preferire tempi di dismiss ≥ 5 secondi e offrire sempre un’alternativa persistente (es. sezione “Notifiche” nella UI).
• Sovrasta il contenuto: il posizionamento fixed può coprire elementi interattivi della pagina, in particolare su schermi piccoli.
• Non sostituisce Alert o Modal: per messaggi critici che richiedono azione, usare il componente Alert (inline) o Modal.

Il componente è conforme WCAG 2.2 AA solo se usato correttamente: live region vuota nel DOM al caricamento, toast iniettato via JS, timing adeguato.

Componente di notifica temporanea sovrapposta al contenuto per comunicare esiti di operazioni. Display-only — nessun JavaScript integrato.

Comportamento

Il singolo toast usa role="status" (polite) per i tipi info/success/warning e role="alert" (assertive) per il tipo error. Il parametro role consente di sovrascrivere il valore.

Il container (role="region") deve essere presente nel DOM al caricamento della pagina — non può essere creato dinamicamente. I singoli toast vengono iniettati nel container via JavaScript dal consumer.

Varianti

• success: Conferma operazione completata
• info: Messaggio informativo
• warning: Avviso che richiede attenzione
• error: Errore — usa role="alert" per annuncio assertivo
• neutro: Toast senza tipo semantico (nessun bordo colorato)
• container: Demo di stacking (3 toast in colonna)

Parametri — Toast singolo

Parametri — Container

Accessibilità

WCAG 2.2 — criteri pertinenti

• 1.4.1 Uso del colore — il bordo colorato è affiancato dall’icona per distinguere il tipo
• 1.4.3 Contrasto minimo — testo su sfondo con contrasto ≥ 4.5:1
• 2.2.1 Tempo regolabile — fornire sempre alternativa persistente; non affidarsi solo al toast
• 4.1.3 Messaggi di stato — role="status" e role="alert" comunicano i messaggi agli AT

Struttura live region

• role="status" (polite): lo screen reader annuncia al termine della lettura corrente. Usare per info, success.
• role="alert" (assertive): lo screen reader interrompe e annuncia immediatamente. Usare solo per error.
• role="region" sul container: nessun aria-live aggiuntivo — causerebbe doppio annuncio.

Attributi ARIA

Stili CSS

Classi — Toast singolo

• .rtds-toast: Stile base — flex, padding, bordo 1px + bordo sinistro spesso, sfondo, ombra
• .rtds-toast--info: Bordo e icona blu (--color-content-info)
• .rtds-toast--success: Bordo e icona verde (--color-content-success)
• .rtds-toast--warning: Bordo e icona arancione (--color-content-warn)
• .rtds-toast--error: Bordo e icona rosso (--color-content-error)
• .rtds-toast__icon: Contenitore icona decorativa
• .rtds-toast__content: Area testo (heading + body)
• .rtds-toast__heading: Titolo in grassetto — elemento <h2> con reset font-size/margin
• .rtds-toast__body: Testo del messaggio
• .rtds-toast__close: Pulsante dismiss — classi: rtds-btn rtds-btn--icon rtds-btn--outlined rtds-border-none rtds-content-01 hover:rtds-bg-black focus:rtds-content-03

Classi — Container

• .rtds-toast-container: Base fixed, flex column, gap, z-index 9000
• .rtds-toast-container--bottom-right / --bottom-left / --top-right / --top-left

Tematizzazione — Custom Properties

Toast singolo (Tier 1 — API pubblica)

Container (Tier 1 — API pubblica)

Esempi di utilizzo

Markup HTML base

<!-- Toast success -->
<div class="rtds-toast rtds-toast--success" role="status" aria-labelledby="toast-1-heading">
  <div class="rtds-toast__icon" aria-hidden="true"><!-- SVG outline--check-circle --></div>
  <div class="rtds-toast__content">
    <h2 id="toast-1-heading" class="rtds-toast__heading">Operazione completata</h2>
    <p class="rtds-toast__body">I dati sono stati salvati.</p>
  </div>
</div>

<!-- Toast error (assertive) -->
<div class="rtds-toast rtds-toast--error" role="alert" aria-labelledby="toast-2-heading">
  <div class="rtds-toast__icon" aria-hidden="true"><!-- SVG outline--x-circle --></div>
  <div class="rtds-toast__content">
    <h2 id="toast-2-heading" class="rtds-toast__heading">Errore</h2>
    <p class="rtds-toast__body">Impossibile salvare. Riprova.</p>
  </div>
</div>

<!-- Container (da includere nel layout base della pagina) -->
<div class="rtds-toast-container rtds-toast-container--bottom-right"
     role="region" aria-label="Notifiche">
</div>

Gestione dismiss via JavaScript

document.querySelectorAll('.rtds-toast__close').forEach(btn => {
  btn.addEventListener('click', () => {
    btn.closest('.rtds-toast').remove();
  });
});

Auto-dismiss via JavaScript

function showToast(container, toastEl, delay = 5000) {
  container.appendChild(toastEl);
  setTimeout(() => toastEl.remove(), delay);
}

// Uso:
const container = document.querySelector('.rtds-toast-container');
const toast = document.createElement('div');
toast.className = 'rtds-toast rtds-toast--success';
toast.setAttribute('role', 'status');
toast.setAttribute('aria-label', 'Operazione completata');
toast.innerHTML = `
  <div class="rtds-toast__content">
    <p class="rtds-toast__body">Salvato con successo.</p>
  </div>
`;
showToast(container, toast, 6000);

Note

• Richiede lo sprite SVG (/icons.svg) caricato in pagina.
• Il container DEVE essere nel DOM al caricamento della pagina — non crearlo dinamicamente: le live region create dopo il caricamento non vengono riconosciute dagli screen reader.
• Per z-index in conflitto con modal/overlay: sovrascrivere --toast-container-zindex su .rtds-toast-container.
• Il dismiss è responsabilità del consumer — nessun JavaScript integrato.