Fractal è uno strumento open source per costruire style guide e librerie di componenti: prende i template sorgente di un progetto (in RTDS, file Nunjucks .njk), li renderizza con dati di esempio e li espone in un’interfaccia web navigabile — una sidebar con tutti i componenti, un’anteprima interattiva per ciascuno, il markup HTML generato, e una sezione di documentazione libera in Markdown a fianco.
RTDS lo usa come unica fonte della UI di consultazione: sia la doc dei componenti (ogni pagina che si consulta in questo sito), sia le pagine di testo come questa, sono generate da Fractal. Non è un CMS: i contenuti sono file versionati nel repository, Fractal si limita a renderizzarli.
Cosa fa Fractal e cosa no. Fractal renderizza i template .njk e genera la UI di consultazione (sidebar, anteprime, questa stessa documentazione) — non compila CSS o JavaScript: per queste attività delega a strumenti di build esterni, integrabili tramite la sua API. In RTDS quel lavoro è affidato a Webpack, con una configurazione specifica del progetto: legge i CSS sorgente (assets/css/), li elabora con Tailwind CSS e PostCSS (autoprefixer incluso) e produce i CSS pubblicati in public/css/; allo stesso tempo raggruppa il JavaScript dei singoli componenti in un unico bundle (componentsJs.js) — un’aggregazione non prevista da Fractal, ma configurata ad hoc per RTDS. In sviluppo, npm run start avvia Fractal e Webpack in parallelo (insieme a un piccolo watcher dedicato ai CSS dei componenti): si vede quindi l’anteprima aggiornarsi automaticamente perché i due processi lavorano fianco a fianco, ma sono strumenti distinti con responsabilità distinte. In build di produzione la sequenza è invece esplicita: prima Webpack compila gli asset, poi Fractal genera la UI statica che li referenzia già pronti.
RTDS non gira su una singola istanza Fractal, ma su due, con perimetri di componenti diversi:
Il quadro completo (contenuto, dev server, cartelle di build) è descritto in Struttura delle cartelle e nelle pagine di collegamento reciproco Fractal Servizi / Fractal Core. Questa pagina non ripete quel contenuto: si concentra su Fractal come strumento e su cosa RTDS ha personalizzato rispetto al comportamento di base.
Alcuni aspetti dell’interfaccia non sono il comportamento predefinito di Fractal, ma scelte fatte per RTDS:
Tema grafico brandizzato. L’interfaccia (sidebar, tipografia, colori) usa il tema @frctl/mandelbrot, personalizzato con l’identità visiva di Regione Toscana — non è l’aspetto di default che si otterrebbe installando Fractal senza configurazione.
Sidebar componenti filtrata per istanza. Ogni istanza mostra solo il proprio perimetro: Fractal Core nasconde le collezioni widgets/servizi/templates-servizi, Fractal Servizi nasconde tutte le collezioni “core” (atoms, molecules, organisms, template, portale istituzionale) mostrando solo design-system, widget e servizi. Se una categoria che ci si aspetterebbe non compare nella sidebar, è per questo filtro intenzionale — i componenti restano comunque disponibili nel codice sorgente condiviso, semplicemente non sono navigabili da quella specifica istanza.
Sidebar documentazione filtrata per istanza. Allo stesso modo, alcune pagine di questa sezione “documentazione” sono nascoste in un’istanza e visibili nell’altra (ad esempio le pagine tecniche pensate per chi lavora sul repo, o i contenuti specifici di ciascun perimetro).
Resource browser filtrato. Aprendo la scheda risorse di un componente si vedono solo gli asset reali (template, CSS, JS, config) e non i file di predisposizione interna usati per generare Storybook, esclusi deliberatamente dalla vista.
Alcuni link di questa documentazione (in particolare quelli che puntano da un’istanza all’altra, o tra pagine di documentazione) risultano leggermente diversi a seconda di dove li si consulta: in locale durante lo sviluppo puntano al server di sviluppo dell’altra istanza (es. un indirizzo localhost), nella build pubblicata puntano invece al percorso relativo corretto. È un adattamento automatico che permette ai link di funzionare in entrambi i contesti senza doverli riscrivere manualmente.
Per le note tecniche di manutenzione su queste personalizzazioni (utile a chi lavora sul repository, non necessario per consultare o integrare RTDS), vedi Fractal — personalizzazioni tecniche.