Steps

Indicatore di avanzamento per flussi multi-step (wizard, moduli a più pagine). Mostra gli step del percorso con i rispettivi stati (completato, attivo, futuro) senza includere content area né pulsanti di navigazione — entrambi sono responsabilità del consumer. Su mobile mostra solo lo step attivo (gli altri sono nascosti visivamente ma restano accessibili agli screen reader) affiancato da un contatore compatto, calcolato senza JavaScript.

Comportamento

Il componente produce sempre un <nav> con un <ol> di step. L’elemento interno di ogni step varia:

• <a href="..."> — step completato con href fornito sull’oggetto step; consente di tornare a step precedenti senza JavaScript
• <span> — tutti gli altri casi: step completato senza href, step attivo, step futuro

Varianti

• steps (default): indicatore circolare sempre presente per tutti gli stati — cerchio vuoto con bordo per gli step futuri, cerchio con bordo + spunta (check-solid) per i completati, cerchio con bordo spesso (8px) e sfondo bianco senza icona per l’attivo
• numbered: numero progressivo (1, 2, 3…) al posto di icone e cerchi; utile quando la sequenzialità numerica è significativa

Parametri di configurazione

Contesto di sviluppo Fractal/Nunjucks — parametri del context .config.yml usati nella libreria.

Parametri radice

• steps (array, obbligatorio): lista di oggetti step (vedi Oggetto step)
• ariaLabel (stringa, opzionale, default: "Avanzamento procedura"): label del <nav> letta dagli screen reader
• completedLabel (stringa, opzionale, default: "Completato: "): prefisso sr-only per step completati
• currentLabel (stringa, opzionale, default: "Corrente: "): prefisso sr-only per lo step attivo
• classes (stringa, opzionale): classi CSS aggiuntive sul <nav>

Oggetto step

• label (stringa, obbligatorio): testo visibile dello step
• completed (booleano, opzionale, default: false): segna lo step come completato
• active (booleano, opzionale, default: false): segna lo step come corrente — massimo uno per componente
• href (stringa, opzionale): se presente e completed: true, lo step diventa un <a> navigabile
• icon (stringa, opzionale): ID icona SVG sprite per step completati (solo variante base); default check-solid. Ignorato nella variante numerata.

Accessibilità

WCAG 2.1

Livello AA — criteri pertinenti:

• 1.3.1 Informazioni e correlazioni — <nav> landmark + <ol> comunica sequenzialità
• 1.3.3 Caratteristiche sensoriali — stato comunicato via testo, non solo colore
• 2.1.1 Tastiera — step completati con href sono link navigabili da tastiera
• 4.1.2 Nome, Ruolo, Valore — aria-current="step" sullo step attivo

Struttura e semantica

• <nav> — landmark navigation; identificato dall’aria-label configurabile
• <ol> — lista ordinata; comunica agli screen reader che gli step sono in sequenza
• <a> — ruolo implicito link; attivabile con Enter; solo per step completati con href
• <span> — nessun ruolo interattivo; usato per step attivi, futuri e completati senza link
• <span aria-current="step"> / <a aria-current="step"> — annuncia lo step corrente agli screen reader; posizionato sull’elemento interattivo (.rtds-steps__link), non sul <li>

Attributi ARIA

Screen reader

• <span class="rtds-sr-only">Completato: </span> — prefisso sr-only davanti alla label degli step completati; comunicano lo stato senza dipendere dai colori
• <span class="rtds-sr-only">Corrente: </span> — prefisso sr-only per lo step attivo; in combinazione con aria-current="step" sul .rtds-steps__link, lo step viene annunciato chiaramente
• aria-hidden="true" sull’indicatore — icone, cerchi e numeri sono decorativi; lo stato è comunicato dal testo sr-only
• aria-hidden="true" sul contatore mobile — l’informazione è già accessibile tramite la struttura della lista completa

Stili CSS

Classi Base

• .rtds-steps: <nav> wrapper; contiene le variabili triple fallback

Classi Modificatori

• .rtds-steps--numbered: variante numerata; gli indicatori mostrano il numero progressivo con bordo

Classi Elementi (BEM)

