Guida integrazione consumer

Come integrare RTDS in un applicativo o portale esterno. Si rivolge ai team che costruiscono servizi digitali per Regione Toscana e caricano RTDS da CDN.

I tre layer CSS

Il Design System si distribuisce in tre file indipendenti da caricare nell’ordine seguente:

<head>
  <!-- 1. Token layer: variabili CSS per colori, spaziatura, tipografia -->
  <link rel="stylesheet" href="https://cdn.example.com/rtds/css/custom-properties.css">

  <!-- 2. Core: componenti siti informativi RT (button, form, header, footer…) -->
  <link rel="stylesheet" href="https://cdn.example.com/rtds/css/core.css">

  <!-- 3. Servizi: componenti applicativi e widget (solo se necessario) -->
  <link rel="stylesheet" href="https://cdn.example.com/rtds/css/servizi.css">

  <!-- 4. Font: opzionale, font di default Open Sans -->
  <link rel="stylesheet" href="https://cdn.example.com/rtds/css/font.css">
</head>

font.css non è importato dentro core.css/servizi.css — va sempre incluso come <link> a parte. Senza, la libreria funziona comunque (nessun errore, nessun layout rotto) ma il testo non usa Open Sans, cade sul fallback di sistema del browser. Dettagli in Font.

Il caricamento da CDN è l’assetto a regime, ancora in fase di definizione con enti e partner. In ambiente di sviluppo, finché il canale CDN non è attivo, sostituire gli URL con i percorsi locali dei file copiati dal pacchetto ZIP — vedi Customizzazione del tema.

Ogni layer ha una responsabilità precisa — vedi Architettura bundle CSS per i dettagli completi.

Quando caricare `servizi.css`

Caricare il terzo layer solo se l’applicativo usa componenti da 08-servizi/ o 07-widgets/ (es. @page-header-base-smart, @steps, @card-smart, template-servizio).

Caricamento JS

Il JS di autoria RTDS è distribuito via CDN in due forme, a scelta del consumer — vedi Risorse JS per il dettaglio completo:

<!-- Opzione 1: bundle completo, tutti i componenti -->
<script src="https://cdn.example.com/rtds/js/componentsJs.js"></script>

<!-- Opzione 2: solo i file dei componenti effettivamente usati -->
<script src="https://cdn.example.com/rtds/js/components/raw/accordion/accordion.js"></script>
<script src="https://cdn.example.com/rtds/js/components/raw/tablist/tablist.js"></script>

Le librerie esterne vendorizzate (Splide per il carousel, Tobii per il lightbox, Accessible Autocomplete) non sono distribuite via CDN RT — restano disponibili solo nel pacchetto ZIP o nel sito documentale. Un componente che dipende da una di queste librerie (es. carousel/slider, lightbox) richiede che il consumer la includa autonomamente (proprio bundler, altro CDN pubblico, o file dello ZIP). Vedi Risorse JS per l’elenco completo.

Contratto di tematizzazione

Diversi componenti servizi espongono variabili CSS pubbliche per consentire al sito ospitante di personalizzare il brand senza modificare i file RTDS. Non è una garanzia estesa a tutti i componenti: verificare sempre la sezione Custom Properties del README del singolo componente prima di fare affidamento su una variabile di override.

Il pattern triple fallback

Dove il pattern è implementato, ogni proprietà CSS variabile usa tre livelli di fallback:

--_componente-prop: var(
  --componente-prop,           /* Tier 1: override del sito ospitante */
  var(--token-semantico-rtds,  /* Tier 2: token del Design System */
  var(--literal-fallback))     /* Tier 3: valore primitivo, sempre disponibile */
);

Tier	Chi lo imposta	Quando si attiva
1	Il sito / CMS ospitante	Quando si definisce la variabile di override
2	Il Design System (`custom-properties.css`)	Quando il Tier 1 non è definito
3	Il componente stesso (hardcoded)	Quando nemmeno `custom-properties.css` è caricato

Il Tier 3 garantisce che i componenti funzionino correttamente anche in ambienti che non caricano custom-properties.css, dove il pattern è applicato.

Il pattern è la convenzione richiesta per ogni nuovo componente 08-servizi/, ma non copre ancora tutti i componenti esistenti né i 07-widgets/ attuali — vedi la copertura completa in Architettura bundle CSS → Pattern triple fallback.

Dove trovare le variabili pubbliche

Le variabili di Tier 1 esposte da ogni componente sono documentate nella sezione Custom Properties del README del componente.

Pattern di override sicuri

Override tramite variabili CSS (raccomandato)

Il modo corretto per personalizzare il brand è ridefinire le variabili di Tier 1 nello scope dell’applicativo:

/* Nel CSS del sito ospitante */
.mio-applicativo {
  --card-smart-bg: #f0f4ff;        /* override sfondo card */
  --card-smart-border: #3b5bdb;    /* override bordo card */
}

Questo approccio:

Non rompe gli aggiornamenti futuri di RTDS
Non aumenta la specificità CSS
È reversibile rimuovendo le variabili

Override tramite classi CSS (da evitare)

Non sovrascrivere direttamente le classi BEM di RTDS (rtds-card-smart, rtds-btn--primary, ecc.):

/* EVITARE — fragile agli aggiornamenti */
.rtds-card-smart {
  background: #f0f4ff !important;
}

Questo crea dipendenze sui nomi interni dei componenti che possono cambiare tra versioni.

