# Regione Toscana Design System — pacchetto di distribuzione

Questo archivio contiene i fogli di stile, il JavaScript, i font e gli asset del
Design System di Regione Toscana, più il markup renderizzato di ogni componente
come materiale di riferimento.

Canale: **staging**. I dettagli della build sono in `BUILD-INFO.txt`.

---

## 1. Cosa caricare per avere qualcosa che funziona

Nell'ordine:

```html
<link rel="stylesheet" href="css/custom-properties.css">
<link rel="stylesheet" href="css/core.css">
<link rel="stylesheet" href="css/servizi.css">
<link rel="stylesheet" href="css/font.css">
<script src="js/componentsJs.js" defer></script>
```

**`custom-properties.css` non è opzionale e non è incluso negli altri file.**
Contiene tutti i token del Design System — colori, spaziature, tipografia — e i
bundle li consumano via `var(--…)`. Senza di lui i componenti si caricano senza
colori né spaziature. È una dipendenza runtime, va servita insieme al resto.

`core.css` copre i componenti di base; `servizi.css` aggiunge widget e
componenti per i servizi digitali: se non li usi, puoi ometterlo. Di entrambi
esiste la versione minificata (`core.min.css`, `servizi.min.css`) per la
produzione.

`font.css` dichiara gli `@font-face` di Open Sans e cerca i file in
`../fonts/open-sans/`. Se sposti `css/` da un'altra parte, la cartella
`fonts/` deve restare sua sorella, oppure vanno corretti i percorsi.

## 2. I file per componente sono riferimento, non pacchetti autonomi

Sotto `components/` ogni componente ha il markup delle sue varianti, e dove
esiste il proprio `.css` e `.js`.

**Il `.css` di un componente da solo non basta a renderizzarlo.** Il markup usa
classi utility (`rtds-flex`, `rtds-items-center`, `rtds-gap-0.5`,
`rtds-mt-auto`, `rtds-pr-12`…) che stanno soltanto nei bundle `core.css` e
`servizi.css`. Quei file servono a leggere come è fatto un componente e a
copiarne le parti che ti servono, non a caricarne uno alla volta.

## 3. Per vedere gli snippet serve un server http locale

Aprire un file `.html` con un doppio clic non funziona: le icone non compaiono.
Sono riferimenti `<use href>` a uno sprite SVG esterno, e i browser li bloccano
su `file://` perché l'origine è opaca. Riguarda la maggior parte degli snippet.

Dalla radice di questo archivio:

```bash
python3 -m http.server 8000
# poi apri http://localhost:8000/components/…
```

## 4. Dipendenze terze incluse

Sono in `css/libraries/` e `js/libraries/`. Vanno caricate solo se usi i
componenti che le richiedono:

| Libreria | Serve a |
|---|---|
| splide | slider, carousel |
| tobii-lightbox | gallery |
| accessible-autocomplete | autocomplete-select-field |

## 5. La cartella `cdn/`

`cdn/` contiene il sottoinsieme pensato per essere pubblicato su una CDN: i CSS
minificati più i token, `font.css`, i font Open Sans e il JavaScript del Design
System — l'aggregato `componentsJs.js` e i file per singolo componente sotto
`js/components/`.

Replica il layout della radice (`css/`, `js/`, `fonts/` fratelli) e non è
piatta: `font.css` cerca i font in `../fonts/open-sans/`, e le due cartelle
devono restare in questa relazione. Il vantaggio è che i percorsi sono gli stessi
nei due rami, quindi lo stesso riferimento vale sia che la base sia l'URL della
CDN sia una copia locale di questo archivio:

```html
<link rel="stylesheet" href="{base}/css/core.min.css">
```

**Le tre librerie terze non sono in `cdn/`**, di proposito: splide,
tobii-lightbox e accessible-autocomplete hanno un proprio ciclo di rilascio e di
sicurezza, e ripubblicarle metterebbe la loro manutenzione a carico del Design
System. Restano in questo archivio sotto `css/libraries/` e `js/libraries/`,
da servire da dove preferisci.

Se non devi pubblicare niente su una CDN, `cdn/` è materiale che hai già negli
altri percorsi: puoi ignorarla.

---

Documentazione completa dei componenti, con parametri e note di accessibilità:
sito documentale del Design System. Questo archivio ne è l'artefatto di
distribuzione, non la documentazione.
