Button

Componente per pulsanti con supporto per diverse varianti, dimensioni e icone.

Comportamento

Il componente può essere renderizzato come:

• <button> — elemento di default; garantisce ruolo button e attivabilità da tastiera nativa senza ARIA aggiuntivo
• <a> — quando viene specificato href nel contesto Fractal/Nunjucks; usato per navigare a un URL con aspetto visivo di pulsante
• <span> — quando viene specificato span: true nel contesto Fractal/Nunjucks; usato come contenuto non cliccabile all’interno di componenti complessi (es. card, list-item)

Varianti

Varianti di Stile

• primary: Pulsante primario (default)
• secondary: Pulsante secondario
• outlined: Pulsante con bordo
• outlined-bg-white: Pulsante con bordo e sfondo bianco fisso — da usare quando il pulsante outlined è posizionato su un contenitore non bianco (es. pattern già in uso nei servizi come card-smart--scadenza, o su sfondo scuro come in back-to-top-button)
• inverted: Pulsante con stile invertito
• text-inverted: Pulsante di testo con stile invertito
• only-text: Pulsante di solo testo
• icon: Pulsante circolare con solo icona
• icon-right: Pulsante con icona a destra
• icon-left: Pulsante con icona a sinistra

Varianti di Dimensione

• size-s: Dimensione piccola
• size-l: Dimensione grande

Varianti di Stato

• spinner: Pulsante con indicatore di caricamento
• disabled: Pulsante disabilitato con attributo HTML nativo disabled
• disabled-aria: Pulsante disabilitato con aria-disabled="true" (interazione preservata)

Parametri di configurazione

Contesto di sviluppo Fractal/Nunjucks — Questa sezione riguarda esclusivamente i parametri del context .config.yml usati durante lo sviluppo nella libreria. Non descrive attributi HTML o proprietà da usare nei temi, CMS o ambienti di implementazione: per quello, fare riferimento alla sezione Esempi di utilizzo.

Parametri Base

• label (stringa, obbligatorio): Testo del pulsante
• classes (stringa, opzionale): Classi CSS aggiuntive
• buttonType (stringa, opzionale): Tipo del pulsante (button, submit, reset). Default: “button”
• href (stringa, opzionale): URL per renderizzare come link
• span (booleano, opzionale): Renderizza come span invece che button/link
• disabled (booleano, opzionale): Aggiunge l’attributo HTML disabled; lo stile viene applicato automaticamente via CSS
• ariaDisabled (booleano, opzionale): Aggiunge aria-disabled="true"; stile visivo identico a disabled, ma l’interazione non è bloccata dal browser

Parametri per Icone

• icon (stringa, opzionale): ID dell’icona da utilizzare
• iconSize (stringa, opzionale): Classi CSS per la dimensione dell’icona
• iconTransformType (stringa, opzionale): Tipo di animazione dell’icona al passaggio del mouse. Valori supportati: 'scale' (ingrandimento 125%), 'translate' (traslazione orizzontale)

Parametri di Accessibilità

• labelHidden (booleano, opzionale): Nasconde il testo visibile ma mantiene l’accessibilità
• srOnlyLabel (stringa, opzionale): Testo aggiuntivo visibile solo agli screen reader
• ariaExpanded (booleano, opzionale): Stato di espansione per ARIA
• ariaControls (stringa, opzionale): ID dell’elemento controllato per ARIA
• ariaLabel (stringa, opzionale): Etichetta ARIA per il pulsante
• id (stringa, opzionale): ID del pulsante
• callback (stringa, opzionale): Funzione JavaScript da eseguire al click

Accessibilità

WCAG 2.1

Livello AA — criteri pertinenti:

• 1.4.3 Contrasto minimo — testo su sfondo per tutte le varianti
• 2.1.1 Tastiera — il <button> è attivabile da tastiera nativamente
• 2.4.6 Intestazioni ed etichette — ogni pulsante ha un nome accessibile
• 4.1.2 Nome, Ruolo, Valore — role implicito button; stato e controlli comunicati tramite ARIA

Struttura e semantica

• <button> — ruolo implicito button; attivabile con Enter e Space; usare per azioni che non navigano a un URL
• <a> — ruolo implicito link; attivabile con Enter; usare quando il componente deve navigare verso un URL
• <span> — nessun ruolo interattivo; non focusabile; usare esclusivamente come contenuto non cliccabile all’interno di componenti complessi (es. card, list-item) dove l’interattività è gestita dal contenitore padre

Attributi ARIA

Navigazione da tastiera

Gestione del focus

• Focus visibile: lo stile :focus-visible è sempre visibile e non viene rimosso via CSS

Screen reader