Override tramite token semantici

Se il sito ospitante usa il proprio custom-properties.css con gli stessi token semantici RTDS, i componenti si adattano automaticamente:

/* Sovrascrivere i token semantici per tutta la pagina */
:root {
  --color-primary: #1a56db;        /* il brand del servizio ospitante */
  --color-background-01: #f8faff;  /* sfondo pagina */
}

Template servizio come riferimento compositivo

Il template-form-step in 11-templates-servizi/template-form-step/ mostra come comporre i componenti RTDS in una pagina di servizio completa. Non è un componente da importare direttamente — è un riferimento visivo e strutturale da cui partire.

Struttura di una pagina servizio

skip-link                    ← accessibilità
<header>
  top-bar                    ← autenticazione utente, no social, no ricerca
  main-heading--logo-square  ← logo RT + logo/nome del servizio
</header>
page-header-base-smart       ← breadcrumb + titolo + descrizione
<main>
  @steps (numbered)          ← avanzamento flusso multi-step
  <h2> titolo step corrente
  <section> + <h3>           ← sezioni del form
    @input-field / @select-field / @input-textarea
  <div> navigazione step     ← button "Indietro" + button "Avanti"
</main>
<footer>

Nella variante con-sidebar, il <main> include un <aside> con <nav aria-label="Sezioni del servizio"> per la navigazione tra sezioni del servizio (non tra step):

<main>
  <div class="rtds-container">
    <aside>  ← ~1/4 larghezza
      <nav aria-label="Sezioni del servizio">
        <!-- link alle macro-sezioni del servizio -->
      </nav>
    </aside>
    <div>   ← ~3/4 larghezza
      @steps + form step corrente
    </div>
  </div>
</main>

Adattare il template al proprio servizio

Se si consuma RTDS tramite Fractal/Nunjucks, i punti di personalizzazione sono i parametri di contesto:

Header: impostare secondLogoPath, secondLogoAlt, secondaryLogoText con il brand del servizio
Page header: aggiornare pageHeader.title, pageHeader.description, pageHeader.breadcrumb.items
Steps: definire steps.steps con i passi del proprio flusso
Form sections: sostituire le <section> campione con i campi del proprio form
Footer: configurare footer.navInfoItems con i link informativi del servizio

Se invece si consuma RTDS tramite snippet HTML statici (senza Fractal), gli stessi punti si modificano direttamente nel markup esportato, individuando gli elementi tramite le classi RTDS:

Header — sostituire src/srcset/alt dell’<img> dentro .rtds-logo--secondary con il logo del servizio:

<a href="#" class="rtds-site-logo rtds-logo--secondary ...">
  <img src="/images/logo-mio-servizio.png" alt="Nome del servizio" ... />
</a>

Page header — modificare direttamente il testo dentro .rtds-page-header__title (<h1>) e .rtds-page-header__description (<p>); per il breadcrumb, editare le <li> dentro il componente @breadcrumb incluso in cima al blocco .rtds-page-header
Steps: gli step (etichette, stato attivo/completato) sono markup ripetuto per ogni passo — usare come riferimento lo snippet HTML del componente @steps nella relativa scheda e duplicare/adattare le <li> per il proprio flusso
Form sections: sostituire il contenuto delle <section> campione con i campi del proprio form, usando lo snippet HTML dei componenti @input-field / @select-field / @input-textarea dalle rispettive schede

Footer: nella <nav aria-label="Altre informazioni"> del footer, editare le voci della lista:

<ul class="rtds-grid md:rtds-flex rtds-gap-y-3 md:rtds-gap-y-4 rtds-flex-wrap">
  <li class="rtds-group">
    <a href="/link-servizio" class="rtds-link rtds-px-4 rtds-py-2 rtds-text-sm rtds-content-03 rtds-font-bold">Etichetta link</a>
  </li>
</ul>

Compatibilità con CMS ospitante

Il prefisso rtds- su tutte le classi Tailwind riduce al minimo i conflitti con il CSS del sito ospitante.

Se il CMS ha un proprio CSS globale che interferisce, le opzioni supportate sono:

Shadow DOM: per widget completamente isolati (solo 07-widgets/) — richiede build separata
@layer: se il CSS del sito ospitante usa @layer, assicurarsi che i layer RTDS (components) abbiano precedenza corretta

Isolare i componenti RTDS con tecniche di CSS scoping (es. wrapper con classe dedicata + aumento di specificità) è possibile con gli strumenti CSS standard, ma non è un pattern documentato né supportato da RTDS: l’implementazione e la manutenzione restano a carico del team consumer.

Risorse collegate

Architettura bundle CSS — dettagli sui tre layer
Fractal Servizi — come navigare la libreria componenti
components/11-templates-servizi/template-form-step/README.md — parametri del template servizio

Guida integrazione consumer

Guida integrazione consumer

I tre layer CSS

Quando caricare servizi.css

Caricamento JS

Contratto di tematizzazione

Il pattern triple fallback

Dove trovare le variabili pubbliche

Pattern di override sicuri

Override tramite variabili CSS (raccomandato)

Override tramite classi CSS (da evitare)

Override tramite token semantici

Template servizio come riferimento compositivo

Struttura di una pagina servizio

Variante con sidebar

Adattare il template al proprio servizio

Compatibilità con CMS ospitante

Risorse collegate

Quando caricare `servizi.css`