Assegna a ogni simbolo ripetuto un proprio SVG esterno con un nome accessibile, riutilizzando soltanto il disegno al suo interno. Questa guida mostra come creare un piccolo elenco di elementi grafici con etichette su Mac e mantenere separati il layout della pagina, le coordinate SVG e l’assegnazione dei nomi accessibili.

Per un elemento grafico semplice, MDN consiglia di inserire role="img" e un’etichetta nell’SVG esterno, così che le tecnologie assistive possano trattarlo come un’unica immagine. Il modello pratico qui consiste nell’usare un wrapper per ogni occorrenza, ciascuno collegato alla propria etichetta. Ruolo ARIA: img

Dove va inserita l’etichetta accessibile di ogni istanza?

Assegna il nome all’elemento che rappresenta quella specifica occorrenza. Quando più elementi grafici separati riutilizzano lo stesso simbolo, assegna a ogni svg esterno un riferimento aria-labelledby o un aria-label proprio. Mantieni il simbolo condiviso concentrato sulla geometria riutilizzabile.

Questo segue la distinzione tra una definizione e le sue istanze renderizzate. L’elemento SVG use fa riferimento a elementi grafici e renderizza i contenuti riutilizzati tramite un albero shadow; queste forme generate non sono normali nodi figli nel DOM della pagina. Riutilizzare un disegno, quindi, non crea copie modificabili separatamente della sua etichetta interna nell’HTML. Struttura del documento — SVG 2

Un titolo memorizzato nel simbolo condiviso non può neppure fornire testi diversi per le varie occorrenze senza un altro meccanismo di assegnazione del nome. Per esempio, lo stesso disegno neutro di una tessera potrebbe rappresentare Sample Alpha in un punto e Sample Beta in un altro. Questi nomi appartengono alle due occorrenze, anche se la loro geometria è identica.

Scegli il metodo di assegnazione del nome in base alla posizione del testo utile già presente:

Situazione Modello consigliato
Una didascalia visibile e concisa identifica l’elemento grafico Fai riferimento al suo ID univoco con aria-labelledby sull’SVG esterno.
L’elemento grafico ha bisogno di un nome ma non ha una didascalia visibile Inserisci un title univoco in ogni SVG esterno e fai riferimento a esso con aria-labelledby, oppure usa aria-label.
L’elemento grafico è solo decorativo e il testo comunica già tutto Nascondi l’SVG alle tecnologie assistive anziché aggiungere un nome ridondante.
Più occorrenze devono restare individuabili singolarmente Evita di raggrupparle tutte in un unico elemento immagine esterno role="img".

MDN consiglia di fare riferimento al testo visibile quando può identificare l’SVG. La documentazione sul ruolo immagine spiega inoltre che role="img" presenta i contenuti come un’unica entità, ecco perché il confine del wrapper è importante. L’elemento SVG per il nome accessibile, Ruolo ARIA: img

Crea una pagina completa con due istanze dotate di nomi indipendenti

L’esempio seguente è un documento HTML completo che contiene solo testo di esempio e un semplice disegno formato da un cerchio e un quadrato. Non richiede JavaScript, sprite esterni, librerie o processi di compilazione. Sul Mac, salvalo da un editor di codice in testo semplice come symbol-labels.html, quindi apri il file in un browser desktop.

Entrambe le occorrenze fanno riferimento a tile-mark, ma i rispettivi SVG esterni fanno riferimento a didascalie visibili diverse. Questo usa il modello di assegnazione del nome tramite testo visibile documentato da MDN. L’attributo href è l’attuale meccanismo di riferimento SVG; MDN documenta xlink:href come deprecato. L’elemento SVG per il nome accessibile, Elemento SVG use

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Independently labeled SVG instances</title>
  <style>
    body {
      margin: 2rem;
      font-family: system-ui, sans-serif;
      color: #222;
    }
    .sprite {
      position: absolute;
      width: 0;
      height: 0;
      overflow: hidden;
    }
    .samples {
      display: grid;
      grid-template-columns: repeat(2, minmax(0, 1fr));
      gap: 1rem;
      max-width: 36rem;
      padding: 0;
      list-style: none;
    }
    .sample {
      padding: 1rem;
      border: 1px solid #777;
    }
    .sample svg {
      display: block;
      width: 5rem;
      height: 5rem;
      margin-bottom: 0.75rem;
    }
    @media (max-width: 30rem) {
      .samples { grid-template-columns: 1fr; }
    }
  </style>
