Il Regione Toscana Design System distribuisce il CSS già compilato. I siti consumer includono i file della versione che usano e personalizzano il tema tramite un file di override separato, senza modificare il CSS della libreria.
| Modalità | Come funziona | Stato |
|---|---|---|
| CDN versionata | I CSS sono serviti da una CDN RT e inclusi con un <link> a un URL versionato |
Sarà la modalità principale, ancora in fase di definizione |
| CSS compilato incluso in locale | Si copiano i CSS già compilati dal pacchetto di distribuzione e li si riferisce con percorso relativo | Disponibile, e resta valida anche a CDN attiva |
| CSS compilato in proprio | Si compila il CSS nel proprio ambiente a partire dai sorgenti della libreria - vedi Installazione e sviluppo | Disponibile, per chi ha già una propria pipeline di build |
La CDN sarà la modalità principale, non l’unica: le altre due restano supportate. Finché il canale CDN non è attivo, gli snippet di questa pagina si adattano sostituendo l’URL CDN con il percorso locale dei file copiati dal pacchetto (vedi Pacchetti di distribuzione disponibili).
Qualunque sia la modalità, il contratto di tematizzazione non cambia: si sovrascrivono le stesse custom properties, nello stesso ordine di caricamento, con lo stesso file di override in coda.
Il DS distribuisce quattro file CSS separati - custom-properties.css, core.css, servizi.css e font.css - da includere in sequenza. Cosa contiene ciascuno, quali sono i prerequisiti fra loro e perché font.css va incluso a parte è documentato in CSS, che ne è il riferimento.
Qui interessa solo la loro posizione nella catena di caricamento, perché il file di override del tema va sempre per ultimo.
<link rel="stylesheet" href="https://cdn.rt.toscana.it/rtds/1.x/custom-properties.css">
<link rel="stylesheet" href="https://cdn.rt.toscana.it/rtds/1.x/core.css">
<link rel="stylesheet" href="https://cdn.rt.toscana.it/rtds/1.x/font.css">
<link rel="stylesheet" href="/css/ente-theme.css"><link rel="stylesheet" href="https://cdn.rt.toscana.it/rtds/1.x/custom-properties.css">
<link rel="stylesheet" href="https://cdn.rt.toscana.it/rtds/1.x/core.css">
<link rel="stylesheet" href="https://cdn.rt.toscana.it/rtds/1.x/servizi.css">
<link rel="stylesheet" href="https://cdn.rt.toscana.it/rtds/1.x/font.css">
<link rel="stylesheet" href="/css/ente-theme.css">
servizi.cssdipende dacore.css- va sempre caricato dopo.
Il file ente-theme.css (o come lo chiama il sito consumer) contiene gli override delle custom properties ed è sempre l’ultimo della catena.
La fonte unica di verità per tutte le custom properties è:
public/css/custom-properties.cssQuesto file è l’unico posto dove definire custom properties nel DS. Nessun altro file le ridefinisce. tailwind.config.js le consuma via var(--…).
Non modificare questo file per personalizzazioni di enti specifici: usare il file di override lato consumer.
ente-theme.cssSovrascrivere le custom properties in :root con i valori dell’ente:
/* ente-theme.css - personalizzazione per [Nome Ente] */
:root {
/* Colori brand ente */
--color-primary-500: #0057A8;
--color-primary-600: #004A90;
--color-primary-700: #003D78;
/* I colori semantici si aggiornano automaticamente */
/* (--color-button-primary: var(--color-primary-500) ecc.) */
}Non è necessario ridefinire i colori semantici se cambiano solo i colori base: i token semantici già puntano ai token primitivi via var(--color-primary-*).
Le custom properties sono organizzate in livelli:
Valori concreti (hex, rem, font name). Nessuna dipendenza da altre proprietà.
--color-primary-500: #D0131A;
--spacing-base: 0.25rem;
--fontfamily-sans: 'Open Sans';Puntano ai token primitivi. Comunicano l’intenzione d’uso (contenuto, sfondo, bordo…).
--color-content-01: var(--color-neutral-900);
--color-background-01: var(--color-neutral-50);
--color-button-primary: var(--color-primary-500);Alcuni componenti in 08-servizi/ usano un pattern a tre livelli di fallback per le proprietà CSS variabili, così che il CMS ospitante possa fare override del brand senza modificare il DS.
/* Esempio da card-smart.css */
--_card-smart-bg: var(
--card-smart-bg, /* Tier 1: override del CMS ospitante */
var(--color-background-01, /* Tier 2: token semantico RTDS */
var(--color-neutral-50)) /* Tier 3: literal fallback sempre disponibile */
);| Tier | Variabile | Chi la imposta |
|---|---|---|
| 1 | --card-smart-bg |
Il CMS / sito ospitante (brand override) |
| 2 | --color-background-01 |
Il Design System (token semantico) |
| 3 | var(--color-neutral-50) |
Literal hardcoded nel componente |
Grazie al Tier 3, dove il pattern è applicato i componenti funzionano correttamente anche se né custom-properties.css né l’override del CMS sono presenti.
Non è ancora un pattern applicato in modo uniforme. È la convenzione richiesta per ogni nuovo componente 08-servizi/, ma diversi componenti esistenti non la implementano su tutte le proprietà, e i 07-widgets/ attuali (widget-box, widget-nav, widget-search) non la usano.
Copertura attuale in 08-servizi/: pattern applicato (su tutte o parte delle proprietà) in alert, card-smart, popover, progress-indicator, steps, toast, trascinamento-oggetti; assente in file, table-interactive, upload.
Prima di fare affidamento sulle variabili di override di un componente, verificare quali sono effettivamente esposte nella sezione Custom Properties del suo README - non darle per scontate in base a questa pagina.
| Token | Default RT | Descrizione |
|---|---|---|
--color-primary-500 |
#D0131A |
Colore primario - pulsanti, link, accenti |
--color-primary-600 |
#AD1016 |
Primario hover |
--color-primary-700 |
#8B0D11 |
Primario active |
--color-secondary-500 |
#305D9F |
Colore secondario - navigazione, highlights |
--color-secondary-600 |
#284E84 |
Secondario hover |
| Token | Default | Descrizione |
|---|---|---|
--spacing-base |
0.25rem (4px) |
Unità base - tutte le spaziature derivano da questa |
| Token | Default | Descrizione |
|---|---|---|
--fontfamily-sans |
'Open Sans' |
Font principale - caricare il font separatamente se si cambia |
Quando si sovrascrivono i colori, verificare che il contrasto rispetti WCAG 2.1 AA:
Strumento consigliato: Colour Contrast Analyser
| Canale | Contenuto | Uso |
|---|---|---|
| Pacchetto ZIP | Gli stessi CSS + sprite SVG icons.svg + JS (bundle, file singoli, librerie esterne) + font, più la cartella cdn/ - vedi sotto |
Inclusione in locale del CSS compilato, o base per una compilazione propria. È il canale in uso oggi e resta valido anche a CDN attiva |
| CDN RT | custom-properties.css + core.css + servizi.css + font.css + JS di autoria RTDS (componentsJs.js o file singoli per componente) versionati |
Modalità principale a regime - produzione, includi in <link>/<script>. Le librerie esterne (Splide, Tobii, Accessible Autocomplete) non sono distribuite via CDN RT - vedi Risorse JS |
| Sito documentale | UI Fractal con componenti e documentazione | Consultazione pattern e codice |
La cartella cdn/ dentro il pacchetto contiene già, isolato e pronto da caricare, esattamente ciò che la riga «CDN RT» qui sopra elenca: i CSS minificati con i token e font.css, i font Open Sans e il JavaScript di autoria RTDS, senza le librerie terze. Chi pubblica su una propria CDN carica quella cartella; chi integra dal pacchetto in locale la ignora e usa i file della radice. Il contenuto completo dell’archivio è in Download build corrente.
Per la lista delle versioni disponibili e gli URL CDN, fare riferimento al sito documentale RTDS.