• Nei pulsanti solo icona, il testo è racchiuso in <span class="rtds-sr-only">; l’icona ha aria-hidden="true" — lo screen reader legge solo il testo nascosto come nome del pulsante, ignorando l’icona
• Il <span class="rtds-sr-only"> opzionale dopo il testo visibile arricchisce il nome accessibile annunciato (es. “Elimina questo elemento dalla lista”)
• aria-expanded comunica lo stato aperto/chiuso del pannello o menu controllato; aria-controls collega il pulsante all’elemento controllato — entrambi annunciati dallo screen reader insieme al nome del pulsante

Stili CSS

Classi Base

• .rtds-btn: Stile base del pulsante
• .rtds-btn--primary: Stile primario
• .rtds-btn--secondary: Stile secondario
• .rtds-btn--outlined: Stile con bordo
• .rtds-btn--inverted: Stile invertito
• .rtds-btn--text-inverted: Stile di testo invertito
• .rtds-btn--only-text: Stile di solo testo

Classi Modificatori

• .rtds-btn--icon: Stile per pulsante circolare con icona
• .rtds-btn--icon-right: Stile per icona a destra
• .rtds-btn--icon-left: Stile per icona a sinistra
• .rtds-btn--s: Dimensione piccola
• .rtds-btn--l: Dimensione grande

Stato Disabled

Lo stato disabilitato è gestito tramite selettori attributo, senza classi aggiuntive:

• .rtds-btn[disabled]: stile disabilitato + blocco interazione (pointer-events: none)
• .rtds-btn[aria-disabled="true"]: stile disabilitato visivo; il click e la navigazione da tastiera rimangono attivi

Stato Disabled — Indicazioni d’uso

disabled (attributo HTML nativo)

L’attributo disabled impedisce all’utente di effettuare azioni non valide o non disponibili in un dato momento: l’elemento viene rimosso dal tab order, l’attivazione da tastiera e mouse è bloccata, e viene annunciato dagli screen reader come “non disponibile”. Utile ad esempio per bloccare l’invio di un form finché i campi obbligatori non sono compilati, o per disattivare un’azione che richiede una condizione non ancora soddisfatta.

Non è sempre la soluzione migliore: un pulsante rimosso dal tab order è invisibile alla navigazione da tastiera, e senza un messaggio esplicativo l’utente non capisce perché l’azione non è disponibile né cosa fare per sbloccarla. Valutare sempre se non sia preferibile un’alternativa (vedi avvertenza generale).

<button class="rtds-btn rtds-btn--primary" disabled>
  Invia
</button>

aria-disabled="true"

Comunica lo stato disabilitato agli screen reader, ma non blocca la navigazione da tastiera né il click — lo sviluppatore deve gestire il blocco dell’interazione via JavaScript. Usare quando il pulsante deve restare raggiungibile, ad esempio per mostrare un tooltip che spiega perché l’azione non è disponibile.

<button class="rtds-btn rtds-btn--primary" aria-disabled="true">
  Invia
</button>

Nota implementativa: Con aria-disabled="true", il click handler rimane attivo. Aggiungere un handler che ignora l’evento o mostra un messaggio contestuale.

Avvertenza generale

Evitare i pulsanti disabilitati dove possibile. Un pulsante disabilitato senza spiegazione crea frustrazione: l’utente non sa perché non può agire né cosa fare per sbloccare l’azione. Prima di usare lo stato disabled, discutere con il team di sviluppo le alternative:

• Mostrare un messaggio contestuale che spiega la condizione bloccante
• Rendere il pulsante attivo ma mostrare un feedback al click (es. “Compila prima tutti i campi obbligatori”)
• Usare uno stato di loading invece di disabled durante operazioni asincrone

Se il disabled è inevitabile, fornire sempre un testo o un tooltip adiacente che spieghi il motivo.

Esempi di utilizzo

<!-- Pulsante primario -->
<button class="rtds-btn rtds-btn--primary">
  Salva
</button>

<!-- Pulsante secondario -->
<button class="rtds-btn rtds-btn--secondary">
  Annulla
</button>

<!-- Pulsante con icona a destra -->
<button class="rtds-btn rtds-btn--primary rtds-btn--icon-right">
  Continua
  <svg class="rtds-icon">...</svg>
</button>

<!-- Pulsante circolare con icona (accessibile) -->
<button class="rtds-btn rtds-btn--primary rtds-btn--icon">
  <span class="rtds-sr-only">Chiudi</span>
  <svg class="rtds-icon">...</svg>
</button>

<!-- Pulsante per menu dropdown -->
<button class="rtds-btn rtds-btn--primary"
        aria-expanded="false"
        aria-controls="dropdown-menu">
  Menu
  <svg class="rtds-icon">...</svg>
</button>