</head>
<body>
  <svg class="sprite" xmlns="http://www.w3.org/2000/svg"
       aria-hidden="true">
    <defs>
      <symbol id="tile-mark" viewBox="0 0 48 48">
        <rect x="4" y="4" width="40" height="40" rx="6"
              fill="none" stroke="currentColor" stroke-width="2" />
        <circle cx="24" cy="24" r="9" fill="currentColor" />
      </symbol>
    </defs>
  </svg>

  <h1>Sample tiles</h1>
  <ul class="samples">
    <li class="sample">
      <svg xmlns="http://www.w3.org/2000/svg"
           viewBox="0 0 48 48" role="img"
           aria-labelledby="sample-alpha-label">
        <use href="#tile-mark" width="48" height="48"
             aria-hidden="true" />
      </svg>
      <span id="sample-alpha-label">Sample Alpha</span>
    </li>
    <li class="sample">
      <svg xmlns="http://www.w3.org/2000/svg"
           viewBox="0 0 48 48" role="img"
           aria-labelledby="sample-beta-label">
        <use href="#tile-mark" width="48" height="48"
             aria-hidden="true" />
      </svg>
      <span id="sample-beta-label">Sample Beta</span>
    </li>
  </ul>
</body>
</html>

I nomi accessibili previsti sono Sample Alpha e Sample Beta. Sono risultati attesi dal markup, non risultati di test del browser riportati. Il disegno all’interno di ogni wrapper è esplicitamente nascosto alle tecnologie assistive; l’SVG esterno con nome rimane esposto. Le mappature di accessibilità SVG distinguono i discendenti nascosti dal genitore esposto. Mappature API di accessibilità SVG

Quando aggiungi una terza occorrenza, riutilizza href="#tile-mark", crea un nuovo ID per la didascalia e aggiorna aria-labelledby di quell’occorrenza in modo che corrisponda. Mantieni condiviso il riferimento al simbolo e specifico per l’occorrenza il riferimento all’etichetta.

Le didascalie visibili possono essere incontrate separatamente anche durante la lettura con uno screen reader. Se la tessera non aggiunge informazioni oltre alla didascalia, usa invece il modello decorativo: rimuovi role="img" e aria-labelledby dall’SVG esterno, quindi assegnagli aria-hidden="true". Mantieni la didascalia visibile. Le mappature SVG documentano l’esclusione tramite aria-hidden. Mappature API di accessibilità SVG

Quale meccanismo del browser controlla ciascuna parte del layout?

In questo esempio ci sono tre compiti distinti: disporre le schede, disegnare il simbolo e calcolare i nomi accessibili. Modificarne uno non esegue automaticamente gli altri.

CSS Grid dispone gli elementi dell’elenco HTML. Dichiarare display: grid trasforma i figli diretti del contenitore in elementi della griglia; grid-template-columns definisce le colonne. Qui, la media query trasforma l’elenco da due colonne a una. Questo influisce sul layout delle schede nella pagina. Concetti di base del layout a griglia

Le coordinate SVG controllano le forme all’interno di ogni elemento grafico. viewBox="0 0 48 48" del simbolo stabilisce il suo rettangolo delle coordinate e le dimensioni dell’elemento use determinano le dimensioni della viewport del simbolo referenziato. Queste dimensioni non creano colonne per le schede HTML né spaziature per le didascalie. SVG 2 distingue esplicitamente il layout degli elementi grafici riutilizzati dal layout delle caselle CSS. Struttura del documento — SVG 2

L’assegnazione del nome accessibile collega ogni SVG esterno a un testo tramite aria-labelledby. Non disegna il testo, non posiziona una didascalia e non ridimensiona un elemento grafico. Le indicazioni del W3C sull’assegnazione dei nomi descrivono questo attributo come un riferimento a contenuti usati per calcolare il nome accessibile. Fornire nomi e descrizioni accessibili

Questa separazione offre una regola diagnostica utile: controlla Grid quando le schede sono fuori posto, le coordinate SVG quando i disegni sono fuori posto e i riferimenti di assegnazione dei nomi quando le etichette sono errate. Aggiungere x o y a use sposta gli elementi grafici riutilizzati nello spazio SVG; non sposta la didascalia HTML. Inoltre, le dimensioni use non sono un sostituto universale per ridimensionare forme referenziate arbitrarie: MDN documenta il loro effetto quando si fa riferimento a un SVG o a un simbolo con viewBox. Elemento SVG use

