Markup HTML riutilizzabile e progressivamente migliorabile

Introduzione

Una buona pratica spesso trascurata consiste nel progettare il markup come un contratto stabile tra contenuto, stili e JavaScript. Un componente HTML ben costruito deve rimanere utile anche quando gli stili non vengono caricati o quando JavaScript non è disponibile. Questo approccio è chiamato progressive enhancement: si parte da una base HTML completa e funzionale, poi si aggiungono miglioramenti visivi e interattivi.

La tecnica è particolarmente utile per schede di articoli, filtri, menu, pannelli informativi e moduli. Il markup deve descrivere il contenuto e il comportamento nativo del browser, senza dipendere da classi CSS usate impropriamente o da elementi generici come <div> e <span>.

Un altro obiettivo importante è definire una separazione chiara tra:

• classi utilizzate per l’aspetto grafico;
• attributi data-* utilizzati come ganci per JavaScript;
• elementi HTML nativi che forniscono già un comportamento utile;
• contenuto testuale comprensibile anche senza script.

Codice completo

<section class="catalogo" data-component="catalogo">
  <h2>Guide disponibili</h2>

  <form class="filtro" data-action="filter-cards" method="get">
    <div class="campo">
      <label for="categoria">Filtra per categoria</label>

      <select id="categoria" name="categoria">
        <option value="">Tutte le categorie</option>
        <option value="html">HTML</option>
        <option value="css">CSS</option>
        <option value="javascript">JavaScript</option>
      </select>
    </div>

    <button type="submit">Applica filtro</button>
  </form>

  <div class="lista-guide" data-role="results">
    <article class="card" data-category="html">
      <h3>Struttura di una pagina HTML</h3>
      <p>Impara a organizzare contenuti e sezioni in modo ordinato.</p>
      <p>
        <a href="/guide/struttura-html">Leggi la guida</a>
      </p>
    </article>

    <article class="card" data-category="css">
      <h3>Layout responsivi con CSS</h3>
      <p>Scopri come creare interfacce adatte a schermi diversi.</p>
      <p>
        <a href="/guide/layout-responsivi">Leggi la guida</a>
      </p>
    </article>

    <article class="card" data-category="javascript">
      <h3>Eventi JavaScript nel browser</h3>
      <p>Gestisci le interazioni dell’utente con gli eventi nativi.</p>
      <p>
        <a href="/guide/eventi-javascript">Leggi la guida</a>
      </p>
    </article>
  </div>

  <p class="messaggio-vuoto" data-role="empty-message" hidden>
    Nessuna guida corrisponde al filtro selezionato.
  </p>
</section>

Spiegazione

L’elemento <section> identifica un’area autonoma della pagina e possiede un titolo visibile. L’attributo data-component="catalogo" comunica a JavaScript che l’area rappresenta un componente specifico. Non descrive l’aspetto grafico e quindi non dovrebbe essere usato come classe CSS.

Il filtro è realizzato con un vero elemento <form>. Se JavaScript non funziona, il browser può comunque inviare il valore scelto al server tramite il metodo GET. Questa è una differenza importante rispetto a un semplice contenitore controllato esclusivamente da uno script.

La relazione tra <label> e <select> è stabilita usando gli attributi for e id. In questo modo l’etichetta è cliccabile e il controllo mantiene un significato chiaro per il browser.

Ogni risultato è un elemento <article> indipendente. Può essere spostato, riutilizzato o visualizzato in un’altra pagina senza perdere il proprio significato. L’attributo data-category contiene un valore utile allo script per filtrare le schede, mentre la classe card può essere usata dagli stili.

Il collegamento verso ogni guida è un elemento <a> reale. Non è necessario trasformare l’intera scheda in un pulsante né aggiungere un gestore JavaScript per aprire una pagina. Il browser dispone già del comportamento corretto per la navigazione.

L’attributo hidden sul messaggio vuoto mantiene il contenuto nel documento, ma lo nasconde finché lo script non deve mostrarlo. È preferibile a inserire messaggi dinamici senza una posizione stabile nel markup.

Best practice

• Progetta prima la versione senza JavaScript. Il form deve poter inviare una richiesta e i link devono poter aprire le destinazioni anche senza codice client.
• Usa elementi nativi per i comportamenti nativi. Preferisci <button>, <a>, <form>, <select> e <details> a elementi generici con eventi personalizzati.
• Separa stile e comportamento. Le classi come card possono descrivere l’aspetto; attributi come data-component e data-role possono descrivere il ruolo tecnico.
• Scegli nomi stabili. Un selettore JavaScript non dovrebbe dipendere da una classe che potrebbe cambiare solo per esigenze grafiche.
• Evita di inserire informazioni strutturali nel testo. Non usare nomi di classi o simboli visivi per comunicare dati importanti all’utente.
• Mantieni il contenuto completo nel markup iniziale. Il caricamento dinamico può migliorare l’esperienza, ma non dovrebbe essere l’unico modo per ottenere informazioni fondamentali.
• Usa valori coerenti negli attributi data-*. Scegli una convenzione, ad esempio valori minuscoli e separati da trattini, e applicala a tutti i componenti.
• Non abusare degli attributi personalizzati. Se un’informazione ha già un attributo HTML standard, utilizza quello invece di crearne uno nuovo.
• Prevedi uno stato vuoto. Liste, ricerche e filtri devono descrivere cosa accade quando non esistono risultati.
• Valida il markup. Errori come id duplicati, elementi annidati in modo scorretto o attributi non validi possono compromettere sia gli script sia il comportamento del browser.

Riepilogo

Il markup riutilizzabile non consiste nel creare molti elementi generici, ma nel definire una struttura comprensibile e indipendente dal comportamento aggiuntivo. Parti sempre da HTML semantico e funzionante, usa i controlli nativi, assegna nomi stabili ai componenti e utilizza gli attributi data-* solo quando servono a collegare il markup al codice.

Con questo approccio, CSS e JavaScript diventano miglioramenti progressivi invece di requisiti indispensabili. Il risultato è un’interfaccia più resistente, più semplice da testare e più facile da mantenere nel tempo.

Approfondisci con risorse ufficiali

• MDN Web Docs: documentazione sugli elementi HTML e sui loro comportamenti nativi, disponibile su developer.mozilla.org/docs/Web/HTML.
• WHATWG HTML Living Standard: specifica ufficiale del linguaggio HTML, disponibile su html.spec.whatwg.org.
• MDN Web Docs: guida sugli attributi personalizzati data-*, disponibile su developer.mozilla.org/docs/Learn/HTML/Howto/Use_data_attributes.
• Web.dev: approfondimenti sul progressive enhancement e sulla progettazione di esperienze web solide, disponibile su web.dev.