Struttura

Struttura delle cartelle

Tailwind

Sorgente: assets/css/main.css — importa i layer Tailwind (base, components, utilities) intervallati da CSS custom: assets/css/custom-properties.css e base.css nel layer base, il CSS di ogni componente (incluso automaticamente via @import-glob su tutte le cartelle components/**/*.css — nessuna registrazione manuale richiesta per i nuovi componenti) nel layer components, le utility colore semantiche nel layer utilities.

assets/css/custom-properties.css non è il file dei token del design system (colori, tipografia, spaziature) — quello è public/css/custom-properties.css, unica fonte di verità, consumato da tailwind.config.js (vedi sotto). L’omonimo file in assets/css/ è un file distinto e a scopo ristretto: definisce solo --adminbar-height/--header-height/--header-top-position, gli offset usati dall’header sticky quando la libreria è embeddata sotto una admin bar di CMS (es. WordPress, Liferay).

Build: npm run build:webpack (o npm run start/start:all in sviluppo, con watch) compila assets/css/main.css → public/css/main.css; npm run minify-css genera public/css/main.min.css via PostCSS + cssnano. Vedi Installazione e sviluppo per l’elenco comandi e Bundle CSS per come questo output confluisce nei bundle core.css/servizi.css/font.css distribuiti.

Configurazione in tailwind.config.js (root del repository): prefisso utility rtds- (ogni classe Tailwind generata è rtds-*) e valori (colori, spaziature, font-size…) letti da public/css/custom-properties.css via var(--…) — mai hardcodati.

Nunjucks / HTML

File sorgente/spazio di lavoro nella cartella components/, organizzata in categorie numerate:

Struttura della cartella di un componente — esempio component-example/:

• component-example.njk — template, sintassi Nunjucks (Fractal Nunjucks adapter); può contenere anche solo HTML semplice, senza markup Nunjucks, se il componente non ha logica condizionale
• component-example.css — stili del componente (Tailwind + custom properties)
• component-example.js — script del componente, se necessario
• component-example.config.yml — configurazione Fractal: contesto dati, varianti, metadati
• README.md — documentazione: markup, classi, parametri di configurazione, esempi d’uso. Template di riferimento: components/TEMPLATE_README.md

Public

Asset statici serviti/distribuiti così come sono, in public/:

Altre sottocartelle di public/ (illustrations/, logos/, media/) contengono asset di esempio usati solo negli esempi di alcuni componenti in Fractal — non fanno parte del bundle distribuito.

Dual Fractal

Il progetto ha due istanze Fractal separate, ognuna con il proprio build:

Le due istanze condividono la stessa cartella components/ — ogni componente è disponibile in entrambe via @handle.

Per avviarle entrambe con un solo comando: npm run start:all (vedi Installazione e sviluppo).

Dist

Output build nella cartella dist/, committata in git:

dist/
├── index.html                  ← Homepage hub (link a Core e Servizi)
├── core/                       ← Build statica Fractal Core
│   ├── index.html
│   ├── components/             ← Componenti statici (raw + render)
│   ├── docs/                   ← Documentazione fondamenta/core/servizi
│   ├── css/
│   │   ├── main.min.css        ← CSS bundle Tailwind compilato
│   │   ├── custom-properties.css
│   │   ├── core.css            ← Bundle componenti core
│   │   ├── servizi.css         ← Bundle componenti servizi
│   │   ├── font.css
│   │   └── liferay/            ← Integrazione legacy multi-CMS (non toccare)
│   ├── js/
│   ├── fonts/
│   └── icons.svg
├── servizi/                    ← Build statica Fractal Servizi
│   └── (stessa struttura di core/)
├── temp/                       ← Staging: Storybook Core + Servizi + homepage hub
│   ├── index.html              ← Hub di staging
│   ├── core/                   ← Build Storybook Core
│   └── servizi/                ← Build Storybook Servizi
└── css/
    ├── components/             ← CSS per componente (standalone)
    └── servizi/                ← CSS bundle servizi (standalone)

I build vengono generati dai comandi:

Risorse (immagini, font, SVG, JS)

La sezione Public sopra copre dove si trova ogni tipo di risorsa; qui il come aggiornarla.

• Immagini — aggiungere in public/images/ seguendo le convenzioni di naming descritte in Immagini. Nessun passaggio di build richiesto: sono servite/distribuite as-is.
• Font — il font di default (Open Sans) e le sue regole @font-face sono già presenti in font.css; per aggiungerne uno nuovo o capire il meccanismo di inclusione (font.css non è importato in core.css/servizi.css, va sempre linkato a parte) vedi Font.
• SVG (icone sprite) — aggiungere il sorgente in public/svgs/{eventuale-sottocartella}, poi rigenerare lo sprite con npm run build-svgs (compila icons.svg e aggiorna la config Fractal così la nuova icona sia selezionabile nel componente icon) — vedi Sprite SVG.
• JS componenti — un file .js nella cartella del componente viene incluso automaticamente nel bundle componentsJs.js alla build — vedi Risorse JS.