Customizzazione del tema

Il Regione Toscana Design System distribuisce il CSS tramite CDN versionata. I siti consumer (enti, portali RT) includono il CSS della versione stabile e possono personalizzare il tema tramite un file di override separato.

Stato attuale: il modello CDN descritto in questa pagina è l’assetto a regime, ancora in fase di definizione insieme a enti e partner (onboarding, versioning per consumer, dominio CDN). Finché questo percorso non è strutturato, in ambiente di sviluppo si includono i CSS copiandoli localmente dal pacchetto ZIP (vedi Pacchetti di distribuzione disponibili) e riferendoli con percorso relativo al posto dell’URL CDN. È un approccio transitorio, da sostituire con i <link> a CDN non appena il canale sarà attivo per il proprio ente/partner.

Modello di distribuzione

Il DS distribuisce quattro file CSS separati, da includere in sequenza:

File	Contenuto	Obbligatorio
`custom-properties.css`	Token layer — tutte le CSS Custom Properties	Sempre
`core.css`	Tailwind base + utilities + componenti atoms, molecules, organisms, portale	Per siti istituzionali / portali RT
`servizi.css`	Componenti 07-widgets e 08-servizi	Per applicativi servizi (richiede `core.css`)
`font.css`	Regole `@font-face` del font di default (Open Sans)	Se si vuole il font di default del DS — senza, il testo usa il fallback di sistema del browser, senza altre conseguenze

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. Dettagli sui font in Font.

Caso 1 — Sito istituzionale (solo componenti core)

<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">

Caso 2 — Applicativo servizi (componenti servizi)

<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.css dipende da core.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.

File sorgente delle custom properties

La fonte unica di verità per tutte le custom properties è:

public/css/custom-properties.css

Questo 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.

Come personalizzare — file `ente-theme.css`

Sovrascrivere 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-*).

Struttura delle custom properties

Le custom properties sono organizzate in livelli:

Livello 1 — Token primitivi (base)

Valori concreti (hex, rem, font name). Nessuna dipendenza da altre proprietà.

--color-primary-500: #D0131A;
--spacing-base: 0.25rem;
--fontfamily-sans: 'Open Sans';

Livello 2 — Token semantici

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);

Livello 3 — Override componente (triple fallback, parte dei componenti 08-servizi/)

Pattern usato da diversi componenti servizi per permettere override dal CMS ospitante — non è ancora presente su tutti i componenti 08-servizi/ né sui 07-widgets/ esistenti. Vedi copertura reale e dettagli nella sezione Architettura bundle CSS → Pattern triple fallback.

--_card-smart-bg: var(--card-smart-bg, var(--color-background-01, var(--color-neutral-50)));

Token principali sovrascrivibili

Colori brand

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

Spaziatura

Token	Default	Descrizione
`--spacing-base`	`0.25rem` (4px)	Unità base — tutte le spaziature derivano da questa

Tipografia

Token	Default	Descrizione
`--fontfamily-sans`	`'Open Sans'`	Font principale — caricare il font separatamente se si cambia

Accessibilità e contrasto

Quando si sovrascrivono i colori, verificare che il contrasto rispetti WCAG 2.1 AA:

Testo su sfondo: ≥ 4.5:1
Testo grande (≥ 18pt / 14pt bold): ≥ 3:1
Elementi UI e focus: ≥ 3:1

Strumento consigliato: Colour Contrast Analyser

Pacchetti di distribuzione disponibili

Canale	Contenuto	Uso
Pacchetto ZIP	Gli stessi CSS + sprite SVG `icons.svg`	Attuale — ambiente di sviluppo, in attesa della strutturazione CDN per enti/partner
CDN RT	`custom-properties.css` + `core.css` + `servizi.css` + `font.css` versionati	A regime — produzione, includi in `<link>`
Sito documentale	UI Fractal con componenti e documentazione	Consultazione pattern e codice

Per la lista delle versioni disponibili e gli URL CDN, fare riferimento al sito documentale RTDS.

Customizzazione Tema