Cosa fare se non c’è una didascalia visibile?

Usa un titolo per ogni istanza quando l’elemento grafico ha bisogno di un nome ma il design non contiene testo visibile adatto. Il frammento seguente sostituisce il primo SVG visibile nell’esempio completo. Dipende comunque dal simbolo tile-mark già esistente:

<svg xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 48 48" role="img"
     aria-labelledby="sample-alpha-title">
  <title id="sample-alpha-title">Sample Alpha</title>
  <use href="#tile-mark" width="48" height="48"
       aria-hidden="true" />
</svg>

Per ogni occorrenza aggiuntiva, assegna al titolo un ID diverso e aggiorna il riferimento del relativo genitore. MDN documenta title come elemento SVG per l’assegnazione di un nome accessibile e consiglia di posizionarlo per primo per garantire la compatibilità con SVG 1.1. Il testo del titolo non viene visualizzato come parte del disegno, anche se di solito i browser lo mostrano come suggerimento. L’elemento SVG per il nome accessibile

Per un nome breve senza un elemento title, sostituisci aria-labelledby con aria-label="Sample Alpha" sull’SVG esterno di quell’occorrenza. Evita di lasciare attributi di assegnazione del nome in conflitto: il W3C documenta che aria-labelledby ha precedenza su aria-label. Un riferimento residuo può quindi impedire alla nuova stringa di diventare il nome. Fornire nomi e descrizioni accessibili

Non provare ad assegnare un titolo specifico per un’occorrenza modificando un clone generato. SVG 2 specifica un albero shadow d’istanza di sola lettura. Anche la bozza di lavoro attuale delle Mappature API di accessibilità SVG limita la corrispondenza dei riferimenti ID ARIA negli alberi shadow use. Sono limiti documentati; non dimostrano che tutti i browser si comportino allo stesso modo. Mantenere l’etichetta sul wrapper scritto nel markup evita di dipendere dalla ricerca nel clone. Struttura del documento — SVG 2, Mappature API di accessibilità SVG

Come controllare e correggere il risultato?

Controlla separatamente il risultato visibile e i nomi accessibili nel browser del tuo Mac. Esamina ogni SVG esterno negli strumenti di accessibilità del browser, poi controllalo con VoiceOver. Il W3C raccomanda specificamente di testare con tecnologie assistive i nomi calcolati tramite aria-labelledby. Fornire nomi e descrizioni accessibili

Usa i seguenti risultati attesi come breve elenco di criteri di accettazione:

  1. Entrambi i disegni sono visibili, con le rispettive didascalie.
  2. Ogni SVG esterno ha un ruolo immagine e il nome corrispondente.
  3. La definizione del simbolo non appare come un elemento grafico significativo aggiuntivo.
  4. Riducendo la larghezza della finestra cambia la disposizione delle schede, mentre ogni elemento grafico mantiene la propria etichetta.
  5. Modificando solo la seconda didascalia cambia solo il nome calcolato del secondo elemento grafico.

Se entrambi gli elementi grafici ricevono lo stesso nome, confronta prima i rispettivi valori aria-labelledby. Poi verifica che ogni ID referenziato identifichi il testo previsto. Non dare per scontato che la vicinanza visiva stabilisca la relazione: l’attributo fa esplicito riferimento a un elemento tramite ID. Fornire nomi e descrizioni accessibili

Se l’intero disegno viene annunciato come un’unica immagine quando ti servono più immagini indipendenti, controlla dove si trova role="img". Un singolo ruolo immagine intorno all’intera raccolta chiede alle tecnologie assistive di trattarla come un’unica entità. Mantieni wrapper immagine separati per gli elementi grafici semplici distinti. Ruolo ARIA: img

Se stai effettivamente incorporando un file SVG tramite l’elemento HTML img, usa l’attributo alt di quell’elemento per ogni occorrenza. WHATWG definisce alt come contenuto equivalente di fallback per l’immagine. L’SVG inline usa meccanismi di assegnazione dei nomi diversi e non supporta alt come attributo del testo alternativo. Standard HTML: l’elemento img, Introduzione a SVG in HTML

Per questo compito di layout, mantieni una sola definizione del disegno condivisa e una decisione di assegnazione del nome per ogni occorrenza. Scegli il wrapper in base a ciò che il lettore deve incontrare, collegalo al testo appropriato e verifica il nome accessibile risultante indipendentemente dal layout visivo.

Fonti