• .rtds-steps__list: <ol> — layout flex orizzontale
• .rtds-steps__item: <li> — flex colonna; border-bottom come barra visiva di separazione orizzontale
• .rtds-steps__item--active: step corrente — indicatore cerchio con bordo spesso (var(--spacing-2) = 8px) nel colore active e sfondo bianco (--_steps-indicator-bg), senza icona; label in grassetto; border-bottom nel colore active
• .rtds-steps__item--completed: step completato — border-bottom nel colore completed; indicatore con bordo e sfondo chiaro
• .rtds-steps__link: <a> o <span> — flex row centrato con gap; decorazione underline on hover solo sui link
• .rtds-steps__indicator: contenitore icona/numero/cerchio — sempre presente per tutti gli stati; dimensione fissa --_steps-indicator-size, centrato, forma circolare; cerchio vuoto (solo bordo) per step futuri, con icona o riempito per gli altri stati
• .rtds-steps__label: testo dello step; grassetto e colore active sullo step corrente
• .rtds-steps__counter: contatore X / Y; nascosto su desktop, affiancato allo step attivo su mobile (< 640px)

Tematizzazione

Il componente espone variabili CSS per la personalizzazione dal CMS ospitante. Il CMS può sovrascrivere le variabili Tier 1; se non sovrascritte, usano i token semantici del DS.

Override pubblici (Tier 1)

Token semantici DS (Tier 2)

Esempi di utilizzo

<!-- Variante base (cerchi e icone) -->
<nav class="rtds-steps" aria-label="Avanzamento procedura">
  <ol class="rtds-steps__list">
    <li class="rtds-steps__item rtds-steps__item--completed">
      <a href="/step1" class="rtds-steps__link">
        <span class="rtds-steps__indicator" aria-hidden="true">
          <!-- icona check-solid, 16×16 -->
        </span>
        <span class="rtds-sr-only">Completato: </span>
        <span class="rtds-steps__label">Dati anagrafici</span>
      </a>
    </li>
    <li class="rtds-steps__item rtds-steps__item--active">
      <span class="rtds-steps__link" aria-current="step">
        <span class="rtds-steps__indicator" aria-hidden="true"></span>
        <span class="rtds-sr-only">Corrente: </span>
        <span class="rtds-steps__label">Contatti</span>
      </span>
    </li>
    <li class="rtds-steps__item">
      <span class="rtds-steps__link">
        <span class="rtds-steps__indicator" aria-hidden="true"></span>
        <span class="rtds-steps__label">Riepilogo</span>
      </span>
    </li>
  </ol>
  <span class="rtds-steps__counter" aria-hidden="true">2 / 3</span>
</nav>

<!-- Variante numerata -->
<nav class="rtds-steps rtds-steps--numbered" aria-label="Avanzamento procedura">
  <ol class="rtds-steps__list">
    <li class="rtds-steps__item rtds-steps__item--completed">
      <span class="rtds-steps__link">
        <span class="rtds-steps__indicator" aria-hidden="true">1</span>
        <span class="rtds-sr-only">Completato: </span>
        <span class="rtds-steps__label">Dati anagrafici</span>
      </span>
    </li>
    <li class="rtds-steps__item rtds-steps__item--active">
      <span class="rtds-steps__link" aria-current="step">
        <span class="rtds-steps__indicator" aria-hidden="true">2</span>
        <span class="rtds-sr-only">Corrente: </span>
        <span class="rtds-steps__label">Contatti</span>
      </span>
    </li>
    <li class="rtds-steps__item">
      <span class="rtds-steps__link">
        <span class="rtds-steps__indicator" aria-hidden="true">3</span>
        <span class="rtds-steps__label">Riepilogo</span>
      </span>
    </li>
  </ol>
  <span class="rtds-steps__counter" aria-hidden="true">2 / 3</span>
</nav>

Note

• Il contatore mobile (X / Y) è calcolato interamente in Nunjucks — non richiede JavaScript.
• Su viewport < 640px gli step non attivi sono nascosti visivamente ma restano accessibili agli screen reader. Il <span class="rtds-steps__counter"> è aria-hidden="true" perché la lista completa è già navigabile.
• Il parametro icon per-step è ignorato nella variante numerata.
• Il componente non include content area né pulsanti di navigazione: sono responsabilità del consumer.
• Massimo un active: true per istanza.
• Dipende da: @icon (variante base, per step completati)