`, ``
- Evitare abbreviazioni ambigue (es: "info" vs "informazione")
- Titoli gerarchici coerenti (h3, h4, h5)
- Lingua italiana consistente (no "inglesia" miscelata)
**Validazione**: Prima di publishare changelog, verificare tutti 7 punti su almeno la versione corrente e una precedente per coerenza.
### 1.6 Regola Decisionale Trigger Aggiornamento Instructions
Quando una modifica nel changelog DEVE propagarsi in instructions.md:
#### ✅ AGGIORNA instructions se changelog introduce:
- **Nuova procedura critica**: Rollback, audit pre-rimozione, setup workflow
- *Esempio*: Procedura di rollback sicuro v1.0.17 → sezione 8.11 instructions
- *Motivo*: Non è specifica della versione, è una regola generale riutilizzabile
- **Nuova eccezione whitelist approvata**: Hardcoding pattern, naming convention
- *Esempio*: Utility classes menu-color-* hardcoded → sezione 7.1 (Eccezioni Approvate)
- *Motivo*: Serve a developer futuro per distinguere "allowed" da "prohibited"
- **Nuova architettura layer**: Mixin aggiunto, configuration subdirectory, sezione refactor
- *Esempio*: Creazione `_dynamic-states.scss` mixin layer → sezione 8 (Mixins)
- *Motivo*: Futur development dipende da questa architettura
- **Regola naming convention che diviene standard**: File prefix, classe pattern
- *Esempio*: Standardizzazione `bi-*` prefix per sezioni → sezione 3.2
- *Motivo*: Deve guidare tutti i file futuri
- **Mixin/pattern riutilizzabile identificato**: Focus-shadow-dynamic, smooth-transition
- *Criterio*: Se usato in 3+ file diversi → va centralizzato in instructions
- *Motivo*: Nuovo developer deve sapere che esiste
- **Presa decisione strategica definitiva**: Non rivisitabile, fondazione architetturale
- *Esempi*: A1/A2/C3 layers, CSS Custom Properties per colori dinamici
- *Motivo*: Definisce identità progettuale
#### ❌ NON aggiorna instructions se changelog descrive:
- **Fix specifico versione**: Bug-squash locale, regressione single-component
- *Esempio*: "Logo header invisibile su tablet" fix v1.0.16
- *Motivo*: Non generalizzabile, solo v1.0.16 ha avuto questo problema
- **Test/validazione risultati**: Metrics, grep results, test coverage
- *Esempio*: "100/100 pattern normalizzati", "0 z-index violations"
- *Motivo*: Snapshot versione-specifica, non regola generale
- **Operazioni file temporanee**: Legacy cleanup, one-off refactoring
- *Esempio*: "Rimosso file _old-colors.scss non usato"
- *Motivo*: Non è una procedura, è una pulizia locale
- **Dettagli implementativi task**: Come è stato codato, iterazioni intermediate
- *Esempio*: "Tentato con mixin breakpoint, fallback a media query"
- *Motivo*: Implementazione detail, non architettura
**Processo Decisionale**:
1. Leggere sezione changelog
2. Fare domanda: "Un developer futuro avrà bisogno di sapere esto?"
3. Se SÌ → Probabilmente va in instructions
4. Se NO → Probabilmente rimane changelog-only
5. In caso di dubbio, consultare tabella 1.4 (Linee Guida Separazione)
### 1.7 Chiusura Versionamento (nota operativa)
Per la chiusura di una versione usare la checklist sintetica in:
- **[versioning_closure.md](versioning_closure.md)**
Questa checklist e complementare a `instruction.md`:
- `instruction.md` definisce principi permanenti
- `versioning_closure.md` definisce il flusso operativo minimo di chiusura release
---
## 2. Contesto del Progetto
### 2.1 Descrizione e Obiettivi
Creare un template per **Joomla** chiamato **Bootstrap .Italia**, basato su **Gantry 5** e **Bootstrap Italia**. Il template deve rispettare le linee guida di **Designers Italia** e le direttive di **AGID**, garantendo interfacce web moderne, responsive e accessibili per la **Pubblica Amministrazione italiana**.
### 2.2 Stack Tecnologico
| Tecnologia | Dettagli |
|---------------------|-------------------------------------------------------------------------|
| **CMS** | Joomla 5.x (compatibilità con moduli, plugin e componenti). |
| **Framework** | Gantry 5 (layout manager, particles, atoms, YAML, Twig). |
| **CSS/UI** | Bootstrap Italia v2.17.2 (o successivo). |
| **Linguaggi** | PHP, Twig, SCSS/CSS, JavaScript, YAML. |
**Compatibilità**: Il template è compatibile con Joomla 5.x e versioni successive. Utilizzare una versione aggiornata di Joomla per garantire il corretto funzionamento.
### 2.3 Decisione Architetturale: Gantry vs Template Core (Cassiopea)
**Decisione**: Il progetto usa **Gantry 5** come framework base (non Cassiopea).
**Razionale**:
- **Configurabilità**: Particles + Layout Manager permettono gestione completa da backend senza sviluppare UI custom.
- **Scalabilità SCSS**: Architettura a layer (A1/A2/C3), variabili centralizzate e valori dinamici nativi.
- **Manutenibilità**: Separazione schema/render/config riduce override Joomla complessi e fragili.
- **Velocità di sviluppo**: Framework fornisce pattern riusabili, riducendo lavoro su funzioni admin custom.
**Trade-off accettato**:
- Dipendenza dal framework Gantry, compensata da maggiore produttività e controllo architetturale.
### 2.4 Struttura Generale del Progetto
- **Layout**: Gestito tramite il **Layout Manager di Gantry**. La struttura delle pagine è definita in file `.yaml`.
- **Componenti Riutilizzabili**: Implementati come **Particles** e **Atoms** Gantry, basati su Bootstrap Italia.
- **Stilizzazione**: Utilizzare `SCSS` per estendere o modificare gli stili di Bootstrap Italia.
- **JavaScript**: Integrare script seguendo le modalità previste da Gantry e Joomla.
### 2.5 Integrazione con Joomla
1. **Moduli e Plugin**: Creare moduli Joomla che utilizzano i **Particles** di Gantry.
2. **Override di Template**: Personalizzare la visualizzazione di componenti core tramite override. Vedere **[joomla_override_conventions.md](joomla_override_conventions.md)** per convenzioni standardizzate.
3. **Gestione Menu**: Configurare i menu di Joomla per utilizzare le classi di Bootstrap Italia.
4. **Multilingua**: Supportare il sistema multilingua di Joomla.
5. **Accessibilità**: Verificare che il template rispetti le linee guida di Joomla e Bootstrap Italia.
**📘 Convenzioni Override**: Per creare nuovi override Joomla seguire le linee guida in **[joomla_override_conventions.md](joomla_override_conventions.md)** che definiscono:
- Struttura directory standardizzata
- Naming convention SCSS (`_bi-nome.scss`)
- Posizionamento file (`scss/bootstrapitalia-joomla/`)
- Template README.md per documentazione
- Procedura step-by-step completa
---
## 📚 Risorse di Riferimento Rapido
- **[STRUCTURE.md](structure.md)** - Inventario completo directory/file, legenda (auto-generati vs installazione), note su `custom/` e compilazione SCSS
- **[hydrogen_sync.md](hydrogen_sync.md)** - Procedura ufficiale di sincronizzazione core Hydrogen (file, metadata, checklist)
- **[architetture_report.md](architetture_report.md)** - Architettura a layer (A1/A2/C3), dipendenze, governance del core Hydrogen
- **[joomla_override_conventions.md](joomla_override_conventions.md)** - Convenzioni standardizzate per override componenti Joomla (naming, struttura, procedure)
- **[versioning_closure.md](versioning_closure.md)** - Checklist breve per chiudere una versione (version/date/link/case-sensitive/coerenza metadata)
- **[Changelog - Release Stable](../changelogs/version/stable/changelog.html)** - Cronologia versioni stabili
- **[Changelog - Release Beta](../changelogs/version/beta/changelog.html)** - Cronologia versioni beta, regole architetturali, fix e miglioramenti
- **[Changelog - Release Alpha](../changelogs/version/alpha/changelog.html)** - Prima release sperimentale, setup iniziale
---
## 3. Regole Generali di Sviluppo
Questa sezione è la **"Bibbia delle Regole Centrali"** del progetto - riferimento rapido e completo di tutte le convenzioni permanenti che devono essere seguite nello sviluppo. Sono regole valide **sempre**, che trascendono specifiche sezioni o componenti.
Ordine logico: **Preset & Layout** → **Particelle** → **Atoms** → **SCSS** (implementazione sottostante).
---
### 3.1 Layout Gantry e Sezioni
**Regola Stacking Context Globale**:
- `#g-page-surround`: z-index base layer (z-index: auto o 1000) - RADICE
- `#g-top`: z-index ≥ 1003 (da `$z-top`)
- `#g-header`: z-index ≥ 1000 (da `$z-header`)
- `#g-navigation`: z-index ≥ 1002 (da `$z-navigation`)
- `.g-offcanvas-toggle`: z-index: 1035 (da `$z-offcanvas-toggle`), `position: absolute` o `fixed` (MAI relative)
- Nessun overlay indesiderato tra sezioni
**Regola Positioning Offcanvas Toggle**:
- DEVE essere `position: absolute` o `position: fixed`, MAI `position: relative`
- Utilizzo relative fa occupare spazio nel flusso, generando bande/offset indesiderati
- Toggle deve essere sempre overlay su contenuto, non parte del flusso normale
**Regola A1/A2/C3 Governance Layers**:
- **A1** (Admin/Core Gantry): Layout base, sezioni strutturali (top, header, navigation, footer, sidebar, mainbody)
- **A2** (Advanced/Sezioni Refactor): File prefisso **bi-** (_bi-top.scss, _bi-header.scss, etc.) - dipendono da C3
- **C3** (Configuration/Core Style Layer): `scss/configuration/` e `scss/mixins/` - variables-only, no direct CSS
**Regola Responsive Sezioni**:
- Testare OBBLIGATORIAMENTE su 3 breakpoint: Mobile Small (480px), Tablet (768px), Desktop (1200px)
- Confrontare ogni modifica tra `layouts/default.yaml` e `custom/config/*/layouts/`
- Verificare coerenza page-surround, top, header, sidebar, mainbody, footer senza rotture
---
### 3.2 Particelle - YAML Configuration
**Regola Particles - Dipendenza Atoms**:
- Le Particles dipendono dagli **Atoms globali** per tutte le risorse CSS/JS
- ❌ **MAI aggiungere** campi `version` o `css_url` alle Particles
- ❌ **MAI caricare** CSS di Bootstrap Italia direttamente dalle Particles
- ✅ **Aggiungere avvertenze `_info`** (alert danger) che dichiarano esplicitamente la dipendenza dagli Atoms
- Tutte le particelle usano variabili SCSS di Gantry: `$base-text-color`, `$accent-color-1`, `$accent-color-2`
**Regola YAML Configuration**:
- Ogni particle ha file YAML associato: `particles/modale-login.yaml`, `particles/bootstrapitalia-modale-login.html.twig`
- Campo `enabled: true` in YAML per abilitare particle
- Campi configurazione devono essere **chiaramente documentati** con descrizioni
- Pattern YAML: `label`, `description`, `type`, `default`, `options` per ogni campo
**Regola File Particles - Naming**:
- Tutti i file particella usano prefisso **_bootstrapitalia-**: `_bootstrapitalia-modale-login.scss`, `_bootstrapitalia-preset-switcher.scss`, `_bootstrapitalia-icone-link.scss`, etc.
- Ogni particella ha uno e un solo file SCSS corrispondente
- File YAML corrispondente ha nome identico: `modale-login.yaml` → `_bootstrapitalia-modale-login.scss`
**Regola Override Particelle Gantry Nucleus**:
- **Override particelle Nucleus** (branding, logo, copyright, menu, etc.) vanno in `particles/` (root template), **NON in `custom/particles/`**
- Rationale: Override in `particles/` fanno parte dell'**identità del template distribuito** e vengono caricati sia in Layout Gantry che come moduli Joomla
- Pattern: Copiare Twig + YAML da `/media/gantry5/engines/nucleus/particles/` → `particles/` del template
- Esempio: `particles/branding.html.twig` + `particles/branding.yaml` sovrascrivono la particella core Nucleus
- ⚠️ **`custom/particles/` va usato SOLO per personalizzazioni site-specific** non distribuite con il template (es. cliente singolo, test non ancora approvati)
- Aggiornamenti template: File in `particles/` vengono sovrascritti, quelli in `custom/particles/` sono protetti
**Regola Cleanup File Orfani `custom/config/*/particles/`**:
- **Problema**: Quando si crea primo outline, Gantry copia configurazioni particelle da template base in `custom/config/default/particles/`
- Se successivamente rimuovi/modifichi particelle in `particles/`, i file in `custom/config/` diventano **orfani** e possono bloccare caricamento valori default
- **File orfani comuni**: Particelle Gantry standard (content, menu, social, messages, totop, spacer, etc.) non usate nel template custom
- **Soluzione**: Eliminare periodicamente file vuoti/obsoleti in `custom/config/*/particles/`
- **Comando audit**:
```bash
# Trova file vuoti
find custom/config/*/particles/ -type f -empty
# Elimina file vuoti (con cautela)
find custom/config/*/particles/ -type f -empty -delete
```
- **Best Practice**: Dopo setup iniziale outline, cleanup immediato file non utilizzati
- **Nota**: Template Hydrogen alla prima installazione NON ha cartella `custom/` - viene creata solo al primo salvataggio outline in Gantry Admin
- **Distribuzione Template**: La cartella `custom/` NON va distribuita e non va versionata (auto-generata da Gantry). Aggiungere a `.gitignore`:
- `/custom/`
- `/custom/css-compiled/`
**Regola MD5SUMS (Integrita\' Pacchetto)**:
- Aggiornare `MD5SUMS` **solo in fase di rilascio/distribuzione**, non a ogni micro-edit in sviluppo
- Obbligatorio quando cambia la struttura o i file inclusi nel pacchetto (aggiunte/rimozioni/modifiche)
- Il formato usato in questo progetto e\': `percorso/filehash` (non quello standard di `md5sum -c`)
- Esclusioni intenzionali dal manifest di release: `.github/`, `changelogs/`, `custom/`, `backup_*/`, `*.log`
- Comando ufficiale di rigenerazione (script progetto):
```bash
cd /path/al/template
python3 .github/scripts/regenerate-md5sums.py
```
- Esecuzione valida solo con path corretto dello script:
- ✅ Da root template: `python3 .github/scripts/regenerate-md5sums.py`
- ✅ Da qualsiasi cartella: `python3 /percorso/assoluto/templates/bootstrapitalia/.github/scripts/regenerate-md5sums.py`
- ❌ Non valido dalla root template: `python3 regenerate-md5sums.py` (file non presente in root)
- Errore comune atteso: `python3: can't open file ... regenerate-md5sums.py: [Errno 2] No such file or directory`
- Causa: comando lanciato senza prefisso `.github/scripts/`
- Fix: usare il comando ufficiale sopra
#### Quick Commands (Release)
```bash
# 1) Rigenera MD5SUMS (comando ufficiale)
cd /path/al/template
python3 .github/scripts/regenerate-md5sums.py
# 2) Verifica integrita' MD5SUMS (self-row esclusa)
python3 - <<'PY'
import hashlib, os
ok = miss = mis = 0
for l in open('MD5SUMS', encoding='utf-8', errors='replace'):
l = l.strip()
if not l or '\t' not in l:
continue
p, h = l.split('\t', 1)
if p == 'MD5SUMS':
continue
if not os.path.isfile(p):
miss += 1
continue
with open(p, 'rb') as f:
g = hashlib.md5(f.read()).hexdigest()
if g == h:
ok += 1
else:
mis += 1
print('OK', ok, 'MISSING', miss, 'MISMATCH', mis)
PY
# 3) Verifica sintassi installer
php -l install.php
```
One-line (copy/paste rapido):
```bash
# Rigenera MD5SUMS
python3 .github/scripts/regenerate-md5sums.py
# Verifica integrita' MD5SUMS (self-row esclusa)
python3 -c "import hashlib,os;ok=miss=mis=0
for l in open('MD5SUMS',encoding='utf-8',errors='replace'):
l=l.strip();
if not l or '\t' not in l: continue
p,h=l.split('\t',1)
if p=='MD5SUMS': continue
if not os.path.isfile(p): miss+=1; continue
g=hashlib.md5(open(p,'rb').read()).hexdigest()
ok += (g==h); mis += (g!=h)
print('OK',ok,'MISSING',miss,'MISMATCH',mis)"
# Verifica sintassi installer
php -l install.php
```
**Regola Permanente - Sync Cleanup Installer (Task 4)**:
- Il cleanup orphan in `install.php` resta **attivo in sviluppo** per evitare residui quando si passa tra release vecchie/nuove.
- Artefatti runtime (log/backup sync) salvati in: `custom/sync-runtime/` (mai nella root del template).
- Whitelist minima obbligatoria da proteggere in `isProtectedPath()`:
- `custom/`
- `changelogs/`
- `backup_*/`
- `.git/`
- `.github/`
- Il cleanup usa confronto `old/new` con fallback filesystem reale per intercettare anche file non tracciati nel manifest.
- Policy operativa toggles (`install.php`):
- `$syncCleanupEnabled = true` (sempre true in dev e release)
- `$syncBackupEnabled = true` in sviluppo; valutare `false` in produzione se backup e\' gestito a livello deploy
- `$syncLogEnabled = true` in sviluppo; opzionale in produzione secondo necessità di audit
- Nota release: se `changelogs/` non e\' distribuito nel pacchetto, deve restare comunque protetto per evitare cancellazioni accidentali in ambienti di lavoro.
- Validazione minima prima di chiudere una release:
- `python3 .github/scripts/regenerate-md5sums.py`
- `php -l install.php`
- update di prova con verifica output cleanup + controllo file `install_cleanup_*.log`
**Semaforo Preflight (interpretazione unica)**:
- **🟢 Verde**: versioni allineate (`templateDetails.xml` ↔ `gantry/theme.yaml`), `php -l install.php` OK, `MD5_MISMATCH=0` e `MD5_MISSING=0`.
- **🟡 Giallo**: lint/versioni OK ma `MD5_MISMATCH>0` (rigenerare manifest e ricontrollare).
- **🔴 Rosso**: versioni non allineate, lint fallito o file mancanti.
**Regola Permanente - Integrità Entry SCSS Joomla**:
- `scss/bootstrapitalia-joomla.scss` è un entrypoint critico e **non deve mai risultare vuoto**.
- Import minimi obbligatori:
- `@import "configuration/base";`
- `@import "mixins/base";`
- import dei layer Joomla necessari (es. `bootstrapitalia-joomla/bi-finder`, `bootstrapitalia-joomla/bi-user`).
- Prima di chiudere attività su override Joomla, verificare che l'entrypoint includa il file SCSS del componente toccato.
**Regola Permanente - Bottoni Outline Bootstrap (`.btn-outline-*`)**:
- Per stili dinamici robusti non basta impostare solo `border-color`/`color`.
- In presenza di Bootstrap Italia, definire sempre anche le variabili native `--bs-btn-*` nel contesto componente:
- `--bs-btn-color`
- `--bs-btn-border-color`
- `--bs-btn-hover-color`
- `--bs-btn-hover-bg`
- `--bs-btn-hover-border-color`
- `--bs-btn-active-color`
- `--bs-btn-active-bg`
- `--bs-btn-active-border-color`
- I fallback devono puntare a token semantici C3 in `scss/configuration/_colors.scss` (evitare hardcode locale nei layer A2).
**Profilo Produzione (Go-Live) - Passaggi Mirati**:
1. Definire policy runtime in `install.php`:
- mantenere `$syncCleanupEnabled = true`
- impostare `$syncBackupEnabled` secondo strategia backup infrastrutturale
- impostare `$syncLogEnabled` secondo policy audit/retention
2. Rigenerare manifest release: `python3 .github/scripts/regenerate-md5sums.py`
3. Verificare installer: `php -l install.php`
4. Eseguire update di prova in staging e verificare:
- messaggio cleanup in backend Joomla
- artefatti in `custom/sync-runtime/`
- assenza cancellazioni su path protetti (`custom/`, `changelogs/`, `.github/`)
5. Solo dopo staging verde, promuovere il pacchetto in produzione.
---
### 3.3 Atoms - CDN Versioning e Dipendenze
**Regola Atoms - Single Source of Truth**:
- **Versione di Bootstrap Italia gestita CENTRALMENTE** nell'Atom CDN
- Atom Icons legge automaticamente la versione dall'Atom CDN via `gantry.config.get()`
- Procedura aggiornamento: Gantry Admin → Layout Manager → Atom CDN → Version field → Salva → Compile CSS → Pulisci cache
- Nessuna duplicazione CSS tra atoms, niente conflitti versioning
**Regola Atoms - Dipendenza Dichiarata**:
- Tutte le particelle nella YAML devono dichiarare chiaramente: "Questa particella richiede Atom CDN attivo"
- Se Atom CDN è disabilitato, la particella non funziona (avvertenza obbligatoria in _info)
- Nessun fallback CSS alternativo - dipendenza è non-negoziabile
---
### 3.4 SCSS: Principio Fondamentale - Colori Dinamici vs. Hardcoded
**REGOLA PRINCIPALE**: TUTTI i colori devono usare il pattern **CSS Custom Properties con fallback SCSS**:
```scss
color: var(--custom-property, $scss-fallback);
```
**Pattern Obbligatorio** (applicato a tutte le proprietà color/background/border-color):
```scss
// ✅ CORRETTO
color: var(--base-title-color, $base-title-color);
background-color: var(--well-background, $well-background);
border: 1px solid var(--base-border-color, $base-border-color);
// ❌ VIETATO
color: $base-title-color; // Manca CSS Custom Property
background-color: #f5f5f5; // Hardcoded
border-color: var(--primary); // Manca fallback SCSS
```
**Razionale**:
- Tematizzazione runtime senza ricompilare SCSS
- Fallback SCSS garantisce compatibilità browser legacy
- Preset-switcher può modificare GLOBALMENTE i colori via CSS Custom Properties
**Conseguenza Strutturale**:
- Se una variabile CSS custom property non esiste, crearla in `:root` o nel theme switcher
- Se una variabile SCSS fallback non esiste, aggiungerla in `configuration/_colors.scss`
- I file `configuration/` possono definire SCSS fallback con valori hardcoded (sono la fonte di verità)
- Tutte le sezioni, override, particles DEVONO usare il pattern `var(--prop, $fallback)`
**Scope Applicativo**: Questa regola si applica a:
- ✅ Sezioni template (`scss/bootstrapitalia/_bi-*.scss`)
- ✅ Override Joomla (`scss/bootstrapitalia-joomla/_bi-*.scss`)
- ✅ Particles (`scss/bootstrapitalia/_bootstrapitalia-*.scss`)
- ✅ System messages, modali, navigation, tutto
### 3.4.0 Bridge Runtime Colori (Regola Permanente)
Per garantire allineamento colori end-to-end tra preset Gantry, SCSS compilato e runtime, adottare sempre questo pattern:
1. **Source of truth preset**:
- `gantry/presets.yaml` e la fonte unica per i valori colore di preset.
- I fallback SCSS vanno allineati in `scss/configuration/_colors.scss`.
2. **Bridge token runtime obbligatorio**:
- Il file `scss/configuration/_css-tokens.scss` espone i token runtime in `:root` (es. `--base-*`, `--primary-*`, `--bs-primary`, `--well-background`).
- Non duplicare definizioni token runtime in file di sezione/override/particle.
3. **Import chain vincolante**:
- In `scss/configuration/_base.scss`, `@import "css-tokens";` deve restare attivo e in coda agli import configuration.
- Se assente o spostato in ordine non coerente, la release non e chiudibile.
### 3.4.1 Playbook Operativo - Diagnosi Colori Dinamici (Regola Permanente)
Quando un colore o uno stato interattivo non cambia in modo dinamico (es. `box-shadow` che resta blu), seguire SEMPRE questa sequenza unica.
1. **Partire dal computed style**, non dal sorgente SCSS.
- Identificare la proprieta finale bloccata (`color`, `border-color`, `background-color`, `box-shadow`, ecc.).
2. **Isolare la regola vincente in cascata**.
- Verificare selettore, specificita, ordine di caricamento e stato (`:hover`, `:focus`, `:focus-visible`, `:active`).
3. **Applicare la correzione nel layer corretto**.
- Token globali e variante base bottoni: `scss/bootstrapitalia-joomla/_buttons.scss`.
- Override componente: `scss/bootstrapitalia-joomla/_bi-*.scss` del componente coinvolto.
4. **Usare una sola catena runtime condivisa**.
- `--bi-btn-primary-bg`
- `--bi-btn-primary-border`
- `--bi-btn-primary-hover-bg`
- `--bi-btn-primary-hover-border`
- Evitare catene parallele con fallback eterogenei nello stesso blocco.
5. **Se Bootstrap impone un valore statico, sovrascrivere la proprieta finale**.
- Non fermarsi a variabili intermedie (`--bs-btn-*`) se il valore calcolato resta fisso.
- Impostare anche la proprieta concreta richiesta dal caso (es. `box-shadow`) con priorita adeguata nel contesto componente.
6. **Coprire tutti gli stati realmente usati dal browser/framework**.
- Al minimo: base, `:hover`, `:focus`, `:focus-visible`, `:active`.
- Se presente Bootstrap toggle/check flow, coprire anche pattern tipo `.btn-check:focus + .btn`.
7. **Validare su matrice minima prima di chiudere**.
- Preset: base, verde, rosso, neutro.
- Stato: base, hover, focus, active.
- Confermare da computed che non rimangano valori hardcoded (es. `#06c`) fuori dai casi consentiti.
**Regola d'oro**: una sola sorgente token + override mirato della proprieta realmente bloccata.
---
### 3.5 SCSS: Mixins per Stati Dinamici
**REGOLA**: Per garantire consistenza tra tutti gli elementi interattivi (input, button, link), gli stati dinamici (`:focus`, `:hover`, `:active`) DEVONO utilizzare mixins centralizzati invece di dichiarazioni duplicate.
**Mixins Disponibili** (in `scss/mixins/_dynamic-states.scss`):
**`focus-shadow-dynamic($opacity: 0.1)`**
- **Uso**: Applicare box-shadow su stati `:focus` con colore accent dinamico
- **Parametro**: `$opacity` (opzionale, default 0.1) - Opacità della shadow (0.0 a 1.0)
- **Esempio**:
```scss
input:focus {
border-color: var(--primary-color, $base-text-color);
@include focus-shadow-dynamic; // Opacity 0.1 (default)
}
button:focus {
@include focus-shadow-dynamic(0.2); // Opacity 0.2 per enfasi maggiore
}
```
- **VIETATO**: `box-shadow: 0 0 0 3px var(--accent-light, rgba(...))` hardcoded
- **Output**: `box-shadow: 0 0 0 3px var(--accent-light, rgba(0, 102, 204, $opacity));`
**Principio "Valori a Monte"**: Prima di applicare stili ripetuti in più file, verificare se esiste un mixin centralizzato. Se non esiste, crearlo in `scss/mixins/` e applicarlo uniformemente.
---
### 3.6 SCSS: Variabili Centralizzate (Configuration Layer - C3)
**Regola Fondamentale**: Tutte le variabili usate in **3+ file diversi** DEVONO essere centralizzate in `scss/configuration/` e accessibili da tutte le sezioni.
**Variabili Z-Index** (`_z-index.scss`):
- `$z-base: 1000` - Livello base sezioni
- `$z-header: 1000` - Header
- `$z-navigation: 1002` - Navigation bar
- `$z-top: 1003` - Top section
- `$z-offcanvas-overlay: 1010` - Offcanvas backdrop
- `$z-preset-switcher: 1031` - Preset switcher dropdown
- `$z-offcanvas-toggle: 1035` - Offcanvas toggle button
- `$z-modal: 1900` - Modali (login, ricerca)
- `$z-popover: 1920` - Popover e tooltip
**Variabili Spacing** (`_core.scss`):
- `$spacing-xs: 0.25rem` - Gap icone, padding badge
- `$spacing-sm: 0.5rem` - Padding compatti, margin verticali
- `$spacing-md: 1rem` - Margin inline standard
- `$spacing-lg: 1.5rem` - Padding contenitori base
- `$spacing-xl: 2rem` - Separazione sezioni
- `$spacing-xxl: 2.5rem` - Padding modal/card
- `$spacing-xxxl: 3rem` - Spacing extra-large
- `$touch-target-min: 44px` - WCAG 2.1 AA minimo
- `$spacing-none: 0 !default` - Centralizzazione zero-spacing
**Variabili Transitions** (`_core.scss`):
- `$transition-fast: 0.15s ease-in-out` - Hover rapidi, icon animation
- `$transition-standard: 0.3s ease-in-out` - Transizioni standard (button, card)
- `$transition-slow: 0.5s ease-in-out` - Animazioni complesse
**Variabili Opacity** (`_core.scss`):
- `$opacity-disabled: 0.4` - Elementi disabilitati
- `$opacity-secondary: 0.6` - Testo secondario, close button
- `$opacity-hover: 0.8` - Stati hover intermedi
- `$opacity-full: 1` - Opacity piena (reset)
**Variabili Typography** (`_core.scss`):
- `$font-weight-light: 300`
- `$font-weight-normal: 400`
- `$font-weight-semibold: 600` - Alert heading, strong text
- `$font-weight-bold: 700`
- `$line-height-tight: 1.2` - Heading compatti
- `$line-height-base: 1.6` - Body text standard
- `$line-height-relaxed: 1.8` - Paragrafi estesi
**Variabili Custom Components** (`_core.scss`):
- `$well-background: hsl(0, 0%, 96%)` - Background container .well (com_users)
- `$form-group-margin: $spacing-lg` - Margine form groups
- `$shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.1)` - Box shadow sottile
**Variabili Colori** (`_colors.scss`):
- Per ogni sezione (top, header, navigation, etc.): `$[section]-background-color`, `$[section]-text-color`, `$[section]-heading-color`, `$[section]-link-color`, `$[section]-link-hover-color`
- Colori neutrali globali: `$white`, `$black`, `$off-white`
- Overlay: `$overlay-dark: rgba(0, 0, 0, 0.8)`
**Variabili Typography** (`_typography.scss`):
- `$fonts-body-font: "Titillium Web"` (+ fallback)
- `$fonts-heading-font: "Titillium Web"` (+ fallback)
- `$fonts-menu-font: "Titillium Web"` (+ fallback)
- `$font-family-mono: "Roboto Mono"` (+ fallback)
- `$font-family-serif: "Lora"` (+ fallback)
- `$font-weight-regular: 400`, `$font-weight-medium: 500`, `$font-weight-bold: 700`
- Heading sizes: `$h1-font-size`, `$h2-font-size`, ... `$h6-font-size` (scalabili da `$fontsizes-body-font-size`)
**Variabili Breakpoints** (`_breakpoints.scss`):
- `$bp-mobile-small: 480px`
- `$bp-tablet: 768px` - Breakpoint critico
- `$bp-desktop: 992px`
- `$bp-large: 1024px`
- `$bp-xl: 1200px`
**Regola ZERO Hardcoding in Sezioni**: Nessun valore numerico (z-index, colors hex, breakpoints px, spacing rem) deve essere hardcoded nei file bi-* o nelle particelle. SEMPRE usare variabili da configuration/.
**Whitelist Eccezioni Accettate (SCSS UI Layer)**:
- Valori tecnici di accessibilità WCAG per utility `visually-hidden` sono consentiti **solo se centralizzati** in token C3 (es. `$a11y-visually-hidden-size`, `$a11y-visually-hidden-margin`)
- Micro-motion strutturale (`translateY`, keyframes di ingresso/uscita) è consentita **solo se tokenizzata** in `configuration/_core.scss` (es. `$motion-lift-sm`, `$motion-lift-md`, `$motion-fade-enter-y`)
- Fallback `var(--prop, $fallback)` con funzioni colore (`rgba(...)`) è consentito quando il fallback usa token C3 e non valori semantici duplicati inline
**Criterio Obbligatorio di Standardizzazione**:
- Se un valore compare in **2+ punti** nello stesso file o in file diversi, promuoverlo a token C3
- Se un valore governa comportamento cross-componente (focus, motion, a11y utility), promuoverlo a token C3 anche con singola occorrenza
- Inline values non tokenizzati sono accettati solo per casi eccezionali documentati nel changelog e approvati in review
---
### 3.7 SCSS: Convenzioni di Naming
**Regola File Configuration Layer (C3)**:
- Tutti i file di configurazione in `scss/configuration/` devono usare underscore prefix: `_colors.scss`, `_spacing.scss`, `_z-index.scss`, `_typography.scss`, `_breakpoints.scss`, `_core.scss`
- Nessun file in configuration può contenere regole CSS dirette, SOLO variabili e placeholder
**Regola File Sezioni (A2)**:
- Tutti i file di sezione refactor DEVONO usare prefisso **bi-**: `_bi-top.scss`, `_bi-header.scss`, `_bi-offcanvas.scss`, `_bi-menu.scss`, `_bi-drawer.scss`, `_bi-navigation.scss`, etc.
- I file legacy senza prefisso **NON vanno importati** nel main entry-point (`scss/bootstrapitalia.scss`)
- Ogni sezione ha un file bi-* dedicato: una sezione = un file bi-*
---
### 3.8 SCSS: File Management e Legacy
**Regola Importazione File SCSS**:
- **Import Order OBBLIGATORIO**: Configuration → Mixins → Sections
- Nessun @import in sezione bi-* può puntare FORWARD a altra sezione non ancora importata
- Ogni sezione bi-* importa SOLO da configuration/ e mixins/ (layers precedenti)
- Cross-sezione reference è VIETATA
**Regola File Legacy**:
- File SCSS non importati nel main entry-point rimangono nel filesystem ma sono "orfani"
- Grep ricorrente è obbligatorio per rilevare selettori legacy residue
- **Procedura 9-Step di Rimozione File** (sezione 4.6):
1. Grep Import: verificare non sia importato in main
2. Grep Selector: cercare in file SCSS se selettori sono usati
3. Grep DOM: cercare in HTML/Twig se selettori appaiono
4. Layout Check: verificare layout Gantry non facciano riferimento a classe dal file legacy
5. Compilazione SCSS: `sass --no-source-map scss/bootstrapitalia.scss:custom/css-compiled/`
6. Visual Regression: testare su mobile/desktop/breakpoints
7. Stacking Context: verificare page-surround, top, header, footer, sidebar senza overlay
8. Changelog: registrare rimozione con verifiche completate
9. Commit: con messaggio esplicito "Remove legacy file X - verified zero references"
**Regola Oro**: NON eliminare file senza completare TUTTE le 9 verifiche.
---
### 3.9 SCSS: Versioning Strategico e Gestione Versioni
**Regola 1:1 Data-Versione**:
- Ogni **giorno lavorativo** = una **singola versione** con quella data
- Una data NON può avere più versioni (es: ❌ v1.0.15-beta (05/02) + v1.0.16-beta (05/02))
- **NON incrementare numero versione** per aggiunte minori stesso giorno
**Regola Versioning Particles e Atoms**:
- Versione particle/atom incrementa SOLO con modifiche funzionali/visive
- Formato: `v1.0.X` con X incrementale per ogni release
- Documentare versioni specifiche nel changelog per ogni release
**Regola Gestione Versioni File Legacy**:
- Quando si ripristina versione precedente, file creati nelle versioni successive vengono cancellati
- **Audit pre-ripristino OBBLIGATORIO**: `git diff v1.0.14..HEAD --name-status | grep "^A"`
- Identificare quali file nuovi sono creati e se hanno dipendenze nel codice attuale
- NON ripristinare senza verificare che rendering non si rompa
### 3.9.1 Chiusura Versioni Particelle (Regola Permanente)
Quando una particella mantiene una versione dedicata (es. `v1.0.4`), la chiusura e valida solo se tutte le evidenze sono presenti.
**Evidenze obbligatorie di chiusura**:
1. **Task-to-file mapping**: ogni task chiuso deve avere corrispondenza esplicita in changelog con file reali toccati.
2. **Verifica runtime**: conferma su computed style degli stati interattivi (base, hover, focus, active) per almeno i preset base, verde, rosso, neutro.
3. **Coerenza changelog**: stato release allineato tra indice iniziale e sezione dettagliata (no mismatch tipo "Planned" vs "Completed").
4. **Coerenza metadata particle**: badge/versione nei file YAML coerente con quanto dichiarato in changelog.
5. **Preflight tecnico**: lint/syntax check e integrita pacchetto (manifest) completati.
**Regola minima di commento (sezioni bi-* e particles)**:
- Versioning operativo in **YAML + changelog** (single source of truth).
- Nei file **SCSS** e **Twig** non inserire numeri versione (`vX.Y.Z`, `@version`, date release).
- Consentita solo una nota breve di appartenenza/finalita del file quando utile alla manutenzione.
**Collocazione documentale (file bi-*)**:
- Per override Joomla (`scss/bootstrapitalia-joomla/_bi-user.scss`, `scss/bootstrapitalia-joomla/_bi-finder.scss`) la documentazione resta in `.github/joomla_override_conventions.md`.
- Per sezioni template (`scss/bootstrapitalia/_bi-*.scss`, incluso `_bi-systemmessages.scss`) mantenere nel file solo commenti inline realmente utili; note descrittive e dipendenze vanno documentate in `instruction.md` e nei documenti architetturali `.github`.
**Regola di blocco**:
- Se manca una sola evidenza, la versione NON e chiudibile.
- Gli hardening senza incremento versione vanno tracciati come "post-rilascio" nella release beta corrente.
---
### 3.10 SCSS: Font Management e Typography-Fonts Coherence
**Regola Fonts Dichiarate vs Assets**:
- Ogni font in `_typography.scss` DEVE avere asset corrispondente in `/fonts/` oppure essere da Bootstrap Italia CDN
- Ogni font in `/fonts/` DEVE avere variabile corrispondente in `_typography.scss`
- Nessun font orfano (dichiarato ma non presente), nessuna variabile orfana (asset non presente)
**Font Ufficiali Bootstrap Italia**:
- **Titillium Web** (body, heading, menu) - Path: `/fonts/titillium_web/` (41 file: regular, 300, 600, 700 + italics)
- **Roboto Mono** (monospace) - Path: `/fonts/roboto_mono/` (20 file: regular, 700 + italics)
- **Lora** (serif opzionale) - Path: `/fonts/lora/` (20 file: regular, 700 + italics)
**Audit Font Periodico** (eseguire quando necessario):
1. Leggere `scss/configuration/_typography.scss` → estrarre lista $font-families
2. Per ogni font famiglia, verificare directory in `/fonts/` corrisponda
3. Se dichiarato ma non presente: ERRORE → aggiungere in `/fonts/` oppure rimuovere da _typography.scss
4. Se presente ma non dichiarato: verificare se legacy → aggiungere in _typography.scss oppure rimuovere
---
### 3.11 SCSS: Override Joomla - Centralizzazione e Convenzioni
**REGOLA FONDAMENTALE**: Override Joomla component DEVONO essere centralizzati in **1 file SCSS per componente intero**, non 1 file per view.
**Naming Convention**:
- Pattern: `_bi-[component].scss` (es: `_bi-user.scss`, `_bi-contact.scss`)
- Location: `scss/bootstrapitalia-joomla/` (NON in `scss/bootstrapitalia/`)
**Esempio Architettura com_users**:
```
scss/bootstrapitalia-joomla/
└── _bi-user.scss // File UNICO per TUTTE le view com_users
// Include: login, registration, reset, remind, profile, modules
```
**Non Fare** (antipattern):
```
❌ scss/bootstrapitalia-joomla/_bi-login.scss // 1 file per view
❌ scss/bootstrapitalia-joomla/_bi-registration.scss // Duplicazione
❌ scss/bootstrapitalia-joomla/_bi-reset.scss // Manutenzione frammentata
```
**Struttura File Override Centralizzato**:
```scss
/**
* @file _bi-user.scss
* @package Bootstrap Italia - Joomla Template
* @description Custom styles per com_users (component + modules)
* @version X.Y.Z
*
* Dependencies:
* - Bootstrap Italia v2.17.2+ (classi native)
* - configuration/_core.scss (variabili)
* - configuration/_colors.scss (colori dinamici)
*/
// ============================================================================
// Login Module (mod_login) - Sidebar/Position modules
// ============================================================================
.mod-login { ... }
// ============================================================================
// Component Pages - All Views
// ============================================================================
.com-users-login__form,
.com-users-registration__form,
.com-users-reset__form,
.com-users-remind__form,
.com-users-profile__form {
// Selettori multipli per evitare duplicazione
// Custom effects comuni (lift button, icon animation)
}
```
**Benefici Centralizzazione**:
- ✅ Zero duplicazione codice
- ✅ Coerenza styling tra tutte le view
- ✅ Manutenzione semplificata (1 file da modificare)
- ✅ Effetti custom applicati globalmente
**Separazione Directories SCSS**:
- `scss/bootstrapitalia/` → Sezioni template (header, navigation, footer, system messages)
- `scss/bootstrapitalia-joomla/` → Override componenti Joomla (com_users, com_contact, etc.)
**Riferimento Dettagliato**: Convenzioni complete in `.github/joomla_override_conventions.md`
**PHP Override Approach**: Usare SOLO classi Bootstrap Italia native nel PHP (`.form-control`, `.btn-primary`, `.alert-info`). SCSS custom solo per effetti oltre Bootstrap Italia (hover, transitions, layout specifici).
---
### 3.12 SCSS: Hardcoding - Vietato e Eccezioni Approvate
**Hardcoding VIETATO TOTALMENTE (⛔)**:
- Breakpoint hardcoded: ❌ `@media (max-width: 768px)` → usare variabili `$bp-tablet` o mixin `@include breakpoint(tablet)`
- Z-index hardcoded: ❌ `z-index: 1035` → usare SEMPRE variabili `$z-offcanvas-toggle`
- Colori hardcoded: ❌ `color: #FF0000` → usare variabili da `_colors.scss`
- Spaziature hardcoded: ❌ `margin: 20px` → usare variabili `$spacing-lg` o Bootstrap Italia utilities
**Eccezioni Approvate** (con documentazione):
1. **Utility Classes Menu Colors** (`_bi-navigation.scss`):
- `.menu-color-red { color: #d1344c !important; }` - Pattern intenzionale
- Colori stabili da Bootstrap Italia
- Modifiche estremamente rare
2. **Media Query con Variabili Breakpoint**:
- ✅ Accettabile: `@media (max-width: ($bp-tablet - 1px)) { ... }` - usa variabile
- ✅ Preferibile per nuovo codice: `@include breakpoint(mobile-only) { ... }` - mixin centralizzato
- ❌ MAI: `@media (max-width: 768px)` - valore hardcoded
3. **Z-Index Conflicts**:
- ❌ **ZERO tolleranze** - Nessun valore `z-index: [numero]` ammesso senza variabile
- Rompe gerarchia stacking context globale
---
### 3.13 SCSS: Decision Tree - Configuration vs Hardcoded
**Per ogni nuovo valore, chiediti in ordine**:
| Domanda | SÌ → Azione | NO → Continua |
|---------|-----------|---------------|
| **"Lo uso 3+ volte in file diversi?"** | Centralizza in configuration/mixins | ↓ |
| **"Deve rispondere al tema dinamico (CSS Custom Properties)?"** | Configuration OBBLIGATORIO: `var(--custom, $fallback)` | ↓ |
| **"È spacing/colore/transizione standard del progetto?"** | Usa variabili esistenti: `$spacing-lg`, `$base-text-color` | ↓ |
| **Nessuna condizione sopra è true** | ✅ Hardcoded va bene | — |
**Esempi Pratici** (nuova particella "bi-card"):
```scss
// ✅ SPACING STANDARD → Variabile
padding: $spacing-lg; // Ripetuto in progetto
// ✅ DINAMICO → Configuration
background: var(--bg-card, #fff); // Risponde al tema
// ✅ PATTERN RIPETUTO → Mixin
&:focus {
@include focus-shadow-dynamic; // Focus state standard
}
// ✅ SPECIFICO DEL COMPONENTE → Hardcoded OK
border-radius: 8px; // Solo questo componente
width: 24px; // Dimensione specifica
margin-bottom: 0; // Reset locale
transform: translateY(-2px); // Effetto hover unico
```
**Antipattern** (da evitare):
```scss
// ❌ SBAGLIATO: Centralizzare il non-centralizzabile
$modal-header-height: 60px; // Usato solo in modale-login
$card-icon-size: 24px; // Usato solo in card
// ❌ SBAGLIATO: Overgeneralize
$primary-text-size: 1rem; // Usato ovunque ma con varianti
// Meglio: hardcoded con commenti specifici per ogni uso
```
**Per Implementazioni Future**:
1. Controlla se variabile/mixin esiste già in `configuration/` o `mixins/`
2. Se esiste → Usala
3. Se non esiste → Valuta con checklist sopra
4. Se serve centralizzazione → Crea in configuration/mixins POI applica uniformemente
5. Se hardcoded → Usa liberamente, ma documenta il motivo se non ovvio
### 3.14 SCSS Code Quality & Dead Code Strategy
Questa sezione definisce i principi permanenti per mantenere la qualità del codebase SCSS durante lo sviluppo e le fasi di refactor.
#### 3.14.1 DRY Principle (Don't Repeat Yourself) - SCSS
**Regola Fondamentale**: Variabili e mixins DEVONO essere definiti UNA SOLA VOLTA, mai duplicati.
**Anti-pattern - Duplicazione di Variabili**:
```scss
// ❌ VIETATO: _core.scss
$spacing-xs: 0.25rem;
$spacing-sm: 0.5rem;
$spacing-md: 1rem;
// ... poi identici in _spacing.scss
```
**Pattern Corretto**:
- Definire variabili spacing SOLO in `configuration/_spacing.scss`
- Altre configuration che le usano (`_core.scss`, `_colors.scss`) si riferiscono attraverso import order
**Anti-pattern - Duplicazione di Mixins**:
```scss
// ❌ VIETATO: configuration/_breakpoints.scss
@mixin media-tablet { @media (min-width: $bp-tablet) { @content; } }
// ... poi identico in mixins/_breakpoints.scss
@mixin breakpoint("tablet-up") { @media (min-width: $bp-tablet) { @content; } }
```
**Pattern Corretto**:
- Definire media query mixins SOLO in `mixins/_breakpoints.scss`
- Configuration può contenere variabili breakpoint ma MAI mixins
**Conseguenza di Violazione**: Manutenzione parallela diventa impossibile → se modifichiamo valore in un posto, dimentichiamo l'altro → inconsistenza layout
#### 3.14.2 YAGNI Strategy for Dead Code (You Aren't Going to Need It)
**Principio**: Non aggiungere codice "just in case" durante fase beta. Quando code risulta non usato, decidere fra **Eliminazione** e **Commento** basato su contesto.
**Decisione Tree - Cosa Fare con Dead Code**:
```
Dead code identificato (0 riferimenti)?
│
├─ È duplicazione confermabile?
│ ├─ YES → ELIMINARE
│ │ - Es: spacing vars duplicate in _core.scss vs _spacing.scss
│ │ - Es: media mixins duplicate in configuration/ vs mixins/
│ │ - Reason: Manutenzione parallela impossibile
│ │
│ └─ NO → Potenzialmente utile per refactor futuro?
│ ├─ YES, likely v1.0.1+ → COMMENTARE con flag
│ │ - Format: `// UNUSED v1.0.22-beta - Remove after v1.0 stable if still unused`
│ │ - Es: effect mixins (hover-scale, focus-ring) per animazioni future
│ │ - Es: file interi (_nav.scss, _section-styles.scss) per refactor menu/sezioni
│ │ - Reason: Reversibile, preserva architectural pattern per riconsiderazione
│ │
│ └─ NO, pattern unlikely to repeat → ELIMINARE
│ - Es: breakpoint selector "desktop" (duplicate "desktop-up")
│ - Es: dimension var $_grid-min-height non usato mai
│ - Reason: Clutter del codebase, confonde intent
```
**Fase Beta Caveat**: Durante fase beta (< v1.0 stable), preferire **COMMENTO** per codice non ovviamente eliminabile. Dopo v1.0 stable, eliminare definitivamente se mai usato.
**Tracciamento**: Comentato code deve includere numero versione: `// UNUSED v1.0.22-beta - ...` per facile ricerca futura.
#### 3.14.3 Foundation Layer Import Order - Dipendenze Critiche
**Regola Assoluta**: File configuration che **USANO variabili** devono essere importati DOPO i file che le **DEFINISCONO**.
**Critical Pattern**:
```scss
// ❌ SBAGLIATO ORDINE
@import "core"; // Usa $spacing-lg
@import "spacing"; // Definisce $spacing-lg
// ERRORE SCSS: Undefined variable $spacing-lg
```
**Pattern Corretto**:
```scss
// ✅ GIUSTO ORDINE
@import "spacing"; // Definisce $spacing-lg
@import "core"; // Usa $spacing-lg (ora disponibile)
```
**Mapping Dipendenze** (configuration/_base.scss):
```
breakpoints ─→ Nessuna dipendenza (usato da tutti)
colors ─→ Nessuna dipendenza
spacing ─→ DEVE venire PRIMA di core, dimensions
core ─→ Usa spacing-*, border-color, etc
dimensions ─→ Usa spacing-* per padding/margin
nav, typography ─→ Nessuna dipendenza
z-index ─→ Nessuna dipendenza
```
**Verificazione**: Compilare con `sass configuration/_base.scss /tmp/test.css` — se non compila, c'è dipendenza non risolta.
#### 3.14.4 Breakpoints & Mixins - No Duplication Rule
**Regola**: Breakpoint **variabili** (es: `$bp-tablet: 768px`) POSSONO essere in configuration/. Breakpoint **mixins** (es: `@mixin media-tablet`) DEVONO STARE SOLO in mixins/.
**Ragione**:
- Variabili breakpoint servono a definition (usate in componenti custom)
- Mixins breakpoint servono a abstraction (media query riutilizzabile)
- Duplicate mixin = una modificata, l'altra no = inconsistenza
**Pattern Vietato**:
```scss
// ❌ configuration/_breakpoints.scss
@mixin media-tablet { @media (min-width: $bp-tablet) { @content; } }
// ❌ mixins/_breakpoints.scss
@mixin breakpoint("tablet-up") { @media (min-width: $bp-tablet) { @content; } }
// Stessa funzionalità, due versioni → MANUTENZIONE DISASTRO
```
**Pattern Approvato**:
```scss
// ✅ configuration/_breakpoints.scss (SOLO variabili)
$bp-tablet: 768px;
// ✅ mixins/_breakpoints.scss (SOLO mixins)
@mixin breakpoint($selector) {
@if $selector == "tablet-up" {
@media (min-width: $bp-tablet) { @content; }
}
}
```
#### 3.14.5 Dead Code Audit Procedure
Quando identificare dead code:
1. **Grep Search**: `grep -r "mixin-name\|variable-name" scss/bootstrapitalia/` — verificare 0 riferimenti
2. **Check Imports**: Verificare che file non sia @imported in `scss/bootstrapitalia.scss` o `scss/bootstrapitalia-joomla.scss`
3. **Check HTML/Twig**: `grep -r "class-name\|id-name" html/ particles/` — verificare nessun uso nel markup
4. **Duplicate Detection**: Se variabile/mixin simile esiste altrove, è duplicazione confermata
5. **Future Likelihood Assessment**: Valutare se pattern tornerebbe utile (es: navigation refactor, effect mixins per accessibility)
6. **Decision**: Eliminare duplicazioni, commentare potenziali future-use durante beta
**Output Checklist**:
- [ ] Grep search completato
- [ ] Zero riferimenti confermati
- [ ] Non importato confermato
- [ ] Duplicazione valutata
- [ ] Decisione documentata
- [ ] Se commentato: flag versione aggiunto
- [ ] Se eliminato: SCSS compilato senza errori
---
## 4. Criticità e Lezioni Apprese
### 4.1 Avvertenze Importanti
#### Versione Template Base
⚠️ **Hydrogen v5.5.25** (o successiva)
- Il template è basato su Hydrogen
- Template clonati da versioni precedenti ereditano il manifest della versione origin
- Il manifest clonato DEVE essere aggiornato manualmente quando template base viene aggiornato
- Consultare le lezioni apprese per la procedura di aggiornamento
#### Architettura CSS per Atoms Gantry
⚠️ **IMPORTANTE**: Gantry 5 **NON supporta import SCSS personalizzati** per gli Atoms
- ❌ **Approccio non funzionante**: Creare file SCSS in cartelle personalizzate e importarli nel file principale
- ✅ **Approccio corretto**: Utilizzare CSS inline nel blocco `{% block stylesheets %}` dei template Twig
- Gli Atoms Gantry sono progettati per funzionare con CSS inline incorporato direttamente nei file `.html.twig`
- Il sistema di compilazione SCSS di Gantry non elabora import personalizzati per atoms (solo per particles)
- Tentativi di import personalizzati possono corrompere la compilazione CSS e compromettere il frontend
### 4.2 Criticità Riscontrate e Workaround
- **Gestione Colori Preset**: Le particelle utilizzano le variabili SCSS di Gantry (`$base-text-color`, `$accent-color-1`, `$accent-color-2`) invece di CSS Custom Properties, garantendo compatibilità con tutti i preset definiti in `presets.yaml`. I colori si aggiornano automaticamente alla compilazione SCSS quando si cambia preset.
- **Backdrop Modale Ricerca**: Lo stile del backdrop (`.bi-modal-search-open .modal-backdrop`) è stato spostato dall'inline del Twig al file SCSS `_bootstrapitalia-modale-ricerca.scss` per rispettare l'architettura di compilazione SCSS di Gantry. Questa centralizzazione garantisce coerenza e manutenibilità.
- **Cache Gantry/Joomla**: Attenzione alle cache che possono impedire la visualizzazione immediata delle modifiche agli stili. Pulire sempre la cache dopo modifiche SCSS o cambio preset.
- **Compilazione SCSS**: Dopo ogni modifica ai file SCSS o cambio preset, è necessario ricompilare gli stili da Gantry Admin → Styles → Compile CSS per applicare le modifiche.
### 4.3 Gestione Versioni e File Legacy
**Problema Critico Identificato** (06/02/2026):
Quando si ripristina una versione precedente del template (es: v1.0.14) dopo aver lavorato su versioni successive (v1.0.15, v1.0.16), i **file creati nelle versioni più recenti vengono cancellati**, ma i **riferimenti a questi file rimangono** nel codice, causando errori di compilazione.
**Caso Specifico Rilevato**:
- **File mancante**: `scss/mixins/_breakpoints.scss` (creato in v1.0.15 con 79 righe)
- **Riferimento orfano**: `@include breakpoint(mobile-only)` in `scss/bootstrapitalia/_bi-top.scss` (riga 220)
- **Errore risultante**: Compilazione SCSS fallisce per mixin non definito
**Root Cause**:
1. Versione v1.0.15 creava `_breakpoints.scss` per centralizzare mixin responsive
2. Ripristino a v1.0.14 elimina quel file (non esisteva ancora in quella versione)
3. File che usavano `@include breakpoint()` rimangono con riferimenti "morti"
4. Sistema non rileva automaticamente queste dipendenze rotte
#### Strategia di Prevenzione
**1. Audit Pre-Ripristino Obbligatorio**
Prima di ripristinare una versione precedente, eseguire:
```bash
# 1. Identificare file creati nelle versioni successive
git diff v1.0.14..HEAD --name-status | grep "^A"
# 2. Per ogni file identificato, cercare riferimenti nel codice
grep -rn "nome-file-senza-estensione" scss/
# 3. Documentare dipendenze trovate
```
**Output atteso**:
```
A scss/mixins/_breakpoints.scss → Creato in v1.0.15
Riferimenti: _bi-top.scss (riga 220), _bi-menu.scss, etc.
```
**2. Strategia Backward Compatibility**
**Opzione A - Mantenere File Critici** (raccomandato):
- File come `_breakpoints.scss` che forniscono mixin base **NON devono essere eliminati** anche in rollback
- Copiare file critici in versione v1.0.14 prima di procedere
- Documentarli come "dipendenze trasversali" in `docs/DEPENDENCIES.md`
**Opzione B - Refactoring Completo**:
- Sostituire `@include breakpoint()` con pattern v1.0.14 conforme: `@media (max-width: ($bp-tablet - 1px))`
- Evitare dipendenza da mixin creati in versioni successive
- Più laborioso ma garantisce compatibilità
**Opzione C - Gestione Incrementale**:
- Creare `scss/mixins/_fallbacks.scss` con stub/polyfill per mixin mancanti
- Import condizionale: file esiste → usa quello, altrimenti → usa fallback
**3. Workflow Raccomandato per Rollback Sicuro**
```bash
# 1. Audit dipendenze
git diff v1.0.14..HEAD --name-status | grep "^A" | awk '{print $2}' > new_files.txt
# 2. Per ogni file nuovo, cerca riferimenti
while read file; do
basename=$(basename "$file" .scss | sed 's/^_//')
echo "=== Checking $basename ==="
grep -rn "$basename" scss/ --include="*.scss"
done < new_files.txt
# 3. Se trovati riferimenti, decidere:
# a) Portare file in v1.0.14, OPPURE
# b) Refactorare codice per non usarlo
# 4. Solo dopo verifica, procedere con ripristino
git checkout v1.0.14
```
**Regola Aurea**: **Mai ripristinare versione precedente senza audit dipendenze**. File cancellati = potenziali errori di compilazione silenziosi fino al deploy.
### 4.4 Principi di Architettura SCSS
1. **Toggle Positioning Requirement**: Offcanvas toggle DEVE essere `position: absolute` o `position: fixed`, mai `position: relative`. Utilizzo di `position: relative` fa sì che l'elemento occupi spazio nel flusso di layout, generando bande/offset indesiderati sopra/intorno a sezioni adiacenti.
2. **Z-Index Centralization Mandate**: Tutti i valori `z-index` DEVONO provenire da `_z-index.scss` centralizzato. Anche un singolo valore hardcoded può rompere la gerarchia globale di stacking context. Nessun file bi-* DEVE contenere `z-index: [numero]` diretto.
3. **Breakpoint Mixin Requirement**: Tutti i media query DEVONO utilizzare mixins `@include breakpoint()` da `_breakpoints.scss`, mai `@media (` diretto. Ciò consente manutenzione centralizzata e previene duplicazione di valori breakpoint.
4. **Legacy File Management**: File SCSS non importati nel main entry-point rimangono nel filesystem e possono contenere selettori non utilizzati. Grep ricorrente è obbligatorio per rilevare riferimenti legacy residue prima di eliminazione file.
5. **Typography-Fonts Coherence**: Variabili font in `_typography.scss` DEVONO corrispondere ai font effettivamente presenti in `/fonts/` e conformi a Bootstrap Italia. Pattern: Titillium Web (body/heading/menu), Roboto Mono (monospace), Lora (serif). Ogni font dichiarato DEVE avere @font-face corrispondente o essere presente in /fonts/. Nessuna variabile orfana per font non disponibili.
6. **Stacking Context Isolation Prevention**: `#g-page-surround` è il contenitore radice per stacking context Gantry. Elementi con `position: relative` + `z-index` all'interno creano nuovo stacking context locale che isola l'elemento. Toggle, modal, dropdown DEVONO mantenere stacking context globale.
### 4.5 Eccezioni Hardcoded Approvate
Alcune situazioni giustificano l'uso di valori hardcoded per motivi di pragmatismo e manutenibilità. Queste eccezioni sono **documentate e approvate** esplicitamente:
#### Utility Classes Menu Colors
**File**: `scss/bootstrapitalia/_bi-navigation.scss` (righe 67-79)
**Contesto**: Classi utility `.menu-color-red`, `.menu-color-purple`, `.menu-color-green`, `.menu-color-blue` per colorazione voci menu tramite markup Joomla.
**Giustificazione**:
- Colori intenzionali per uso deliberato in interfaccia utente amministratore
- Modifiche estremamente rare (stabili da Bootstrap Italia)
- Refactor richiederebbe 4+ variabili configuration per utility classes raramente cambiate
- Pattern comune in framework UI (utility-first approach)
**Pattern approvato**:
```scss
.menu-color-red {
color: #d1344c !important; // Approvato: utility class intenzionale
}
```
**Regola**: Se nuove utility colors necessarie, valutare se aggiungere a configuration/_colors.scss o mantenere hardcoded in base a frequenza modifiche prevista.
#### Media Query con Variabili Breakpoint
**Pattern rilevato**: `@media (max-width: ($bp-tablet - 1px))` invece di `@include breakpoint(mobile-only)`
**Contesto**: Pattern diffuso in file legacy che usa variabili breakpoint ma non mixin.
**Giustificazione**:
- Pattern **accettabile** perché usa variabile `$bp-tablet` da configuration/_breakpoints.scss
- Non rompe centralizzazione (nessun valore hardcoded tipo `768px` diretto)
- Logica `($bp-tablet - 1px)` può essere intenzionale per edge case specifici
- Mixin `@include breakpoint()` potrebbe non coprire questo caso esatto
**Pattern approvato**:
```scss
@media (max-width: ($bp-tablet - 1px)) { // Accettabile: usa variabile
// Mobile styling
}
```
**Pattern preferito** (per nuovo codice):
```scss
@include breakpoint(mobile-only) { // Preferibile: mixin centralizzato
// Mobile styling
}
```
**Regola**:
- File esistenti: pattern `@media (max-width: ($bp-variable - 1px))` **accettabile**, non richiede refactor immediato
- Nuovo codice: preferire `@include breakpoint()` per coerenza
- **MAI** usare valori hardcoded tipo `@media (max-width: 768px)` senza variabile
#### Z-Index Conflicts - **NON AMMESSI**
**Anti-pattern rilevato e corretto**: `z-index: 2;` in `_bi-header.scss` (v1.0.16-beta)
**Motivo correzione**:
- Rompe gerarchia stacking context (`$z-header: 1000` definito in _z-index.scss)
- Header finisce sotto navigation (z: 1002) e top (z: 1003)
- Bug architetturale critico
**Regola ferrea**: Nessun valore `z-index: [numero]` hardcoded ammesso. **ZERO eccezioni**. Usare sempre variabili da `_z-index.scss`.
### 4.6 Gestione File Legacy
**Procedure di Rimozione File** (OBBLIGATORIO seguire IN SEQUENZA):
1. **Step 1 - Grep Import**: Verificare che file non sia importato in `scss/bootstrapitalia.scss`
2. **Step 2 - Grep Selector**: Cercare in TUTTI i file SCSS se selettori dal file legacy sono ancora usati
3. **Step 3 - Grep DOM**: Cercare in HTML/Twig se selettori dal file legacy appaiono
4. **Step 4 - Layout Check**: Verificare che layout Gantry (layouts/*.yaml) e particles non facciano riferimento a classe o ID dal file legacy
5. **Step 5 - Compilazione SCSS**: Lanciare `sass --no-source-map scss/bootstrapitalia.scss:custom/css-compiled/` per verificare compilazione senza errori
6. **Step 6 - Visual Regression**: Testare frontend su mobile/desktop/breakpoint principali per verificare assenza di rotture layout
7. **Step 7 - Stacking Context**: Verificare page-surround, top, header, footer, sidebar senza overlay indesiderati o nuove fasce
8. **Step 8 - Changelog**: Registrare rimozione in CHANGELOG con lista file rimossi e verifiche completate
9. **Step 9 - Commit**: Committare con messaggio esplicito: "Remove legacy file X - verified zero references"
**Regola Oro**: NON eliminare file senza completare TUTTE le 9 verifiche. File legacy può contenere effetti collaterali invisibili.
### 4.7 Verifiche Obbligatorie di Stacking Context e Regressione Layout
**CRITICAL - DEVONO essere eseguite PRIMA di modificare qualsiasi file sezione A2**:
**Stacking Context Verification**:
1. `#g-page-surround`: DEVE essere z-index base layer (z-index: auto o 1000)
2. `#g-top`: DEVE avere z-index ≥ 1003 (da $z-top)
3. `#g-header`: DEVE avere z-index ≥ 1000 (da $z-header)
4. `#g-navigation`: DEVE avere z-index ≥ 1002 (da $z-navigation)
5. `.g-offcanvas-toggle`: DEVE avere z-index: 1035 (da $z-offcanvas-toggle), posizionato absolute/fixed
6. Nessun overlay indesiderato tra sezioni
7. Nessuna fascia margin/padding derivata da overflow o z-index conflitto
**Responsive Breakpoint Test** (obbligatorio su 3 risoluzioni):
- Mobile Small (480px)
- Tablet (768px)
- Desktop (1200px)
**Layout Default vs Custom Alignment**:
- Confrontare `layouts/default.yaml` vs `custom/config/*/layouts/`
- Verificare coerenza page-surround, top, header, sidebar, mainbody, footer
- Controllare che z-index non conflitti tra layout diversi
**Regressione Visual Checklist**:
- Toggle offcanvas presente, visibile, dimensioni ≥ 44x44px
- Nessuna fascia/band sopra #g-top
- Header non copre contenuto top
- Navigation non copre header
- Sidebar non copre mainbody su mobile
- Footer visible, non coperto
- Modali hanno backdrop coerente
- Tutti i controlli accessibili (non nascosti)
### 4.8 Gantry Install Templates - Pattern e Criticità
#### Context Isolato Install/Update
⚠️ **IMPORTANTE**: I template install/update di Gantry (`install/templates/*.html.twig`) vengono renderizzati in un **contesto isolato** prima del bootstrap completo di Joomla.
**Limitazioni Tecniche**:
- Filtri Twig translation (`|t`, `|trans`) **NON disponibili**
- Sistema lingua Joomla potenzialmente **non completamente inizializzato**
- `ThemeInstaller->render()` **non carica automaticamente** lingua nel contesto Twig
#### Pattern Obbligatorio: Caricamento Lingua PHP
**❌ APPROCCIO NON FUNZIONANTE**:
```twig
{# install/templates/update.html.twig #}
{{'TPL_CONST_TITLE'|t}}
```
**✅ APPROCCIO CORRETTO**:
```php
// install.php - metodo postflight()
$lang = Factory::getLanguage();
$lang->load('tpl_bootstrapitalia', JPATH_SITE . '/templates/bootstrapitalia');
$translations = array(
'install_title' => Text::_('TPL_BOOTSTRAPITALIA_INSTALL_TITLE'),
'install_desc' => Text::_('TPL_BOOTSTRAPITALIA_INSTALL_DESC'),
// ... altre traduzioni
);
echo $installer->render('install.html.twig', $translations);
```
```twig
{# install/templates/install.html.twig #}
{{ install_title }}
```
**Pattern Architetturale**:
1. Caricamento esplicito file lingua in PHP con `Factory::getLanguage()->load()`
2. Traduzione stringhe con `Text::_()` in PHP
3. Creazione array associativo `$translations`
4. Passaggio array come secondo parametro a `render()`
5. Interpolazione diretta variabili in Twig `{{ var }}`
#### Hardcoding Valori Critici in Install Phase
**Regola**: Informazioni critiche che **devono sempre essere visualizzate** (crediti autore, URL, licensing) vanno hardcoded direttamente in PHP, non caricate da lingua.
**Razionale**:
- Sistema lingua potrebbe essere parzialmente inizializzato
- Fallback garantito anche se traduzione fallisce
- Informazioni invarianti tra lingue (nome autore non cambia)
**Esempio Approvato**:
```php
$translations = array(
'install_title' => Text::_('TPL_CONST_TITLE'), // OK: tradotto
'powered_by_author' => 'Claudio Rosselli', // OK: hardcoded
'powered_by_url' => 'https://iamawebmaster.com' // OK: hardcoded
);
```
#### Eccezione !important per Contrasto Cross-Theme
**Contesto**: Install templates devono garantire contrasto WCAG AA in **qualsiasi** tema (light/dark).
**Problema**: CSS specificity - stili tema backend possono sovrascrivere inline CSS install templates.
**Soluzione Approvata**: Uso di `!important` per forzare colori critici contrasto.
**Pattern Approvato**:
```css
/* install/templates/style.html.twig */
.btn-light {
background: white;
color: #0066cc !important; /* Approvato: garantisce contrasto cross-theme */
border: 1px solid white;
}
.btn-outline-light {
background: rgba(255,255,255,0.1);
color: white !important; /* Approvato: visibilità su sfondo scuro */
text-shadow: 0 1px 2px rgba(0,0,0,0.2);
}
```
**Regola**: `!important` su colori text/background è **ammesso SOLO** in contesto install templates per garantire accessibilità. In tutto il resto del template rimane **vietato** (usare CSS Custom Properties).
**Validazione Obbligatoria**: Ogni uso di `!important` deve essere testato in light mode E dark mode per verificare contrasto WCAG AA (4.5:1 per testo normale, 3:1 per large text).
**Riferimento Changelog**: Vedere v1.1.0-beta Fase 2 (18/02/2026) per contesto completo implementazione e risoluzione bug critici.
### 4.9 Audit Font
**Procedure Audit Font Standard** (eseguire periodicamente):
1. Leggere `scss/configuration/_typography.scss` → estrapolare lista $font-families
2. Per ogni font famiglia, verificare directory in `/fonts/` corrisponda: `/fonts/[font-name]/` DEVE contenere file .woff/.woff2/.ttf
3. Se font dichiarato ma non presente:ERRORE → aggiungere font in `/fonts/` oppure rimuovere da _typography.scss
4. Se font presente ma non dichiarato: Verificare se legacy → aggiungere a _typography.scss oppure rimuovere directory `/fonts/[font-name]/`
5. Dopo audit, documentare risultato in CHANGELOG
**Regola**: Ogni font in `/fonts/` DEVE corrispondere a variabile in `_typography.scss`. Inversamente, ogni variabile font (eccetto fallback) DEVE avere asset corrispondente in `/fonts/` o essere caricato da Bootstrap Italia CDN. Niente font orfani o variabili senza asset. Font ufficiali Bootstrap Italia: **Titillium Web** (body, heading, menu), **Roboto Mono** (monospace), **Lora** (serif opzionale).
---
## 5. Design System e Standard
### 5.1 Linee Guida e Conformità
1. **Designers Italia**: Implementare i pattern e i componenti del **Design System**.
2. **Linee Guida AGID**: Rispettare le direttive per i servizi digitali della PA.
3. **Accessibilità (WCAG 2.1 AA)**:
- Utilizzare codice semanticamente corretto.
- Integrare attributi **ARIA** dove necessario.
4. **Responsività**:
- Adottare un approccio **mobile-first**.
- Usare il sistema di griglie di Bootstrap.
### 5.2 Principi di Coerenza con Bootstrap Italia
- Tutte le particelle sono sviluppate usando le classi native di Bootstrap Italia (it-*) per garantire coerenza visiva e funzionale.
- Il markup Twig delle particelle riprende la struttura ufficiale dei componenti Bootstrap Italia, adattando solo la logica dinamica Gantry (multilingua, configurazioni YAML).
- Gli stili SCSS personalizzati sono ridotti al minimo e usati solo per override o layout specifici non gestiti dal framework.
- La responsività e l'accessibilità sono sempre garantite tramite le utility e i breakpoint Bootstrap Italia.
- Ogni nuova particella o modifica deve seguire queste regole per mantenere la massima compatibilità e aggiornabilità futura.
---
## 6. Sistema SCSS e Architettura
### 6.1 SCSS Files Mapping e Dipendenze
**Configuration Layer (C3 - Centralizzazione)**:
```
scss/configuration/
├── _z-index.scss → Gerarchia stacking context centralizzata
├── _breakpoints.scss → Breakpoint mixins (@include breakpoint(tablet), etc.)
├── _colors.scss → Colori presets per tutti i preset Gantry
├── _typography.scss → Font families dichiarate
└── _core.scss → Spacing, utilities base
```
**Mixins Layer (A1 - Patterns Condivisi)**:
```
scss/mixins/
├── _effects.scss → Transizioni smooth-transition(), shadow effects
├── _dynamic-states.scss → Stati interattivi dinamici (focus-shadow-dynamic())
├── _section-styles.scss → Pattern layout sezioni (grid, flex utilities)
├── _nav.scss → Pattern navigazione (dropdown, menu items)
└── _[custom].scss → Pattern riutilizzabili per multiple sezioni
```
**Sezioni Layer (A2 - Prioritarie)**:
```
scss/bootstrapitalia/
├── _bi-top.scss → Sezione top
├── _bi-header.scss → Header logo, navbar
├── _bi-navigation.scss → Navigation bar
├── _bi-offcanvas.scss → Offcanvas sidebar + toggle
├── _bi-offcanvas-toggle.scss → Particle-specific offcanvas
├── _bi-menu.scss → Menu items styling
├── _bi-drawer.scss → Drawer sezione
└── [other sections].scss → Sezioni secondarie
```
### 6.2 Import Order (OBBLIGATORIO)
**File**: `scss/bootstrapitalia.scss`
```scss
// 1. Configuration (FIRST)
@import "configuration/z-index";
@import "configuration/breakpoints";
@import "configuration/colors";
@import "configuration/typography";
@import "configuration/core";
// 2. Mixins (SECOND)
@import "mixins/effects";
@import "mixins/section-styles";
@import "mixins/nav";
// 3. Sezioni (THIRD)
@import "bootstrapitalia/bi-top";
@import "bootstrapitalia/bi-header";
@import "bootstrapitalia/bi-navigation";
@import "bootstrapitalia/bi-offcanvas";
@import "bootstrapitalia/bi-offcanvas-toggle";
@import "bootstrapitalia/bi-menu";
// ... altre sezioni
```
**Dependencies Verification** (OBBLIGATORIA):
- Nessun @import in sezione bi-* DEVE puntare FORWARD a altra sezione non ancora importata
- Ogni sezione bi-* DEVE importare SOLO da configuration/ e mixins/ (layers precedenti)
- Cross-sezione reference è VIETATA
### 6.3 Metadata Pattern Standardizzati (Obbligatorio)
**Tutti i file SCSS nei layer C3 (Foundation) e Utility (Mixins) DEVONO avere metadata headers standardizzati.**
#### Pattern Obbligatorio
```scss
/**
* @package Gantry 5 Theme - Bootstrap Italia
* @author Claudio Rosselli https://iamawebmaster.com
* @currentDeveloper Claudio Rosselli
* @copyright Copyright (C) 2026 iamawebmaster.com All rights reserved.
* @license GNU/GPLv2 and later
*
* [Layer Name] - [Module Type]
* [Descriptive details specific to module]
* https://italia.github.io/bootstrap-italia/
*/
```
**Esempi Layer**:
- C3 Foundation: `Foundation Layer Configuration Base` (orchestrator), `Foundation Layer - AGID Color Palette`, `Foundation Layer - Typography System`
- Utility Mixins: `Utility Layer Mixins Base` (orchestrator), `Utility Layer - Responsive Breakpoint Mixins`, `Utility Layer - Effects & Interaction Mixins`
#### Tag @-Descriptions
| Tag | Significato | Valore | Mutabile? |
|-----|-------------|--------|-----------|
| `@package` | Nome progetto template | `Gantry 5 Theme - Bootstrap Italia` | ❌ No (identità template) |
| `@author` | Creatore originale | `Claudio Rosselli https://iamawebmaster.com` | ❌ No (credito permanente) |
| `@currentDeveloper` | Maintainer attuale | `Claudio Rosselli` | ⚠️ Aggiornare se cambia maintainer |
| `@copyright` | Copyright holder + anno | `Copyright (C) 2026 iamawebmaster.com All rights reserved.` | ⚠️ Aggiornare solo anno |
| `@license` | Licenza software | `GNU/GPLv2 and later` | ❌ No (legale binding) |
**⚠️ IMPORTANTE - Single Source of Truth per Versioni**:
- ❌ **NON includere** `@version` nei file SCSS individuali
- ✅ **Versione unica** in `templateDetails.xml` (riga 3: `1.0.22-beta`)
- **Rationale**: DRY principle, eliminare 14+ punti di sincronizzazione manuale, ridurre rischio versioni incongruenti
**Benefici Metadata**:
- Tracciabilità codice e autorship permanente
- Licensing chiara (GPL v2+) per distribuzione
- IDE hover documentation automatica
- Deprecation management semplificato
- Audit trail completo per file modificati
#### File Coperti (14 totali)
**Configuration Layer (8 file)**:
- `scss/configuration/_base.scss` (orchestrator)
- `scss/configuration/_colors.scss`
- `scss/configuration/_typography.scss`
- `scss/configuration/_spacing.scss`
- `scss/configuration/_breakpoints.scss`
- `scss/configuration/_z-index.scss`
- `scss/configuration/_dimensions.scss`
- `scss/configuration/_nav.scss`
**Mixins Layer (6 file)**:
- `scss/mixins/_base.scss` (orchestrator)
- `scss/mixins/_breakpoints.scss`
- `scss/mixins/_effects.scss`
- `scss/mixins/_dynamic-states.scss`
- `scss/mixins/_nav.scss`
- `scss/mixins/_section-styles.scss`
**Applicazione Futura**: Quando si crea un nuovo file configuration o mixin, copiare esattamente il pattern metadata sopra e adattare solo la descrizione layer-specifica.
### 6.4 Organizzazione Import bootstrapitalia.scss (Sezioni Logiche)
**Il file `scss/bootstrapitalia.scss` DEVE organizzare i 59 import A2 adapter layer in sezioni logiche chiaramente delimitate.**
#### Struttura Obbligatoria
```scss
// ============================================
// REQUIRED DEPENDENCIES - DO NOT CHANGE
// ============================================
@import "dependencies";
// ============================================
// C3 FOUNDATION LAYER (Design Tokens)
// ============================================
@import "configuration/base";
// ============================================
// A1 HYDROGEN CORE THEME (Read-Only)
// ============================================
@import "nucleus/theme/base";
// ============================================
// A2 ADAPTER LAYER - CORE COMPONENTS
// ============================================
// Base component styles: core reset, typography, navigation, utilities
@import "bootstrapitalia/core";
@import "bootstrapitalia/typography";
@import "bootstrapitalia/utility";
@import "bootstrapitalia/bi-navigation";
@import "bootstrapitalia/mainnav";
@import "bootstrapitalia/bi-menu";
@import "bootstrapitalia/bi-header";
@import "bootstrapitalia/bi-top";
@import "bootstrapitalia/bi-breadcrumb";
@import "bootstrapitalia/drawer";
@import "bootstrapitalia/bi-offcanvas";
@import "bootstrapitalia/bi-offcanvas-toggle";
@import "bootstrapitalia/bi-systemmessages";
@import "bootstrapitalia/bi-footer";
@import "bootstrapitalia/bi-copyright";
@import "bootstrapitalia/to-top";
// ============================================
// A2 ADAPTER LAYER - LAYOUT SECTIONS
// ============================================
// Page region styles: layout sectioning and composition
@import "bootstrapitalia/fullwidth";
@import "bootstrapitalia/showcase";
@import "bootstrapitalia/intro";
@import "bootstrapitalia/feature";
@import "bootstrapitalia/subfeature";
@import "bootstrapitalia/maintop";
@import "bootstrapitalia/mainbody";
@import "bootstrapitalia/sidebar";
@import "bootstrapitalia/aside";
@import "bootstrapitalia/mainbottom";
@import "bootstrapitalia/extension";
@import "bootstrapitalia/additional";
@import "bootstrapitalia/prebottom";
@import "bootstrapitalia/bottom";
@import "bootstrapitalia/afterbottom";
@import "bootstrapitalia/last";
// ============================================
// A2 ADAPTER LAYER - CONTENT & PAGE STYLES
// ============================================
// Content styling: forms, tables, variations, errors
@import "bootstrapitalia/forms";
@import "bootstrapitalia/tables";
@import "bootstrapitalia/variations";
@import "bootstrapitalia/error";
@import "bootstrapitalia/dropdownanimations";
@import "bootstrapitalia/contentarray";
// ============================================
// A2 ADAPTER LAYER - CUSTOM PARTICLES
// ============================================
// Bootstrap Italia custom Gantry particles
@import "bootstrapitalia/bootstrapitalia-logo";
@import "bootstrapitalia/bootstrapitalia-icone-link";
@import "bootstrapitalia/bootstrapitalia-modale-ricerca";
@import "bootstrapitalia/bootstrapitalia-modale-login";
@import "bootstrapitalia/bootstrapitalia-preset-switcher";
// ============================================
// A1 HYDROGEN CORE - BREAKPOINTS
// ============================================
@import "nucleus/theme/breakpoints/base";
```
#### Benefici Organizzazione
**Navigabilità**: Developer capisce immediately A1 (Hydrogen read-only) vs A2 (Bootstrap Italia customizations)
**Manutenibilità**: Aggiungere nuovo file? Chiara section dove inserirlo (core component, layout section, content style, particle)
**Audit**: Verifica completezza import per categoria logica semplificata
**IDE**: Fold/unfold sezioni per focus mirato
**Semantica**: Riflette cleanly il layer model architetturale (A1=Hydrogen, A2=Adapter, C3=Foundation external)
**⚠️ NOTA**: Ogni import NON deve mai puntare a file che non esistono (es: particle-overrides eliminato). Verificare sempre con grep prima di aggiungere import.
---
## 7. Governance Operativa (A1/A2/C3)
### 7.1 Priorità Operative
- **A1 (Architettura Fondamentale)**: Mixins e patterns condivisi (effects, section-styles, nav, transitions, breakpoint-mixins) DEVONO essere unici e riutilizzati. File: `scss/mixins/`, `scss/configuration/`. Regola: un mixin = una definizione centralizzata, tutte le sezioni lo includono.
- **A2 (Sezioni Gantry Prioritarie)**: Top, Header, Navigation, Offcanvas, Page-Surround DEVONO usare SOLO file bi-*. Regola: zero file legacy duplicati per queste sezioni. Stacking context DEVE essere verificato: z-index centralizzato, niente overlay indesiderati.
- **C3 (Configurazione Centralizzata)**: Hardcoding DEVE essere eliminato e sostituito con variabili centralizzate: `_z-index.scss`, `_breakpoints.scss`, `_colors.scss`, `_typography.scss`, `_core.scss`. Regola: qualsiasi valore hardcoded in sezione va spostato in configuration/ e variabile deve essere riutilizzata.
- **Ogni intervento DEVE dichiarare quali blocchi A1/A2/C3 sono stati modificati.** Esempio: "Toccati A1 (mixins effects), A2 (offcanvas toggle), C3 (z-index centralizzazione)".
### 7.2 Hardcoding Bootstrap Italia (Obbligo)
**Vietato Totalmente (⛔)**:
- Breakpoint hardcoded (es: `@media (max-width: 768px)`): usare SOLO mixins da `scss/configuration/_breakpoints.scss` (@include breakpoint(tablet), @include breakpoint(mobile-only))
- Z-index hardcoded (es: `z-index: 1035`): usare SOLO variabili da `scss/configuration/_z-index.scss`
- Colori hardcoded (es: `color: #FF0000`): usare SOLO variabili da `scss/configuration/_colors.scss`
- Spaziature hardcoded (es: `margin: 20px`): usare SOLO variabili da `scss/configuration/_core.scss` o variabili Bootstrap Italia standard
**Procedure di Audit Ricorrente**:
1. Cercare pattern `@media (` nei file bi-* → sostituire con @include breakpoint()
2. Cercare pattern `z-index: [0-9]+` → verificare se da _z-index.scss o hardcoded
3. Cercare pattern `color: #[0-9A-F]`, `background: #[0-9A-F]` → verificare fonte (deve essere variabile)
4. Cercare pattern `(margin|padding): [0-9]+px` → verificare se variabili spacing
### 7.3 Atoms: Architettura e Patterns
#### Pattern Architetturale: Single Source of Truth
**IMPORTANTE**: La versione di Bootstrap Italia deve essere gestita **centralmente** nell'**Atom CDN**. Questo previene conflitti di versioning distribuito e garantisce coerenza globale.
#### Regole di Versioning per Atoms
**Solo negli Atoms (CDN e Icons):**
- `version`: campo parametrico che consente di specificare la versione di Bootstrap Italia (default: 2.17.2)
- `css_url`: URL personalizzato per risorse CSS (opzionale, fallback alla URL costruita dinamicamente)
- **Scopo**: Atoms gestiscono le dipendenze globali e devono supportare versioning flessibile
- **Ereditarietà**: Atom Icons legge automaticamente la versione dall'Atom CDN via `gantry.config.get()`
#### Procedura di Aggiornamento Versione
1. Accedi al **backend Gantry** → Layout Manager
2. Seleziona **Atom CDN**
3. Modifica il campo **Version** (es: `2.16.1` → `2.17.2`)
4. Salva le modifiche
5. Pulisci la cache di **Gantry** e **Joomla**
6. La nuova versione è applicata **globalmente** a tutto il template
7. L'Atom Icons eredita automaticamente la versione aggiornata
#### Motivi della Centralizzazione
- **Coerenza**: Evita conflitti tra versioni CSS e JS
- **Manutenibilità**: Un solo punto di aggiornamento
- **Sicurezza**: Previene incompatibilità tra versioni (es: classi CSS rinominate tra release)
- **Performance**: Niente duplicazione di file CSS
- **Ereditarietà**: Atoms secondari (Icons) leggono la versione da CDN automaticamente
#### Best Practice per Atoms
```twig
{% block stylesheets %}
{{ parent() }}
{% if particle.enabled %}
{% endif %}
{% endblock %}
```
**Nota**: Questa limitazione è intrinseca all'architettura Gantry e deve essere rispettata per garantire stabilità del template. Gantry 5 **NON supporta import SCSS personalizzati** per gli Atoms: il sistema di compilazione SCSS elabora import solo per particles, non per atoms.
#### Regola Permanente: Data-Element per Validatore Modello Scuole
Per i criteri dell'app di valutazione scuole, i marker `data-element` critici DEVONO essere presenti nel **markup server-side** (template/override) e non solo applicati via fallback JS.
- Riferimento ufficiale primario: https://docs.italia.it/italia/designers-italia/app-valutazione-modelli-docs/it/versione-attuale/requisiti-e-modalita-verifica-scuole.html
- Riferimento documentazione app: https://docs.italia.it/italia/designers-italia/app-valutazione-modelli-docs/it/versione-attuale/
Selector/marker minimi da garantire nel markup:
- `data-element="menu"`
- `data-element="overview"`
- `data-element="school-submenu"`, `services-submenu`, `news-submenu`, `teaching-submenu`, `custom-submenu`
- `data-element="service-type"`, `service-link`, `pager-link`
- `data-element="school-locations"`
- `data-element="search-modal-button"`
- `data-element="search-modal-input"`
Uso Atoms in questo contesto:
- consentito come supporto diagnostico/fallback,
- NON sufficiente come unica implementazione per conformità stabile con crawler/headless del validatore.
### 7.4 Particles: Architettura e Patterns
#### Gestione Colori Preset
**Pattern Adottato**: Le particelle utilizzano le **variabili SCSS di Gantry** già definite in `scss/configuration/_colors.scss`:
- `$base-text-color`: Colore primario del preset (cambia per ogni preset)
- `$accent-color-1`: Colore accent secondario
- `$accent-color-2`: Colore accent per hover/focus
**Motivo**: Le CSS Custom Properties (`var(--accent-primary)`) non funzionano con l'architettura di compilazione SCSS di Gantry. Le variabili SCSS vengono compilate direttamente nel CSS finale, garantendo compatibilità con tutti i preset definiti in `presets.yaml`.
**Procedura di Cambio Preset**:
1. Seleziona il preset da **Gantry Admin → Styles → Presets**
2. **Compila il CSS** da **Gantry Admin → Styles → Compile CSS**
3. Pulisci cache Joomla e Gantry
4. I colori delle particelle si aggiornano automaticamente
#### Direttive Generali per Particles
1. **Coerenza**: Seguire le linee guida di **Bootstrap Italia**.
2. **Accessibilità**: Rispettare gli standard **WCAG 2.1 AA**.
3. **Configurazione YAML**: Documentare chiaramente ogni campo configurabile.
4. **Responsività**: Testare su diverse dimensioni dello schermo.
5. **Dipendenza dagli Atoms**: Le Particles dipendono dagli Atoms globali per tutte le risorse CSS/JS.
#### Regole di Utilizzo dei Campi `version` e `css_url`
**MAI nelle Particles (modale-login, icone-link, etc.):**
- ❌ **Non aggiungere** campi `version` o `css_url` alle Particles
- ❌ **Non caricare** CSS di Bootstrap Italia direttamente dalle Particles
- ✅ **Aggiungere note di avvertenza `_info`** (alert danger) che dichiarano esplicitamente la dipendenza dagli Atoms
#### Convenzioni SCSS bi-*
- Tutti i file di sezione refactor DEVONO usare prefisso **bi-** (es: `_bi-top.scss`, `_bi-header.scss`, `_bi-offcanvas.scss`, `_bi-menu.scss`, `_bi-drawer.scss`).
- I file legacy senza prefisso **NON vanno importati** nel main entry-point (`scss/bootstrapitalia.scss`).
- **Import Order**: Tutti i file bi-* DEVONO essere importati centralizzati in `scss/bootstrapitalia.scss` dopo import configuration/ e mixins/.
- Regole critiche (offcanvas toggle, z-index, breakpoints, colori) DEVONO essere centralizzate nei file di configurazione (C3).
- Ogni file bi-* DEVE utilizzare SOLO variabili centralizzate (niente hardcoding di valori numerici o colori).
- **Refactor Completo di Sezione**: Se si modifica una sezione (es: top, header), verificare che il file bi-* corrisponda (es: `_bi-top.scss` DEVE contenere tutte le regole top-, non frammentate in altri file).
#### CSS Custom Properties e Preset Gantry
- Le CSS Custom Properties **non** devono essere generate da Twig delle particles.
- La configurazione dei preset avviene in `gantry/presets.yaml` e tramite SCSS compilato.
- Se un atom Twig usa CSS inline, deve leggere solo configurazioni Gantry (non introdurre CSS vars custom).
---
## 8. Pattern di Sviluppo e Guida Operativa
### 8.1 Variabili Spacing (`_spacing.scss`)
**File**: `scss/configuration/_spacing.scss`
**Scala Progressiva (base 0.25rem = 4px)**:
| Variabile | Valore | Uso Tipico |
|--------------------|-----------|-------------------------------------|
| `$spacing-xs` | 0.25rem | Gap icone, padding badge |
| `$spacing-sm` | 0.5rem | Padding compatti, margin verticali |
| `$spacing-md` | 0.75rem | Margin inline standard (→) |
| `$spacing-lg` | 1rem | Padding contenitori base |
| `$spacing-xl` | 1.5rem | Separazione sezioni, gap prominenti |
| `$spacing-xxl` | 2rem | Padding modal/card |
| `$spacing-xxxl` | 3rem | Spacing sezioni extra-large |
**Pattern Specifici TOP Section** (conformi v1.0.14):
```scss
// Margin inline elements (toggle, switcher, login)
$margin-inline-right: $spacing-md; // 0.75rem
$margin-inline-bottom: $spacing-sm; // 0.5rem
$margin-offcanvas-active: 4.5rem; // Quando offcanvas aperto
```
**Touch Target WCAG 2.1**:
```scss
$touch-target-min: 44px; // WCAG 2.1 Level AA (minimo)
$touch-target-recommended: 48px; // WCAG 2.1 Level AAA (raccomandato)
```
**Border Radius Standardizzati**:
```scss
$border-radius-sm: 0.25rem; // Piccolo (pulsanti, badge)
$border-radius-md: 0.5rem; // Medio (dropdown, card compatte)
$border-radius-lg: 1rem; // Grande (modal, panel)
$border-radius-circle: 50%; // Circolari (avatar, icon-button)
```
**Gap Flexbox/Grid**:
```scss
$gap-sm: $spacing-xs; // 0.25rem (icone ravvicinate)
$gap-md: $spacing-sm; // 0.5rem (elenchi standard)
$gap-lg: $spacing-md; // 0.75rem (card layout)
$gap-xl: $spacing-xl; // 1.5rem (sezioni prominenti)
```
**Conversione Pratica**:
```scss
// ❌ PRIMA (hardcoded)
.preset-dropdown {
padding: 0.5rem;
margin-right: 0.75rem;
border-radius: 0.5rem;
}
// ✅ DOPO (variabili)
.preset-dropdown {
padding: $spacing-sm;
margin-right: $margin-inline-right;
@include border-radius-standard($border-radius-md);
}
```
### 8.2 Mixin Effects (`_effects.scss`)
**File**: `scss/mixins/_effects.scss` (227 righe)
#### Transizioni
**`smooth-transition()`** - Single property:
```scss
// Firma
@mixin smooth-transition($properties: all, $duration: 0.3s, $easing: ease-in-out)
// Esempi
.button {
@include smooth-transition(background-color, 0.2s);
// → transition: background-color 0.2s ease-in-out;
}
.link {
@include smooth-transition(color, 0.15s);
// → transition: color 0.15s ease-in-out;
}
```
**`transition()`** - Multi-property (variadic):
```scss
// Firma
@mixin transition($values...)
// Esempi
.modal-overlay {
@include transition(opacity 0.3s ease-out, z-index 0s);
// → transition: opacity 0.3s ease-out, z-index 0s;
}
.card {
@include transition(transform 0.3s, box-shadow 0.3s);
// → transition: transform 0.3s, box-shadow 0.3s;
}
```
**Quando usare quale**:
- `smooth-transition()`: Simple hover states (color, opacity, background)
- `transition()`: Complex animations (transform + background, multi-property timing)
#### Hover Effects
```scss
// Hover Scale
@mixin hover-scale($scale: 1.4)
.icon {
@include hover-scale(1.2);
// → &:hover { transform: scale(1.2); }
}
// Hover Scale con transizione
@mixin hover-scale-smooth($scale: 1.4, $duration: 0.3s)
.button-icon {
@include hover-scale-smooth(1.1, 0.2s);
}
// Button hover lighten
@mixin button-hover-lighten($base-color, $amount: 5%, $duration: 0.2s)
.btn-primary {
@include button-hover-lighten($base-text-color, 10%, 0.15s);
}
```
#### Focus States (Accessibilità)
```scss
// Focus outline
@mixin focus-outline($color, $width: 2px, $offset: 2px)
.link {
@include focus-outline($base-text-color, 3px, 3px);
}
// Focus ring (box-shadow)
@mixin focus-ring($color, $width: 2px)
.input {
@include focus-ring($base-text-color, 3px);
}
```
#### Border Radius
```scss
@mixin border-radius-standard($radius: 0.5rem)
@mixin border-radius-circle()
// Uso
.card {
@include border-radius-standard($border-radius-lg);
}
.avatar {
@include border-radius-circle();
}
```
### 8.3 Mixin Breakpoints
**File**: `scss/configuration/_breakpoints.scss`
**Variabili Disponibili**:
```scss
$bp-mobile-small: 480px;
$bp-tablet: 768px; // Breakpoint critico
$bp-desktop: 992px;
$bp-large: 1024px;
$bp-xl: 1200px;
```
**Pattern v1.0.14 Conforme** (con variabili):
```scss
// ✅ Pattern CONFORME (usa variabile)
@media (max-width: ($bp-tablet - 1px)) {
// Mobile styling (< 768px)
}
@media (min-width: $bp-desktop) {
// Desktop styling (≥ 992px)
}
```
**Mixin Media Query Semantici** (alternativa preferita per nuovo codice):
```scss
@mixin media-mobile-only // max-width: 767px
@mixin media-tablet // min-width: 768px
@mixin media-tablet-down // max-width: 991px
@mixin media-desktop // min-width: 992px
@mixin media-large // min-width: 1024px
@mixin media-xl // min-width: 1200px
// Uso:
.navbar {
@include media-mobile-only {
flex-direction: column;
}
@include media-desktop {
flex-direction: row;
}
}
```
**❌ Pattern VIETATI**:
```scss
// ❌ VIETATO: Hardcoded px
@media (max-width: 768px) { ... }
// ❌ VIETATO: Hardcoded senza variabile
@media screen and (max-width: 991px) { ... }
```
**Regola Applicabilità**:
- **File esistenti**: Pattern `@media (max-width: ($bp-tablet - 1px))` è **accettabile** (non richiede refactor immediato se già presente)
- **Nuovo codice**: Preferire `@include media-mobile-only` per coerenza
- **MAI** introdurre nuovi valori hardcoded tipo `768px` senza variabile
### 8.4 Z-Index Hierarchy (`_z-index.scss`)
**File**: `scss/configuration/_z-index.scss`
**Gerarchia Completa** (dal basso verso l'alto):
```scss
// Base Layers
$z-base: 1000; // Livello base sezioni
$z-header: 1000; // Header
$z-navigation: 1002; // Navigation bar
$z-top: 1003; // Top section
// Overlay Layers
$z-offcanvas-overlay: 1010; // Offcanvas backdrop
// Interactive Elements
$z-preset-switcher: 1031; // Preset switcher dropdown
$z-offcanvas-toggle: 1035; // Offcanvas toggle button
// Modal Layers
$z-modal: 1900; // Modali (login, ricerca)
$z-popover: 1920; // Popover e tooltip
```
**Regola Ferrea**: **ZERO tolleranza** per `z-index: [numero]` hardcoded.
```scss
// ❌ MAI FARE
.element {
z-index: 1050;
}
// ✅ SEMPRE così
.element {
z-index: $z-modal;
}
// ✅ Calcolo dinamico (se necessario)
.element {
z-index: ($z-offcanvas-overlay + 5);
}
```
**Quando Aggiungere Nuovo Valore**:
1. Identificare stacking context corretto (tra quali layer si deve posizionare)
2. Aggiungere variabile in `_z-index.scss` con nome semantico
3. Inserire nel commento la gerarchia aggiornata
4. Usare la variabile ovunque necessario
### 8.5 Typography (`_typography.scss`)
**File**: `scss/configuration/_typography.scss`
**Font Families** (Bootstrap Italia Official):
```scss
$fonts-body-font: "Titillium Web", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
$fonts-heading-font: "Titillium Web", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
$fonts-menu-font: "Titillium Web", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
$font-family-mono: "Roboto Mono", "SFMono-Regular", Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
$font-family-serif: "Lora", Georgia, "Times New Roman", Times, serif;
```
**⚠️ IMPORTANTE**: I font dichiarati devono corrispondere a quelli presenti in `/fonts/`:
- **Titillium Web** → `/fonts/titillium_web/` (41 file: regular, 300, 600, 700 + italics)
- **Roboto Mono** → `/fonts/roboto_mono/` (20 file: regular, 700 + italics)
- **Lora** → `/fonts/lora/` (20 file: regular, 700 + italics)
Fallback fonts (es: `-apple-system`, `Helvetica Neue`) sono system fonts e non richiedono file fisici.
**Font Weights**:
```scss
$font-weight-regular: 400;
$font-weight-medium: 500;
$font-weight-bold: 700;
```
**Heading Sizes** (scalabili da `$fontsizes-body-font-size: 0.9rem`):
```scss
$h1-font-size: $fontsizes-body-font-size * 3; // 2.7rem
$h2-font-size: $fontsizes-body-font-size * 2.3; // 2.07rem
$h3-font-size: $fontsizes-body-font-size * 2; // 1.8rem
$h4-font-size: $fontsizes-body-font-size * 1.5; // 1.35rem
$h5-font-size: $fontsizes-body-font-size; // 0.9rem
$h6-font-size: $fontsizes-body-font-size * 0.9; // 0.81rem
```
**Uso**:
```scss
// ❌ PRIMA
h1 {
font-family: "Cormorant SC", sans-serif;
font-size: 2.5rem;
font-weight: 700;
}
// ✅ DOPO
h1 {
font-family: $fonts-heading-font;
font-size: $h1-font-size;
font-weight: $font-weight-bold;
}
```
### 8.6 Colors (`_colors.scss`)
**File**: `scss/configuration/_colors.scss` (282 righe)
**Colori Base**:
```scss
$white: #ffffff;
$black: #000000;
$off-white: #ebeced;
```
**Section-Specific Colors** (esempio Top section):
```scss
$top-background-color: #0059b3;
$top-text-color: #ffffff;
$top-heading-color: #ffffff;
$top-link-color: #bfdfff;
$top-link-hover-color: #ffffff;
$top-link-visited-color: #99ccff;
```
**Uso**: Ogni sezione layout (Header, Navigation, Top, etc.) ha il proprio set di variabili. Usare sempre queste variabili invece di hardcoded hex.
**Eccezione Approvata**: Utility classes in `_bi-navigation.scss` (`.menu-color-red`, `.menu-color-blue`, etc.) possono contenere hex hardcoded per motivi di pragmatismo (vedi Sezione 4.5).
### 8.7 Section Mixins (`_section-styles.scss`)
**File**: `scss/mixins/_section-styles.scss` (135 righe)
#### section-base-styles()
```scss
@mixin section-base-styles($bg-color, $text-color, $heading-color, $z-index-level: auto)
// Uso
#g-top {
@include section-base-styles(
$top-background-color,
$top-text-color,
$top-heading-color,
$z-top
);
}
```
Applica:
- Background, color, heading colors
- Position relative
- Z-index (se specificato)
- Link styles con transizioni
#### section-grid-layout()
```scss
@mixin section-grid-layout($gap: 1.5rem, $min-height: 60px)
// Uso
#g-top .g-container {
@include section-grid-layout($gap-lg, 60px);
}
```
Applica:
- Flex layout con `align-items: center`
- Gap tra blocchi
- Min-height per consistenza
- Classi `.align-left`, `.align-right` per blocchi flex
#### section-with-image()
```scss
@mixin section-with-image($bg-color, $text-color, $heading-color, $image-url,
$repeat: no-repeat, $size: cover, $z- index-level: auto)
// Uso
#g-header {
@include section-with-image(
$header-background-color,
$header-text-color,
$header-heading-color,
url('/images/header-bg.jpg'),
no-repeat,
cover,
$z-header
);
}
```
### 8.8 Checklist Conversione Hardcoded → Variabili
**Procedura Step-by-Step**:
#### Passo 1: Identificazione Pattern
Eseguire grep per individuare valori hardcoded:
```bash
# Margin/padding hardcoded
grep -rn "margin.*0\.\(25\|5\|75\)rem" scss/bootstrapitalia/
# Border radius hardcoded
grep -rn "border-radius.*\(0\.25\|0\.5\|1\)rem" scss/bootstrapitalia/
# Touch target hardcoded
grep -rn "\(44\|48\)px" scss/bootstrapitalia/
# Gap hardcoded
grep -rn "gap.*0\.\(25\|5\|75\|1\.5\)rem" scss/bootstrapitalia/
# Z-index hardcoded
grep -rn "z-index:\s*[0-9]" scss/bootstrapitalia/
# Media query hardcoded
grep -rn "@media.*[0-9]\+px" scss/bootstrapitalia/
# Colori hex hardcoded (escludi utility)
grep -rn "color.*#[0-9a-fA-F]\{6\}" scss/bootstrapitalia/ | grep -v "utility"
```
#### Passo 2: Mappatura Valori
Creare tabella di mappatura:
| Valore Hardcoded | Variabile Sostituzione | File Reference |
|--------------------|--------------------------------|-------------------------|
| `0.25rem` | `$spacing-xs` | `_spacing.scss` |
| `0.5rem` | `$spacing-sm` | `_spacing.scss` |
| `0.75rem` | `$spacing-md` / `$margin-inline-right` | `_spacing.scss` |
| `1rem` | `$spacing-lg` | `_spacing.scss` |
| `44px` | `$touch-target-min` | `_spacing.scss` |
| `768px` | `$bp-tablet` | `_breakpoints.scss` |
| `992px` | `$bp-desktop` | `_breakpoints.scss` |
| `z-index: 1035` | `$z-offcanvas-toggle` | `_z-index.scss` |
| `#ffffff` | `$white` / vars section | `_colors.scss` |
#### Passo 3: Sostituzione File-by-File
Per ogni file con pattern hardcoded:
1. **Leggere** contesto completo (10-20 righe prima/dopo)
2. **Identificare** significato semantico del valore
3. **Sostituire** con variabile appropriata
4. **Testare** compilazione SCSS (no errori)
5. **Verificare** layout non cambia (visual regression)
6. **Commit** atomically (un file alla volta quando possibile)
#### Passo 4: Verifica Post-Conversione
```bash
# Verificare 0 hardcoded rimasti (escludere eccezioni approvate)
grep -rn "z-index:\s*[0-9]" scss/bootstrapitalia/ | wc -l
# Risultato atteso: 0
grep -rn "@media.*[0-9]\+px" scss/bootstrapitalia/ | grep -v "\$bp-" | wc -l
# Risultato atteso: 0 (o solo eccezioni documentate)
```
### 8.9 Pattern di Conversione Comuni
#### Esempio 1: Toggle Positioning
```scss
// ❌ PRIMA (_bi-offcanvas-toggle.scss)
.offcanvas-toggle-wrapper {
width: 44px;
height: 44px;
margin-right: 0.75rem;
margin-bottom: 0.75rem;
@media (max-width: 768px) {
position: absolute;
top: 0.5rem;
left: 0.75rem;
z-index: 1035;
}
}
// ✅ DOPO
.offcanvas-toggle-wrapper {
width: $touch-target-min;
height: $touch-target-min;
margin-right: $margin-inline-right;
margin-bottom: $margin-inline-bottom;
@include media-mobile-only {
position: absolute;
top: $spacing-sm;
left: $spacing-md;
z-index: $z-offcanvas-toggle;
}
}
```
#### Esempio 2: Preset Switcher Dropdown
```scss
// ❌ PRIMA (_bootstrapitalia-preset-switcher.scss)
.preset-dropdown {
border-radius: 0.5rem;
padding: 0.5rem;
margin-left: 0.5rem;
z-index: 1031;
@media (max-width: 768px) {
margin-right: 0.75rem;
margin-bottom: 0.5rem;
}
}
.preset-item {
padding: 0.5rem 0.75rem;
border-radius: 0.25rem;
transition: background-color 0.15s ease-in-out;
&:hover {
background-color: #f5f5f5;
}
&:focus-visible {
outline: 2px solid #0066cc;
}
}
// ✅ DOPO
.preset-dropdown {
@include border-radius-standard($border-radius-md);
padding: $spacing-sm;
margin-left: $spacing-sm;
z-index: $z-preset-switcher;
@include media-mobile-only {
margin-right: $margin-inline-right;
margin-bottom: $margin-inline-bottom;
}
}
.preset-item {
padding: $spacing-sm $spacing-md;
@include border-radius-standard($border-radius-sm);
@include smooth-transition(background-color, 0.15s);
&:hover {
background-color: $off-white;
}
@include focus-outline($base-text-color, 2px);
}
```
#### Esempio 3: Login Wrapper
```scss
// ❌ PRIMA (_bootstrapitalia-modale-login.scss)
.it-login-wrapper {
// Nessun margin definito!
@media (max-width: 768px) {
// Nessun margin mobile!
}
}
.modal-dialog {
border-radius: 1rem;
padding: 2rem;
background: #fff;
}
// ✅ DOPO
.it-login-wrapper {
margin-right: $margin-inline-right;
@include media-mobile-only {
margin-right: $margin-inline-right;
margin-bottom: $margin-inline-bottom;
}
}
.modal-dialog {
@include border-radius-standard($border-radius-lg);
padding: $spacing-xxl;
background: $white;
}
```
### 8.10 Strategie Anti-Regressione
**Problema**: Perdita di standardizzazioni tra sessioni di sviluppo.
**Soluzioni**:
#### Git Workflow Strutturato
```bash
# Branch dedicato per standardizzazione
git checkout -b feature/standardization-scss
# Commit atomici per categoria
git commit -m "refactor(spacing): apply $spacing-* vars to toggle/switcher/login"
git commit -m "refactor(breakpoints): convert hardcoded px to $bp-* vars"
git commit -m "refactor(z-index): apply $z-* hierarchy to all sections"
```
#### Checklist Pre-Commit
Prima di ogni commit verificare:
- [ ] File contiene `z-index: [numero]` hardcoded? → Convertire a `$z-*`
- [ ] File contiene `@media (max-width: [numero]px)` hardcoded? → Convertire a `($bp-* - 1px)` o mixin
- [ ] File contiene margin/padding `0.Xrem` hardcoded? → Valutare `$spacing-*`
- [ ] File contiene `transition:` hardcoded? → Usare `@include smooth-transition()` o `transition()`
- [ ] File contiene `border-radius: Xrem` hardcoded? → Usare `$border-radius-*`
- [ ] Breakpoint conforme a pattern v1.0.14? → Verificare `($bp-tablet - 1px)` invece di `768px`
---
### 8.11 Procedure: Rollback Sicuro Versioni
**⚠️ CRITICA** - Seguire SEMPRE questi step per evitare compilazione fallita e dipendenze orfane
#### Problema Architetturale Identificato
Quando si ripristina una versione precedente (es: rollback da v1.0.17 a v1.0.14), **file creati in versioni successive vengono cancellati**, ma **riferimenti a questi file rimangono nel codice**, causando:
- ❌ Errori compilazione SCSS (mixin non definito, @import fallito)
- ❌ Referenze broken (file cancellato ma encore usato)
- ❌ Potenziale silent failure (layout si rompe, difficile debug)
**Caso Specifico (v1.0.17)**:
- **File mancante post-rollback**: `scss/mixins/_breakpoints.scss` (79 righe) eliminato quando si torna a v1.0.14
- **Referenza orfana**: `@include breakpoint(mobile-only)` in `scss/bootstrapitalia/_bi-top.scss` riga 220
- **Risultato**: Compilazione SCSS fallisce con "Undefined mixin 'breakpoint'"
#### Procedure Pre-Ripristino (6 Step Obbligatori)
**PRIMA di eseguire `git checkout `, completare TUTTI step**:
##### Step 1: Identificare File Creati in Versioni Successive
```bash
# Comando: mostra file AGGIUNTI tra versione target e HEAD
git diff v1.0.14..HEAD --name-status | grep "^A"
# Output atteso:
A scss/mixins/_breakpoints.scss
A scss/configuration/_spacing.scss
A scss/mixins/_dynamic-states.scss
```
**Interpretazione**:
- File con prefisso `^A` = Added in versioni successive
- Questi file NON esisteranno dopo rollback
- Verificare se sono usati nel codebase corrente
##### Step 2: Cercare Riferimenti nel Codebase
Per ogni file identificato, cercare riferimenti:
```bash
# Cercare import nella chain
git diff v1.0.14..HEAD -- "scss/**" | grep "@import.*breakpoints"
# Cercare utilizzo mixin/funzioni
git diff v1.0.14..HEAD -- "scss/bootstrapitalia/**" | grep "@include breakpoint"
# Count totale riferimenti
grep -r "@include breakpoint" scss/bootstrapitalia/ | wc -l
```
**Interpretazione**:
- Se count > 0 → File è **critico**, codice dipende da esso
- Se count = 0 → File è **isolato**, sicuro rimuovere (o riottenere da versione vecchia)
##### Step 3: Documentare Dipendenze Trovate
Creare inventory tempfile:
```
## Dipendenze Versione v1.0.14 → Rollback Analysis
File da Verificare:
- _breakpoints.scss:
- Importato in: _bi-top.scss, _bi-offcanvas.scss, _bi-menu.scss
- Usato 10+ volte ne "@include breakpoint()"
- CRITICO: Molti file dipendono
- _dynamic-states.scss:
- Importato in: _bootstrapitalia-modale-login.scss
- Usage: focus-shadow-dynamic(), 11 occorrenze
- CRITICO: Componente core usa
- _spacing.scss:
- Importato in: _bi-top.scss only
- Usage: $spacing-* vars, 9 occorrenze
- MEDIO: Isolato, ma essenziale per sezione
```
##### Step 4: Decidere Strategia Backward Compatibility
Per ogni file critico, scegliere una opzione:
**Opzione A - Mantenere File Critici** (RACCOMANDATO):
- ✅ **Pro**: Rollback funziona, nessun errore compilazione
- ✅ **Pro**: Mantenere dipendenze forward
- ❌ **Contro**: Versione "mix" di timeframes
- **Azione**: Copiare `_breakpoints.scss` in v1.0.14, committare come "backport: critical mixin"
**Opzione B - Refactoring Completo**:
- ✅ **Pro**: Versione è "pure" v1.0.14 code
- ❌ **Contro**: Laborioso, rischio di break durante refactor
- **Azione**: Sostituire `@include breakpoint()` con `@media (max-width: ($bp-tablet - 1px))` in modo manuale
**Opzione C - Gestione Incrementale**:
- ✅ **Pro**: Compromesso pragmatico
- **Azione**: Creare `scss/mixins/_fallbacks.scss` con stub mixin, import condizionale se file mancante
##### Step 5: Solo DOPO Verifica, Procedere Rollback
Una volta decisa strategia (step 4), eseguire rollback:
```bash
# Se Opzione A: copiare file critical in versione target
cp $(git show v1.0.17:scss/mixins/_breakpoints.scss) scss/mixins/_breakpoints.scss
git add scss/mixins/_breakpoints.scss
git commit -m "backport: restore _breakpoints.scss per compatibility v1.0.14"
# Se Opzione B: completare refactoring PRIMA di checkout
# (già fatto nei step precedenti)
# Procedere a rollback
git checkout v1.0.14
git log --oneline | head -1 # Verifica rollback avvenuto
```
##### Step 6: Validare Compilazione SCSS
Verificare che compilazione non fallisce:
```bash
# Compilare SCSS com testing
sass --no-source-map scss/bootstrapitalia.scss:custom/css-compiled/ 2>&1
# Verificare output
echo $?
# Output: 0 = OK, non-zero = ERRORE
# Se errore, controlliare stderr
sass --no-source-map scss/bootstrapitalia.scss 2>&1 | grep -i "error\|undefined"
```
**Interpretazione**:
- ✅ Exit code 0 → Compilazione OK, rollback safe
- ❌ Exit code != 0 → Errore found, completare step 4 (strategie) PRIMA di procedere
#### Flusso Decisionale Completo (Flowchart Testuale)
```
┌─ User vuole rollback v1.0.17 → v1.0.14
│
├─ Step 1: Identify created files (git diff)
│ ├─ Files found?
│ │ ├─ NO → Proceed step 5 (safe)
│ │ └─ YES → Continue step 2
│
├─ Step 2: Cercare riferimenti (grep)
│ ├─ Riferimenti found?
│ │ ├─ NO → File è isolato, step 5 safe
│ │ └─ YES → Continue step 3
│
├─ Step 3: Document dependencies
│ └─ Create inventory
│
├─ Step 4: Decide strategy (A/B/C)
│ ├─ Opzione A (backport):
│ │ └─ Copy file, commit
│ ├─ Opzione B (refactor):
│ │ └─ Manual code changes
│ └─ Opzione C (fallback):
│ └─ Create stub mixin
│
├─ Step 5: Eseguire checkout
│ └─ git checkout v1.0.14
│
└─ Step 6: Validare compilazione
├─ Success → Rollback completato ✅
└─ Error → Return to step 4, try different strategy
```
#### Quando Usare Quale Opzione
| Criticità File | Complexity Refactor | Tempo Disponibile | Opzione Consigliata |
|---|---|---|---|
| CRITICO | Bassa | Illimitato | **B** (Refactor) - Purest |
| CRITICO | Alta | Limitato | **A** (Backport) - Safe |
| CRITICO | N/A | Urgente | **A** (Backport) - Fastest |
| MEDIO | Qualsiasi | Qualsiasi | **A** (Backport) - Pragmatic |
| BASSO | Qualsiasi | Qualsiasi | **C** (Fallback) - Clean |
#### Regola Aurea
⚠️ **Mai ripristinare versione precedente senza audit dipendenze**
> File cancellati = potenziali errori di compilazione silenziosi fino al deploy. È meglio investire 30 minuti in Step 1-6 che 3 ore in debug post-rollback.
---
## 9. Risorse Utili
| Risorsa | Link |
|------------------------------|----------------------------------------------------------------------|
| **Bootstrap Italia Docs** | [italia.github.io/bootstrap-italia](https://italia.github.io/bootstrap-italia/) |
| **Bootstrap Italia CDN** | [jsdelivr.com/package/npm/bootstrap-italia](https://www.jsdelivr.com/package/npm/bootstrap-italia) |
| **Design UI Kit** | [github.com/italia/design-ui-kit](https://github.com/italia/design-ui-kit/) |
| **Design System Italia** | [designers.italia.it/design-system](https://designers.italia.it/design-system/) |
| **Manuale Operativo Design** | [docs.italia.it](https://docs.italia.it/italia/designers-italia/manuale-operativo-design-docs/it/versione-corrente/index.html) |
| **Verifica Modello Scuole (C.SC.1.1)** | [docs.italia.it - requisiti scuole](https://docs.italia.it/italia/designers-italia/app-valutazione-modelli-docs/it/versione-attuale/requisiti-e-modalita-verifica-scuole.html) |
| **App Valutazione Modelli** | [docs.italia.it - app valutazione](https://docs.italia.it/italia/designers-italia/app-valutazione-modelli-docs/it/versione-attuale/) |
| **Linee Guida AGID** | [agid.gov.it](https://www.agid.gov.it/it/design-servizi/linee-guida-design-servizi-digitali-pa) |
| **Joomla Docs** | [docs.joomla.org](https://docs.joomla.org/) |
| **Gantry 5 Docs** | [docs.gantry.org](https://docs.gantry.org/gantry5) |
| **Changelog Completo** | [Changelog Beta](../changelogs/index.html) - Documenta tutte le phases realizzate |