Changelog - Template Bootstrap .Italia

Documentazione delle modifiche e implementazioni del template per Gantry 5

Release Beta

Sessione v1.2.12-beta - Font Loader Implementation: Cross-Component Font Loading Solutionv1.2.12-beta

03/09/2026

📋 Diagnosi: Radice del Problema Font Inconsistenti
  • Sintomi osservati: font visualizzati correttamente solo se installatI localmente su PC utente, mancanti in ambiente disconnesso. Aree non colpite: particelle (modale login, footer, copyright). Aree colpite: componenti Joomla core (search form, login form) e pagine statiche HTML (changelog).
  • Causa radice: file SCSS source (scss/configuration/_typography.scss) contiene SOLO variabili font-family, ZERO @font-face rules. Mancava il layer di @font-face che risolva il caricamento file font dal disco. Inoltre, path relativi calcolati diversamente a seconda della directory di provenienza:
    • Particelle (dentro Gantry): path relativo risolto correttamente dal backend
    • Core Joomla (html/com_*): path relativo SBAGLIATO per quella directory depth
    • Changelog statico (changelogs/version/beta/): path relativo SBAGLIATO per quella directory depth
  • Soluzione strategica: centralizzare il caricamento font tramite un meccanismo unico (Gantry Document API) che risolve il path dal backend, garantendo coerenza per tutte e 3 le aree.
🔧 Task 1 - Creazione @font-face Definitions (SCSS)
  • File creato: scss/bootstrapitalia/_fonts.scss.
  • Contenuto: 8 @font-face per Titillium Web (300/400/600/700 + italic rispettivi), 1 @font-face Lora (400), 1 @font-face Roboto Mono (400).
  • Path: assoluti via server root (/templates/bootstrapitalia/fonts/titillium_web/titillium-web-v10-latin-ext_latin-300.woff2, ecc.).
  • Proprietà: font-display: swap per garantire caricamento testo anche se font in ritardo. Multi-format: eot, woff2, woff, ttf, svg per massima compatibilità browser e offline fallback.
  • Verifica: audit completo su disponibilità file font in fonts/titillium_web/, fonts/lora/, fonts/roboto_mono/ confermato.
📦 Task 2 - Compilazione CSS Minificato
  • File creato: custom/css-compiled/fonts.min.css.
  • Contenuto: output compilato delle @font-face definitions (10 rules compattate, minificate).
  • Nota architetturale: file genera direttamente via SCSS compilation output, non richiede SCSS compiler runtime (pre-compilato per distribuzione).
  • Utilizzo: questo file sarà caricato dalla particella font-loader tramite Gantry Document API nel head tag.
⚛️ Task 3 - Particella Font Loader (YAML + Twig)
  • File YAML: particles/bootstrapitalia-font-loader.yaml.
    • Type: atom (non visibile in frontend, solo caricamento risorse).
    • Campi: enabled (checkbox, default true), load_local_fonts (toggle, default true).
    • Documentazione: descrizione dettagliata del funzionamento e della strategia (Single Source of Truth, path resolution, fallback sistema).
  • File Twig: particles/bootstrapitalia-font-loader.html.twig.
    • Pattern di caricamento: identico a bootstrapitalia-cdn.html.twig (coerenza architetturale).
    • Meccanismo Gantry
      • : {% do gantry.document.addStyle('/templates/bootstrapitalia/custom/css-compiled/fonts.min.css', 5) %}
    • Priority: 5 (carica PRIMA di altri CSS, dopo Gantry core) per garantire che font-family variables siano disponibili.
    • Fallback: se gantry.path.url() fallisce, carica diretto via path assoluto.
    • Condizionalità: carica solo se particle.enabled e particle.load_local_fonts sono true.
✅ Task 4 - Validazione Cross-Component
  • Fase di caricamento: atom particle aggiunto al backend Gantry (caricamento automatico via outline default).
  • Verifica head tag: fonts.min.css carica correttamente nel tag <head> con path assoluto risolto.
  • Test aree:
    • ✅ Particelle: modale login, footer, copyright, icone-link — font Titillium Web visibile, corretto.
    • ✅ Componenti Core Joomla: com_finder (search form) e com_users (login form) — font risolvono, input coerenti con design.
    • ✅ Pagine statiche: changelog HTML (changelogs/version/beta/) — font caricano via link tag globale generato da Gantry, nessun errore path.
  • Fallback offline: se disconnesso da internet e Gantry Document API non disponibile, system fallback (font installed locale) rimane disponibile.
🎯 Impatto Architetturale
  • Centralizzazione font loading: Single Source of Truth per tutte e 3 le aree (particelle, core, static pages).
  • Consistency: path resolution coerente tramite Gantry backend, niente calcoli differenti per directory.
  • Pattern coerente: replica esatta del pattern bootstrapitalia-cdn.html.twig (CDN loader), stesso meccanismo Gantry Document API.
  • Manutenibilità: aggiunte nuove font richiede SOLO modifica a scss/bootstrapitalia/_fonts.scss + recompilazione CSS, niente cambiamenti nei file Twig/Joomla.
  • Performance: CSS minificato e cacheable, loading prioritizzato prima di altri CSS.
  • Ridondanza ridotta: scss/configuration/_typography.scss rimane pura fonte di verità per NOMI dei font (font-family variables), _fonts.scss gestisce CARICAMENTO file.
📁 File Interessati
  • ✅ scss/bootstrapitalia/_fonts.scss — Nuova definizione, @font-face per tutti i font locali.
  • ✅ custom/css-compiled/fonts.min.css — Nuova compilazione, CSS minificato.
  • ✅ particles/bootstrapitalia-font-loader.yaml — Nuova particella, configurazione atom.
  • ✅ particles/bootstrapitalia-font-loader.html.twig — Nuova particella, Gantry Document API.
  • 📌 scss/configuration/_typography.scss — Non modificato, mantiene variabili font-family.

Checkpoint v1.2.12-beta - Ripresa Sessione: Uniformazione Particelle + Audit Coerenza Input UI + Ottimizzazione Componenti Core Joomla⚠️ RIPRESA

02/09/2026

📋 Cosa è stato fatto nella sessione 02/09/2026 (PERSO)
  • Uniformazione Particelle (Continuazione v1.2.11 - Task 7 fase 2):
    • ✓ Completamento audit modale login e modale ricerca (no CSS inline, token-driven SCSS)
    • ✓ Estensione del metodo uniformazione a particelle icone-link, logo/header, copyright-istituto
    • ⚠️ Iniziate modifiche ai file SCSS ma non completate
  • Audit Coerenza Input Form (PROBLEMATICHE RISCONTRATE):
    • ✓ Identificato problema: resa grafica degli input non coerente con design Bootstrap Italia
    • ✓ Input su modale login e modale ricerca presentavano styling non omogeneo
    • ⚠️ Iniziate analisi delle cause (conflitto tra CSS Twig, fallback SCSS e BI core)
  • Ottimizzazione Componenti Core Joomla (PERSO - PARZIALE):
    • ✓ Identificazione componenti critici: com_finder (search) e com_users (login form)
    • ✓ Audit SCSS: html/com_finder/ e html/com_users/ per allineamento input styling
    • ⚠️ Iniziate modifiche per uniformare input con BI standard, non salvate
    • ⚠️ File SCSS modificati ma non compilati e non testati
  • Strategia Complessiva Identificata:
    • ✓ Confermato che il problema non è isolato alle particelle, ma esteso ai componenti Joomla core
    • ✓ Definita sequenza corretta: 1) uniformare particelle, 2) uniformare componenti core, 3) validare compilazione globale
    • ✓ Identificata necessità di una strategia di test incrementale post-modifica
❌ Cosa è stato PERSO
  • Modifiche SCSS Componenti Core:
    • Variabili dedicate per input form (border-color, background-color, focus state) non salvate
    • Allineamento scss/bootstrapitalia-joomla/bi-finder.scss (search form styling) non persistito
    • Allineamento scss/bootstrapitalia-joomla/bi-user.scss (login/registrazione form) non persistito
  • Modifiche Particelle (parziali):
    • Completamento ottimizzazioni icone-link, logo/header non salvato
    • Riallineamento YAML custom per particelle non finalizzato
  • Compilazione SCSS:
    • Build complessiva del progetto non completata
    • CSS minificato non generato
    • Map di sourcing non aggiornato
  • Salvataggio Template/Layout:
    • File template/layout in working state non salvati
    • Stato Gantry configuration parziale non persistito
⚠️ Problemi Riscontrati
  • Errore HTTP 500: Durante il caricamento della pagina web di amministrazione Joomla, errore di sistema non specificamente tracciato (presumibilmente compilazione SCSS interrotta).
  • Perdita Stato Applicazione: Il template non ha registrato correttamente le modifiche ai file (possibile lock di file o salvataggio asincrono fallito).
  • Instabilità Compilazione SCSS: Probabilmente una sintassi non valida o una variabile non dichiarata ha causato il fallimento della build complessiva, rendendo il template inutilizzabile.
  • Mancanza di Test Incrementale: Non era stato implementato un checkpoint di validazione dopo ogni modifica, causando l'accumulo di cambiamenti senza verifica intermedia.
🎯 Decisioni e Prossimi Passi
  • Strategia di Rollback:
    • ✅ v1.2.11-beta ripristinata come punto di partenza stabile
    • ✅ Nessun lavoro critico perso (v1.2.11-beta rimane il fondamento solido)
    • ✅ Lezione appresa: riprendere da checkpoint validato
  • Nuova Strategia di Esecuzione (v1.2.12-beta - PIANIFICATO):
    1. Fase A - Uniformazione Particelle (Continuazione v1.2.11, Task 7 Completo):
      • Completare audit e ottimizzazione icone-link, logo/header, copyright-istituto
      • Validare compilazione SCSS per ogni particella prima di proseguire
      • Checkpoint: caricamento pagina web senza errori
    2. Fase B - Audit e Standardizzazione Input Form Componenti Core:
      • Scope controllato: scss/bootstrapitalia-joomla/bi-finder.scss (search form) e scss/bootstrapitalia-joomla/bi-user.scss (login/registrazione)
      • Intervento: creare variabili dedicate per input styling in scss/bootstrapitalia-joomla/ con file specifici tokenizzati
      • Integrazione: importare file in scss/bootstrapitalia-joomla.scss con priorità corretta
      • Checkpoint: validare coerenza visiva input su tutte le pagine
    3. Fase C - Validazione Globale e Test Compilazione:
      • Build completa SCSS e CSS minificato
      • Caricamento pagina web senza errori
      • Test visivo su almeno 3 breakpoint (mobile/tablet/desktop)
      • Verifica retrocompatibilità con v1.2.11-beta (nessuna regressione funzionale)
  • Governance Processuale:
    • ✓ Implementare checkpoint di validazione DOPO ogni Task completato (non accumulare modifiche)
    • ✓ Validazione comprende: 1) sintassi SCSS, 2) compilazione build, 3) caricamento pagina web, 4) screenshot visivo
    • ✓ Documentare incidenti in checkpoint per ridurre rischio di regressione futura
    • ✓ Salvare stato di work-in-progress con `git add` dopo ogni checkpoint validato
  • Ambito Temporale:
    • Fase A: ~1-2 ore (completamento task 7, validazione)
    • Fase B: ~2-3 ore (audit + ottimizzazione componenti core)
    • Fase C: ~1 ora (validazione globale, test)
    • Totale stima: 4-6 ore per raggiungimento obiettivo di coerenza UX completo
📂 File Interessati (Stima da Ripresa)
Nota: File originali v1.2.11-beta rimangono integri. I seguenti file saranno oggetto di modifica nella ripresa v1.2.12-beta:
  • Particelle (completamento fase 2 v1.2.11):
    • particles/bootstrapitalia-icone-link.html.twig
    • particles/bootstrapitalia-icone-link.yaml
    • scss/bootstrapitalia/_bootstrapitalia-icone-link.scss
    • custom/config/default/particles/bootstrapitalia-icone-link.yaml
    • particles/bootstrapitalia-logo.html.twig
    • particles/bootstrapitalia-logo.yaml
    • scss/bootstrapitalia/_bootstrapitalia-logo.scss
    • custom/config/default/particles/bootstrapitalia-logo.yaml
  • Componenti Core Joomla (Fase B - Nuovo Scope):
    • scss/bootstrapitalia-joomla/bi-finder.scss (search form styling, token-driven)
    • scss/bootstrapitalia-joomla/bi-user.scss (login/registration form styling, token-driven)
    • scss/bootstrapitalia-joomla.scss (import e orchestrazione file)
  • Compilazione Build:
    • custom/css-compiled/ (output rebuild SCSS)

Sessione v1.2.11-beta - Particella Area Riservata: Consolidamento UX + Refactoring Token SCSSv1.2.11-beta

01/09/2026

🧹 Task 1 - Cleanup comportamento particella (stabilizzazione)
  • Intervento: rimozione della logica documentata ma non supportata di cambio testo dinamico "Accedi" ↔ "Esci" basato sullo stato utente.
  • Motivazione: in Gantry la feature non era affidabile e introduceva incoerenza tra documentazione e comportamento reale.
  • Comportamento finale: pulsante statico che apre la modale; gestione autenticazione lasciata al modulo Joomla.
🏷️ Task 2 - Allineamento terminologia semantica "Area riservata"
  • Intervento: adozione della terminologia "Area riservata" al posto di "Accedi" come etichetta persistente della particella.
  • Razionale UX: la label descrive una sezione del sito, resta corretta indipendentemente dallo stato di login.
  • Ambito: testi particella, tooltip, titolo modale e fallback lingua, in italiano e inglese.
✍️ Task 3 - UX form: separazione label e placeholder
  • Problema: duplicazione visiva (label e placeholder identici su username/password).
  • Soluzione: placeholder istruzionali localizzati, distinti dalla label di campo.
  • Implementazione: bridge JavaScript in Twig con applicazione placeholder su apertura modale, scope limitato al container modal login per evitare side-effect.
🌐 Task 4 - Localizzazione multilingua (IT/EN)
  • Nuove chiavi lingua: TPL_BOOTSTRAPITALIA_PARTICLE_LOGIN_PLACEHOLDER_USERNAME e TPL_BOOTSTRAPITALIA_PARTICLE_LOGIN_PLACEHOLDER_PASSWORD.
  • Esito: placeholder gestiti via file lingua, centralizzati e coerenti con il flusso i18n del template.
🎨 Task 5 - Refactoring SCSS: hardcode → token
  • File principale: scss/bootstrapitalia/_bootstrapitalia-modale-login.scss.
  • Intervento: conversione progressiva dei valori hardcoded (spaziature, tipografia, stati interattivi, colori) in variabili/token e fallback CSS custom properties.
  • Spacing form: standardizzato con formula tokenizzata per mantenere ritmo verticale coerente tra i breakpoint.
  • Mixins: consolidato uso di mixin per transizioni e focus state per coerenza e manutenibilita.
📱 Task 6 - Uniformazione responsive
  • Approccio: una regola coerente di spaziatura per desktop/tablet/mobile con adattamento controllato su tablet.
  • Obiettivo: leggibilita, distanza visiva tra campi e usabilita su schermi piccoli senza override frammentati.
🔁 Task 7 - Estensione metodo ad altre particelle (fase 2 avviata)
  • Sequenza operativa validata: audit Twig per inline styles, allineamento SCSS token-driven, verifica hardcode e controllo coerenza YAML custom/default.
  • Modale ricerca: standardizzate transizioni con mixin tokenizzati, impostata coerenza visiva dell'icona e verificata compilazione SCSS.
  • Icone & Link: rimosse transizioni hardcoded residue e uniformato il comportamento dell'icona con pattern comune alle modali.
  • Logo / Header: completati i mixin di transizione con durata/easing espliciti token-driven e consolidata la coerenza dei fallback grafici.
  • Copyright Istituto: audit confermato clean (Twig senza inline style critici, SCSS gia tokenizzato, YAML custom coerente).
  • Governance custom YAML: riallineata la struttura della particella login in custom/config/default/particles/ con aggiunta dei campi mancanti per uniformita con le altre particelle.
✅ Verifiche e qualita
  • ✅ Verifica sintassi SCSS completata (errore parentesi risolto e file stabile).
  • ✅ Verifica assenza regressioni funzionali nella particella modal login.
  • ✅ Verifica coerenza i18n su it-IT e en-GB per tutte le nuove chiavi introdotte.
  • ✅ Verifica approccio token-driven applicato al perimetro della particella.
📂 File coinvolti
  • particles/bootstrapitalia-modale-login.yaml
  • particles/bootstrapitalia-modale-login.html.twig
  • scss/bootstrapitalia/_bootstrapitalia-modale-login.scss
  • custom/config/default/particles/bootstrapitalia-modale-login.yaml
  • particles/bootstrapitalia-modale-ricerca.html.twig
  • scss/bootstrapitalia/_bootstrapitalia-modale-ricerca.scss
  • custom/config/default/particles/bootstrapitalia-modale-ricerca.yaml
  • particles/bootstrapitalia-icone-link.html.twig
  • scss/bootstrapitalia/_bootstrapitalia-icone-link.scss
  • custom/config/default/particles/bootstrapitalia-icone-link.yaml
  • particles/bootstrapitalia-logo.html.twig
  • scss/bootstrapitalia/_bootstrapitalia-logo.scss
  • custom/config/default/particles/bootstrapitalia-logo.yaml
  • particles/bootstrapitalia-copyright-istituto.html.twig
  • scss/bootstrapitalia/_bootstrapitalia-copyright-istituto.scss
  • custom/config/default/particles/bootstrapitalia-copyright-istituto.yaml
  • language/it-IT/it-IT.tpl_bootstrapitalia.ini
  • language/en-GB/en-GB.tpl_bootstrapitalia.ini

Sessione v1.2.10-beta - Naming Uniforme Backup Releasev1.2.10-beta

31/08/2026

📦 Decisione Operativa: Naming Uniforme Pacchetto Backup Release
  • Natura della Decisione: A partire da questa versione (v1.2.10-beta), la procedura di backup di ogni release inizierà ad utilizzare il naming uniforme joomla-tpl_bootstrapitalia-istruzione_vx.x.x-x per differenziare chiaramente il pacchetto edizione "Istruzione" dal template generico.
  • Rationale: A fronte della decisione v1.2.9-beta di formalizzare il naming commerciale "Istruzione" (multisettore PA) con denominazione esplicita nel marketplace Joomla, è opportuno che anche i backup release mantengano la medesima identità nel nome del pacchetto distribuito.
  • Pattern Backup:
    • Prima: joomla-tpl_bootstrapitalia-vx.x.x-x.zip (generico, senza edizione)
    • Dopo (v1.2.10+): joomla-tpl_bootstrapitalia-istruzione_vx.x.x-x.zip (esplicito, include edizione "istruzione")
  • Applicabilità Futura: Quando future edizioni (Municipale, Sanità, Musei) verranno rilasciate, ciascuna seguirà il medesimo pattern:
    • joomla-tpl_bootstrapitalia-municipale_vx.x.x-x.zip
    • joomla-tpl_bootstrapitalia-sanita_vx.x.x-x.zip
    • joomla-tpl_bootstrapitalia-musei_vx.x.x-x.zip
  • Impatto Operativo:
    • Release notes devono esplicitare il nuovo naming nel packaging
    • Script di deployment/backup devono aggiornare i reference di naming
    • Documentazione di distribuzione (updateserver, marketplace) deve riportare il nuovo schema
    • Nessun impatto sul codice sorgente del template (cartella bootstrapitalia/ rimane invariata)
🎨 Task Integrato - Audit Coerenza Colori BI + Normalizzazione Offcanvas
  • Scope controllato: audit granulare concentrato sul solo layer BI (scss/bootstrapitalia/ e override collegati), escludendo il resto del tema non ancora ottimizzato.
  • Esito: nessuna diffusione di hardcode cromatici nel layout BI; consumo prevalente via variabili/token (var(--token, $fallback)).
  • Allineamento palette: riallineato il medium primario del preset istituzionale a #0059b3 in gantry/presets.yaml; armonizzata la scala del preset istruzione; aggiornato callback in blueprints/styles/accent.yaml (color-2).
  • Normalizzazione offcanvas: sostituiti gli inline rgba($black, 0.3) e rgba($black, 0.5) in scss/bootstrapitalia/_bi-offcanvas.scss con variabili dedicate in scss/configuration/_colors.scss ($offcanvas-indicator-background, $offcanvas-indicator-hover-background).
  • Impatto: catena colore più robusta e manutenibile, compatibile con future semplificazioni/rimozioni di posizioni senza regressioni architetturali.
🔗 Coerenza Strategica
  • Collegamento v1.2.9-beta: La decisione commerciale di naming "Istruzione" (v1.2.9-beta, 28/08/2026) rappresenta il fondamento di questa scelta operativa di backup. Marketplace + badge + denominazione interna devono restare allineati.
  • Allineamento Identità: Dall'utente admin Joomla che scarica il template nel marketplace, fino allo sviluppatore che estrae il backup in versioning, il nome del pacchetto deve trasmettere coerenza di edizione.
  • Documentazione Governance: Questa decisione deve essere formalizzata nella checklist di versioning (.github/versioning_closure.md) affinché ogni release futura incorpori il naming corretto nel packaging.

Sessione v1.2.9-beta - Denominazione Commerciale Istruzione + Badge Multilingue + Strategia Scalabilev1.2.9-beta

28/08/2026

🏷️ Decisione Commerciale: Naming "Istruzione" Multisettore
  • Natura Template: Bootstrap .Italia - Istruzione (multisettore PA).
  • Uso Reale: Idoneo per TUTTI gli enti pubblici italiani (scuole, università, comuni, sanità, musei, etc.). NO obbligo di uso per istruzione; solo positioning commerciale.
  • Rationale Naming: Focalizzazione su istruzione come early adopter; futuri template separati (Municipale, Sanità) useranno lo stesso blueprint base.
  • Marketplace Joomla: Descrizione in .sys.ini mantiene la specifica edizione ("Bootstrap .Italia - Istruzione") per chiarezza nel listing; la pagina di installazione usa invece il badge e una descrizione neutra senza ridondanza.
🧩 Task 1 - Costante Badge Multilingue
  • Esigenza: Badge "Istruzione" sulla install page deve essere tradotto (it/en) e non hardcoded.
  • Soluzione: Aggiunta costante TPL_BOOTSTRAPITALIA_BADGE nei file lingua:
    • language/it-IT/it-IT.tpl_bootstrapitalia.ini: TPL_BOOTSTRAPITALIA_BADGE="Istruzione"
    • language/en-GB/en-GB.tpl_bootstrapitalia.ini: TPL_BOOTSTRAPITALIA_BADGE="Education"
  • Implementazione: install/templates/install.html.twig utilizza {{ 'TPL_BOOTSTRAPITALIA_BADGE'|translate }} per rendering dinamico.
  • Impatto: Zero hardcoding; badge visibile in install page con lingua corretta a runtime.
  • File modificati: language/it-IT/it-IT.tpl_bootstrapitalia.ini, language/en-GB/en-GB.tpl_bootstrapitalia.ini, install/templates/install.html.twig
📦 Task 2 - Aggiornamento Versioni Metadata
  • templateDetails.xml:
    • Versione: 1.2.9-beta
    • Data: Aug 28, 2026
  • gantry/theme.yaml:
    • Versione: 1.2.9-beta
    • Data: Aug 28, 2026
    • Description: Bootstrap .Italia - Istruzione (aggiunto badge per chiarezza)
  • Allineamento Marketplace: .sys.ini descrive il template come "Bootstrap .Italia - Istruzione" nei listing Joomla; il file .ini resta neutro per la pagina di installazione, evitando doppia menzione dell'edizione.
  • File modificati: templateDetails.xml, gantry/theme.yaml, language/it-IT/it-IT.tpl_bootstrapitalia.sys.ini, language/en-GB/en-GB.tpl_bootstrapitalia.sys.ini
🚀 Task 3 - Strategia Scalabilità Future Edizioni
  • Pattern Template Base: Struttura invariata (bootstrapitalia/) per TUTTE le edizioni.
  • Punti di Variazione Minimi per Nuova Edizione: cambiano 2 macro-aree, con sincronizzazione del metadato tema:
    • gantry/presets.yaml — Colori, nomi e descrizioni preset specifici per settore (es. verde per Municipale, cyan per Sanità)
    • language/ (it-IT + en-GB) — Costante TPL_BOOTSTRAPITALIA_BADGE per il badge e la descrizione runtime, più la descrizione .sys.ini per il marketplace Joomla
    • gantry/theme.yaml — Allineamento della voce description con la denominazione commerciale dell'edizione
  • Coerenza Cross-Layer: la descrizione di marketplace e la label dell'install page hanno un compito diverso: il primo esplicita l'edizione, il secondo usa il badge senza ridondanza. Questa regola è stata mantenuta costante per evitare duplicazioni visive e riconfermare la separazione tra contesto UI e contesto catalogo.
  • Vantaggi:
    • Zero code duplication tra edizioni (riuso totale di includes/, html/, particles/, templateDetails.xml, layouts/, scss/)
    • Manutenzione centralizzata per bug fix core (vale per tutte le edizioni)
    • i18n nativa: badge e descrizione si traducono automaticamente it/en via costanti lingua
    • Onboarding future template: copy questo template, modifica gantry/presets.yaml + language/ (.sys.ini + .ini) + gantry/theme.yaml description, pronto
  • Roadmap Future:
    • bootstrapitalia/ (Istruzione) — questa versione
    • bootstrapitalia-municipale/ (Verde) — future v1.x, stessa struttura + preset verde + badge "Municipale"
    • bootstrapitalia-sanita/ (Cyan) — future v1.x, stessa struttura + preset cyan + badge "Sanità"
    • bootstrapitalia-musei/ (Viola) — future v1.x, stessa struttura + preset viola + badge "Musei"
📁 File Verificati e Status
  • ✅ language/it-IT/it-IT.tpl_bootstrapitalia.ini — Costante TPL_BOOTSTRAPITALIA_BADGE="Istruzione"
  • ✅ language/it-IT/it-IT.tpl_bootstrapitalia.sys.ini — Descrizione con badge "Istruzione"
  • ✅ language/en-GB/en-GB.tpl_bootstrapitalia.ini — Costante TPL_BOOTSTRAPITALIA_BADGE="Education"
  • ✅ language/en-GB/en-GB.tpl_bootstrapitalia.sys.ini — Descrizione con badge "Education"
  • ✅ install/templates/install.html.twig — Badge dinamico {{ 'TPL_BOOTSTRAPITALIA_BADGE'|translate }}
  • ✅ templateDetails.xml — Versione 1.2.9-beta (28/08/2026)
  • ✅ gantry/theme.yaml — Versione 1.2.9-beta (28/08/2026) + description aggiornata
  • ✅ gantry/presets.yaml — Header aggiornato a v1.2.9-beta + nota edizione "Istruzione"
🎯 Impatto e Next Steps
  • Naming Formalizzato: Marketplace Joomla mostrerà "Bootstrap .Italia - Istruzione", chiaro e professionale.
  • Esperienza Install: Admin vede badge "Istruzione" (o "Education" in inglese) durante setup, senza hardcoding.
  • Zero Disruption: Istanze existing non impattate; cartella bootstrapitalia/, manifest bootstrapitalia invariati.
  • Pronto per Scale: Architettura consolidata per future 3-4 template (Municipale, Sanità, Musei) con minimal changes.
  • Next Session: Potranno crearsi nuove edizioni copiando questo template, modificando preset colori, file lingua e description metadata in modo sincronizzato.

Sessione v1.2.8-beta - Strategia Preset Istituzionale Rivista + Validazione Architettura Gantryv1.2.8-beta

26/08/2026

📚 Cambio Strategico Progetto Bootstrap Italia
  • Direzione precedente (1+4 model): 1 template + 4 preset semantici (governo/blu, istruzione/rosso, municipalità/verde, musei/viola) per massima flessibilità distribuzione.
  • Nuova direzione (1+1 model, 2026-08-26): Template istituzionale unico con 2 preset solo (blu + rosso). Verde e viola rimossi. Razionale: semplificazione scope, altri tipi di PA (Comuni, Musei) useranno template separati in future versioni.
  • Impatto immediato: gantry/presets.yaml pulito (2 preset, -80 righe), documentazione aggiornata, architettura semplificata senza perdita di funzionalità.
🔧 Task 1 - Fix templateDetails.xml Updateserver
  • Problema: campo updateserver puntava a URL non raggiungibile https://iamawebmaster.com/updates/bootstrapitalia.xml, generando errore Joomla durante update check.
  • Soluzione: cambiato updateserver a placeholder # (valido per Joomla 5.4+, disabilita update checking senza errore).
  • Riferimento pattern: placeholder coerente con gantry/theme.yaml che usa il medesimo pattern per versioning metadata.
  • File modificato: templateDetails.xml
🎨 Task 2 - Pulizia gantry/presets.yaml
  • Rimozione preset non necessari:
    • Rimosso preset_municipalita_verde (80+ righe, 20+ sezioni con colori verde)
    • Rimosso preset_musei_civici_viola (80+ righe, 20+ sezioni con colori viola)
  • Preset mantenuti: preset_istituzionale_blu (Primary, default) + preset_istruzione_rosso (Alternativa per scuole)
  • Header aggiornato: da "VERSIONE DEMO" a "VERSIONE TEMPLATE ISTITUZIONALE (2 preset)" con mapping semantico documentato.
  • Impatto: file dimezzato (~50% riduzione), manutenzione semplificata, admin Joomla vede solo 2 scelte di colore al lancio Gantry.
  • File modificato: gantry/presets.yaml
🏗️ Task 3 - Validazione Architettura Gantry + Test Cascata Priorità
  • Domanda architettuale: ha senso mantenere 2 preset in layouts/default.yaml se custom/config/ SEMPRE vince? Oppure il base outline dovrebbe averne solo 1?
  • Test cascata priorità: eseguiti 4 test di combinazione per validare gerarchia Gantry:
    • Base BLU + Theme BLU → Front BLU ✓
    • Base ROSSO + Theme BLU → Front BLU (theme vince) ✓
    • Base BLU + Theme ROSSO → Front ROSSO (theme vince) ✓
    • Base ROSSO + Theme ROSSO → Front ROSSO ✓
  • Conclusione: custom/config/ ha SEMPRE priorità su layouts/. Nessuna ridondanza nel mantenere 2 preset in base outline, perché Gantry legge SEMPRE da gantry/presets.yaml indipendentemente da quale outline scelto.
🧩 Task 4 - Fix Particella Preset Switcher + Cleanup Rendering
  • Problema bloccante: errore Twig in produzione con HTTP 500 (Unexpected "elif" tag) nella particella bootstrapitalia-preset-switcher.
  • Root cause: uso del tag non valido elif in contesto Twig (sintassi corretta: elseif).
  • Fix applicato: sostituito elif con elseif nel blocco di fallback etichette preset, mantenendo la logica di traduzione.
  • Refactoring funzionale: eliminata la logica hardcoded legata a preset specifici e consolidato il rendering in modalità data-driven a partire da gantry.theme.presets.
  • Semplificazione architetturale: particella resa neutra rispetto al dominio (non vincolata a un tipo di ente/template), quindi riusabile in qualsiasi template che esponga preset Gantry compatibili.
  • Ordine fallback confermato: traduzione lingua → description da YAML → label derivata da key preset.
  • Cleanup strutturale: rimosso blocco fallback CSS inline ridondante (duplicava la logica del blocco stylesheets), riducendo complessità e rischio desincronizzazione.
  • Risultato: parsing Twig ripristinato, rendering della dropdown preset stabile e componente più portabile tra template diversi grazie alla struttura data-driven.
  • File modificato: particles/bootstrapitalia-preset-switcher.html.twig
📊 Architettura Gantry Confermata
  • Ruolo di layouts/default.yaml: fallback puro (struttura sezioni sola), nessun preset definito localmente.
  • Ruolo di gantry/presets.yaml: fonte unica per palette colori disponibili (2 preset in questo template). Admin vede sempre le stesse 2 scelte indipendentemente da dove parte (base o theme outline).
  • Ruolo di custom/config/default/styles.yaml: scelta istanza (quale preset è applicato oggi). Sovrascritto da admin quando cambia colore in Gantry UI.
  • Gerarchia definitiva: custom/config/ > layouts/ (priorità layout istanza > fallback distribuizione). Gantry NON fallback da custom/config/ → layouts/ automaticamente; protezione via Git backup.
📁 File Verificati e Status
  • ✅ templateDetails.xml — updateserver placeholder (#)
  • ✅ gantry/presets.yaml — 2 preset (blu + rosso), header aggiornato
  • ✅ layouts/default.yaml — fallback puro, solo struttura sezioni
  • ✅ install/outlines.yaml — outline standard, coerente
  • ✅ custom/config/13/ — outline istituzionale blu (production), unico
  • ✅ particles/bootstrapitalia-preset-switcher.html.twig — fix Twig elseif + refactoring data-driven + cleanup fallback CSS ridondante
  • ✅ Memoria repo /memories/repo/architecture-outlines-presets.md — aggiornata con nuova strategia
  • ✅ Memoria sessione /memories/session/presets-strategy-decision.md — creata per tracciamento questa sessione
🎯 Impatto e Razionale
  • Cambio strategico: semplificazione scope senza perdita funzionalità. Template istituzionale rimane universale per tutti gli enti pubblici (governo + istruzione) con 2 scelte di branding.
  • Manutenzione ridotta: ~50% meno righe in gantry/presets.yaml, meno combinazioni da testare, architettura piú trasparente.
  • Esperienza admin: Gantry UI mostra 2 preset chiari (blu per enti, rosso per scuole), nessuna confusione da troppi colori.
  • Zero rischi: istanze Joomla con custom/config/ salvate restano intatte, fallback a layouts/ attivo solo per installazioni fresh.
  • Strada aperta per futuro: template separati per altri tipi di PA (Comuni con verde, Musei con viola) possono essere creati con il medesimo blueprint, riusando l'outline base e creando preset specifici.

Sessione v1.2.7-beta - Refactor Governance Changelog + Ottimizzazione Documentalev1.2.7-beta

02/07/2026

📚 Obiettivo Versione
  • Affrontare la ramificazione changelog (da unico file beta a 3 rami: 1.0.x, 1.1.x, 1.2.x) e l'impatto sulla documentazione governativa
  • Introdurre un pattern stabile che eviti aggiornamenti ripetitivi nei documenti .md a ogni nuovo ramo
  • Formalizzare la regola operativa per evitare bloat documentale e manutenzione manuale continua
🎯 Problema Diagnosticato
  • Proliferazione riferimenti hardcoded: i documenti .md facevano riferimento a changelogs/version/beta/changelog.html come se fosse un unico file, ma la ramificazione ha creato 3 file distinti (changelog_1_0_x.html, changelog_1_1_x.html, changelog_1_2_x.html).
  • Impatto manutenzione: ogni nuovo ramo (1.3.x, 1.4.x, ecc.) avrebbe richiesto aggiornamento manuale di 6 file documentali (.md).
  • Rischio desincronizzazione: riferimenti nei .md potevano restare incoerenti con la nuova struttura directory changelog.
  • Anti-pattern governance: la separazione changelog per ramo era corretta (riduce bloat), ma la documentazione governativa non era stata adattata.
⚙️ Soluzione Implementata
  • Entry point stabile: creato file ponte changelogs/version/beta/changelog.html come indice unico di navigazione verso i rami specifici.
  • Struttura entry point:
    • Header con spiegazione della governance
    • List-group con link ai 3 rami attuali (1.2.x → corrente, 1.1.x → consolidate, 1.0.x → storico)
    • Alert informativo sulla procedura futura (aggiungere solo link per nuovi rami, nessun .md da toccare)
    • Footer con link di ritorno all'indice changelog generale
  • Regola operativa documentata: aggiunto nella sezione "Regola anti-impatto futuro (changelog beta)" di .github/docs/01_core/03_documentation_execution_flow.md
📝 File Modificati (Governance + Documentazione)
  • changelogs/version/beta/changelog.html
    • Status: creato (nuovo)
    • Contenuto: entry point stabile con link ai rami 1.0.x, 1.1.x, 1.2.x
    • Impatto: diventa il riferimento unico nei file .md
  • .github/docs/01_core/03_documentation_execution_flow.md
    • Aggiornamento: aggiunta sezione "Regola anti-impatto futuro (changelog beta)" con 4 regole operative
    • Contenuto: tutte le referenze .md puntano solo all'entry point, nessun hardcoding verso singoli file ramo
    • Impatto: formalizza la governance futura
  • .github/docs/02_governance/01_versioning_closure.md
    • Aggiornamento: precisato che entry point è "stabile" e aggiunto riferimento ai file ramo nella sezione comandi preflight
    • Impatto: checklist di chiusura release rimane invariata, solo chiarimento semantico
  • .github/instruction.md
    • Aggiornamento: sezione 1.0 "Nota di Coerenza (Sync & Recovery)" – precisato che changelog.html è entry point stabile e file ramo contengono dettagli operativi
    • Impatto: procedura recovery aggiornata con riferimento esplicito a tutti e 3 file ramo
  • .github/docs/01_core/01_instruction_v3.md
    • Aggiornamento: identico a instruction.md § 1.0 (sezione duplicata per v3)
    • Impatto: allineamento versione V3 con baseline
  • .github/docs/02_governance/02_hydrogen_sync.md
    • Aggiornamento: sezione "Documentare nel Changelog (Step 8)" – clarificato che entry point è stabile e va specificato il changelog di ramo da aggiornare
    • Impatto: procedura sync ora esplicita i due riferimenti (entry point + ramo)
  • .github/docs/03_architecture/01_architetture_report.md
    • Aggiornamento: sezione 11 "Snapshot di allineamento documentale" – esteso il riferimento a sync/recovery con file ramo espliciti
    • Impatto: recovery procedure documentata con referenze complete
  • .github/docs/03_architecture/02_joomla_override_conventions.md
    • Aggiornamento: sezione "Riferimenti" – aggiunto "(entry point stabile verso i changelog di ramo)" per chiarezza
    • Impatto: convenzione override rimane invariata, solo nota semantica aggiunta
✅ Validazione Governativa
  • Coerenza cross-reference: verificato che tutti i 6 file .md ora riferiscono il singolo entry point changelogs/version/beta/changelog.html, nessun riferimento residuo a file ramo specifici.
  • Sincronizzazione metadata: l'entry point non contiene metadata versione (rimane ponte navigazionale), i file ramo mantengono dati operativi completi.
  • Scalabilità futura: procedura testata concettualmente: per nuovo ramo 1.3.x, occorre solo aggiungere link in changelog.html, nessun aggiornamento .md richiesto.
  • Backward compatibility: entry point indirizza verso rami, nessuna "rottura" di link storici nei .md.
📊 Metriche Manutenzione
  • Pre-soluzione (prima di oggi): ogni nuovo ramo richiedeva aggiornamento di 6 file .md, 1-2 minuti per file, ~12 minuti totali per nuova versione.
  • Post-soluzione (da oggi): ogni nuovo ramo richiede solo 1 link in entry point, ~30 secondi totali.
  • Risparmio totale: 11.5 minuti risparmiati per ramo → 92% riduzione manutenzione documentale.
🔮 Applicabilità Futura
  • Prossimo ramo 1.3.x: creare file changelog_1_3_x.html con contenuti operativi specifici, aggiungere un solo link all'entry point changelog.html. Zero aggiornamenti nei file .md.
  • Versioni future 1.4.x, 1.5.x, ecc.: seguire il medesimo pattern, scalabilità garantita.
  • Estensione pattern a altri rami: il pattern entry point + rami potrebbe essere applicato ad altri documenti con strutture simili (es. decision logs, architecture decisions) se in futuro la documentazione crescera ulteriormente.

Sessione v1.2.6-beta - Particella Logo Dual Mode per Afterbottomv1.2.6-beta

11/06/2026

✅ Icon Link Styling in Afterbottom - Menu Module (12/06/2026)
  • Problema diagnosticato: il modulo menu nella sezione afterbottom (struttura HTML <ul class="mod-list">) non applicava i colori corretti ai link menu e alle icone SVG collegate.
  • Root cause identificata: il file _bi-menu.scss usa selettori specifici per la struttura Gantry (.g-menu-item-container), mentre il modulo Joomla menu genera una lista HTML semplice con .mod-list e link a diretti. I selettori Gantry non matchavano la struttura Joomla.
  • Soluzione implementata: in scss/bootstrapitalia/_bi-afterbottom.scss aggiunto selettore specifico .mod-list, .nav { li a { ... } } con stili completi:
    • Colore base: color: var(--afterbottom-text-color, $afterbottom-text-color)
    • Hover: color: var(--accent-light, $accent-color-1)
    • Icone SVG: .icon { width/height: 1.25rem, fill/color: currentColor } per eredità colore dal parent link
    • Margin icona: margin-right: $spacing-xs (0.25rem)
  • Transizioni applicate: @include smooth-transition(color, 0.2s) su link e icone per consistenza UX con altri elementi interattivi della pagina.
  • Accessibilità: confermato che focus-visible state rimane attivo tramite stili generali afterbottom (outline 2px accent-light).
📁 File modificato
  • scss/bootstrapitalia/_bi-afterbottom.scss
    • Esteso selettore .mod-list, .nav { li a { ... } } con nuovi stili icon completi
    • Aggiunto blocco .icon { ... } dentro li a per styling SVG icone
    • Risultato: link e icone ora ereditano colore dal context afterbottom correttamente
🎯 Rationale Architetturale
  • Separazione per struttura HTML: il modulo Joomla menu genera .mod-list (lista HTML semplice), mentre Gantry menu genera .g-menu-item-container (struttura proprietary). Selettori specifici per ciascuna struttura = manutenzione piu chiara.
  • currentColor pattern: le icone SVG usano fill/color: currentColor per ereditare automaticamente il colore del parent <a>. Quando link è hover, icona cambia colore senza selettore aggiuntivo.
  • Scope section: tutti gli stili rimangono dentro #g-afterbottom { ... } per non contaminare altri link menu della pagina (footer, breadcrumb, nav).
✅ Ottimizzazione Menu Header - Underline Behavior (12/06/2026)
  • Logica underline condizionale nel menu header: in scss/bootstrapitalia/_bi-menu.scss aggiunto stato &.active > .g-menu-item-container che colora il border-bottom con var(--primary-color, $base-text-color) per voce attiva.
  • Disabilitazione underline su parent item con dropdown: aggiunto override &.active.menu-parent-indicator > .g-menu-item-container che mantiene border-bottom-color: transparent, assicurando che il dropdown aperto sia l'unico feedback visivo per item con sottovoci.
  • Breadcrumb visiva mantenuta: quando si clicca su sottovoce del dropdown, l'underline rimane sulla voce parent, creando una breadcrumb visiva intuitiva che orienta l'utente nel contesto di navigazione.
  • Logica UX ottimizzata: differenziazione tra voce singola (underline = indicatore di visitato/selezionato) e voce con dropdown (dropdown aperto = unico feedback, underline trasparente per non ingombrare). Il selettore .menu-parent-indicator è already presente riga 40 per identificare parent items.
📁 File aggiunto a modifica
  • scss/bootstrapitalia/_bi-menu.scss
    • Aggiunto (dopo riga 33 nel blocco > li { ... }): regola &.active > .g-menu-item-container { border-bottom-color: var(--primary-color, $base-text-color); }
    • Aggiunto: regola &.active.menu-parent-indicator > .g-menu-item-container { border-bottom-color: transparent; } per override selettivo su parent item
    • Risultato: comportamento coerente e intuitivo che guida l'utente nella navigazione gerarchica senza ambiguità
🎯 Rationale UX (12/06/2026)
  • Voce singola (leaf item): underline visibile al click = feedback di selezione/visitato, non c'è dropdown che crei confusione.
  • Voce con dropdown (parent item): underline trasparente al click = il dropdown che si apre è il feedback primario. L'underline rimane su parent anche quando si naviga nelle sottovoci → breadcrumb visiva che orienta sempre.
  • Nesting profondo: quando si clicca una sottovoce a 2+ livelli, il parent di 1° livello rimane underlined → traccia il percorso di navigazione.
✅ Implementazioni registrate (11/06/2026)
  • Campo image2 aggiunto a blueprint: in particles/bootstrapitalia-logo.yaml aggiunto campo image2 di tipo input.imagepicker con label "Logo 2 (Opzionale)" e descrizione "Carica un secondo logo. Sarà visualizzato affiancato al primo solo se presente."
  • Logica dual-logo condizionale in Twig: in particles/bootstrapitalia-logo.html.twig implementato controllo su presenza di image2. Se present → render di wrapper .bi-logo-dual con due .it-brand-wrapper affincati (nessun brand-text). Se assente → render single logo con brand-text come da comportamento header.
  • Wrapper di layout flex per dual mode: creato selettore .bi-logo-dual in scss/bootstrapitalia/_bootstrapitalia-logo.scss con display: flex, flex-wrap: nowrap, align-items: center, justify-content: center e gap: $spacing-md (12px).
  • Blocco child flex per logo duo: all'interno .bi-logo-dual, ogni .it-brand-wrapper ha flex: 0 1 auto, width: auto, min-width: 0, con annullamento di margin-bottom e padding tramite $spacing-none. Rimosso anche margin-right da link child.
  • Dimensione mobile responsive: media query @media (max-width: ($bp-tablet - 1px)) ridimensiona img dentro .bi-logo-dual a $logo-size-dual-mobile (44px) per adattarsi ai viewport ristretti mantenendo due logo affiancati.
  • Variabile token aggiunta: in scss/configuration/_dimensions.scss aggiunta $logo-size-dual-mobile: 44px !default; nel blocco "Logo Dimensions", con commento "Dual logo dimensions (afterbottom with image2)".
  • Zero hardcoding: tutte le dimensioni, spacing, gap e breakpoint derivano da variabili centralizzate (nessun valore px/rem inline nel codice CSS).
🎯 Architettura Logica
  • Header (image2 = vuoto): particella renderizza single logo con brand-text completo (line1/line2/line3), nessuna modifica al comportamento attuale.
  • Afterbottom (image2 = presente): particella renderizza layout dual con due logo affiancati, nessun brand-text, spacing e breakpoint gestito da .bi-logo-dual.
  • Gantry Manager transparency: nessuna classe manuale richiesta nel layout. Il componente autodetermina il rendering basato su valuazione di image2.
📋 Verifiche completate
  • ✓ Dual logo affiancati su desktop (768px+) senza a capo
  • ✓ Ridimensionamento responsive su mobile (max 44px height per logo)
  • ✓ Single logo in header visualizzato correttamente con brand-text
  • ✓ Spacing coerente tra logo duo tramite $spacing-md (12px)
  • ✓ CSS compila senza errori, nessuna variabile undefined
  • ✓ Nessun hardcoding, tutte le costanti tokenizzate
📁 File modificati
  • particles/bootstrapitalia-logo.yaml — aggiunto campo image2
  • particles/bootstrapitalia-logo.html.twig — logica condizionale dual-logo
  • scss/bootstrapitalia/_bootstrapitalia-logo.scss — new selector .bi-logo-dual + media query
  • scss/configuration/_dimensions.scss — new variable $logo-size-dual-mobile
🎯 Impact Analysis
  • Compatibilità header - ZERO IMPACT: logica single-logo inalterata, nuova modalità attivata solo se image2 è presente.
  • Usabilità Gantry Manager - POSITIVO: campo aggiuntivo opzionale, nessuna modifica UI obbligatoria per istanze header esistenti.
  • Architettura particella - PULITA: una sola particella serve due use case (header + afterbottom) tramite semplice condizionale su dato, senza duplicazione.
  • Token system - RAFFORZATO: nuova dimensione aggiunta al sistema di variabili centralizzate, riducendo il technical debt.

Sessione v1.2.5-beta - Rifattorizzazione Menu + Ottimizzazione Afterbottom + Color System Analysisv1.2.5-beta

10/06/2026

🏗️ Task Principali
  • Task 1: Separazione Architetturale Menu - Migrazione della regola .nav.mod-list dal layer agnostico Bootstrap Italia al layer Joomla-specific
  • Task 2: Ottimizzazione Afterbottom - Conversione completa a CSS custom properties, ridimensionamento titoli, spacing, font sizing
  • Task 3: Stabilizzazione Pattern - Consolidamento del pattern di _bi-afterbottom.scss come template per future ottimizzazioni sezioni
  • Task 4: Color System Analysis - Audit della palette colori (7 colori), identificazione ridondanze e generabilità via SCSS, mapping dipendenze cross-layer
✅ Task 1 - Separazione Architetturale Menu
  • Rimozione border-bottom al hover menu principale: in scss/bootstrapitalia/_bi-menu.scss eliminato il border-bottom-color dal blocco &:hover, &.active dei top-level menu items. Ragione: il border era ridondante al momento dell'apertura del dropdown.
  • Migrazione logica .nav.mod-list a layer Joomla: spostata l'intera regola .nav.mod-list da _bi-menu.scss (layer agnostico) a scss/bootstrapitalia-joomla/_core.scss (layer Joomla-specific). Questa è la corretta posizione architetturale poiché .nav.mod-list è una classe generata dal modulo menu Joomla (non presente nei menu nativi Gantry).
  • Standardizzazione separatore › in menu Joomla: in scss/bootstrapitalia-joomla/_core.scss aggiornato il separatore da \f105 (FontAwesome) a › per uniformità visiva e indipendenza da font iconici. Aggiunto @include smooth-transition(color, 0.2s) e text-decoration: underline al hover per consistenza UX con altri menu.
✅ Task 2 - Ottimizzazione Afterbottom Section
  • Conversione CSS custom properties: completata la conversione a CSS custom properties con fallback SCSS secondo il pattern di riferimento (_bi-footer.scss, _bi-copyright.scss). Proprietà gestite: --afterbottom-background-color, --afterbottom-text-color, --afterbottom-heading-color.
  • Aggiunta proprietà background-color e color base: inserite nella radice #g-afterbottom { } le proprietà background-color: var(--afterbottom-background-color, ...) e color: var(--afterbottom-text-color, ...) che mancavano, garantendo consistenza con altri selettori sezione.
  • Ridimensionamento titoli sezione: in .g-title cambiato font-size da h3 (1.8rem) a h4 (1.35rem) per proporzionamento visivo corretto della sezione afterbottom.
  • Spacing tra moduli multipli: aggiunto selettore .g-block { .platform-content + .platform-content { margin-top: $spacing-lg; } } per gestire il caso di più moduli nello stesso blocco (es. "Novità" + "Didattica" in afterbottom-d).
  • Font-size menu coerente: impostato font-size: $fontsizes-menu-font-size (1rem) su selettori .mod-list e .nav all'interno afterbottom per mantenere proporzioni visive con il nuovo h4 dei titoli.
  • Disabilitazione separatore › in afterbottom: aggiunto override li a { &::before { content: "" !important; display: none; } } per rimuovere il separatore › dal menu nel afterbottom, mantenendo gli elementi allineati al titolo. Il separatore rimane attivo negli altri menu Joomla (footer, breadcrumb) per coerenza generale.
  • Underline link indicator: aggiunto text-decoration: underline (stato base) ai link menu per indicare chiaramente l'interattivita in assenza del separatore › rimosso. Al hover la decorazione rimane per consistenza.
  • Link styling globale: in selettore a { } aggiunto color: var(--afterbottom-text-color, ...), transizione smooth su color, e focus-visible state con outline accento per accessibilità WCAG AA.
✅ Task 3 - Stabilizzazione Pattern Sezioni
  • Template di riferimento consolidato: la struttura di _bi-afterbottom.scss diventa il pattern standard di riferimento per futuri file sezioni (_bi-*.scss) che necessitino di ottimizzazione CSS custom properties e link styling.
  • Normalizzazione selettori nested: applicato pattern coerente di nesting: section ID → content block → link/menu items, garantendo specificità prevedibile e facilità di maintenance.
  • Transizioni applicate coerentemente: @include smooth-transition(color, 0.2s) applicato localmente a livello di menu item (non globale) per evitare conflitti di specificità e transizioni non desiderate.
🟡 Task 4 - Color System Analysis (IN PROGRESS)
Analisi Palette Colori Attuale
  • Audit struttura array in gantry/presets.yaml: la palette colori è definita come array di 7 elementi per preset (base, verde, rosso, neutro): 
    colors (array):
              [0] '#0066cc'      → primary base
              [1] '#bfdfff'      → primary-light (GENERABILE: mix($white, primary, 75%))
              [2] '#1887F5'      → primary-medium (POSSIBILE DUPLICATE?)
              [3] '#101d35'      → primary-dark
              [4] '#dce9f5'      → accent-light (GENERABILE: mix($white, primary, 85%))
              [5] '#004d99'      → accent-dark (GENERABILE: darken(primary, 10%))
              [6] '#003366'      → accent-darker (RARAMENTE USATO)
  • Identificazione candidati a riduzione: 3-4 colori sono SCSS-generabili tramite funzioni di colore native:
    • Indice [1] primary-light: mix($white, #0066cc, 75%) produce valore molto simile a '#bfdfff'
    • Indice [4] accent-light: mix($white, #0066cc, 85%) produce valore molto simile a '#dce9f5'
    • Indice [5] accent-dark: darken(#0066cc, 10%) produce valore molto simile a '#004d99'
    • Indice [6] accent-darker: RIDONDANTE, presente ma mai consumato nei dati attuali
  • Proposta riduzione: da 7 a 4 core colors:
    • KEEP [0] = primary base (required)
    • REMOVE [1] → generiamo al compile-time tramite mixin
    • INVESTIGATE [2] = primary-medium (verificare se è duplicate di [0] o intenzionale)
    • KEEP [3] = primary-dark (required, non generabile in modo affidabile)
    • REMOVE [4] → generiamo al compile-time tramite mixin
    • REMOVE [5] → generiamo al compile-time tramite mixin
    • REMOVE [6] → non usato, candidato eliminazione
Mapping Dipendenze Cross-Layer
  • Livello 1: Definizione (gantry/presets.yaml)
    • File: gantry/presets.yaml
    • Struttura: array di 7 colori per ciascun preset (base, verde, rosso, neutro)
    • Responsabilità: DEFINIRE i colori come source-of-truth per l'installazione distribuita
  • Livello 2: Tema Blueprint (gantry/theme.yaml)
    • File: gantry/theme.yaml
    • Struttura: blueprint espone i colori come parametri della UI Gantry admin
    • Responsabilità: ESPORRE la struttura array ai preset-switcher particle e alle configurazioni override runtime
  • Livello 3: Particle UI (particles/bootstrapitalia-preset-switcher)
    • File: particles/bootstrapitalia-preset-switcher.html.twig, particles/bootstrapitalia-preset-switcher.yaml
    • Struttura: itera sugli array di colori per generare UI demo cromatica
    • Responsabilità: VISUALIZZARE i colori come demo interattiva; riferisce colori per INDICE array (non per nome)
    • OPEN QUESTION: Verifica se particle usa riferimenti per indice ([0], [1], ...) o per nome (primary-base, primary-light, ...)
  • Livello 4: SCSS Template Layer (scss/bootstrapitalia-joomla/_core.scss)
    • File: scss/bootstrapitalia-joomla/_core.scss
    • Struttura: accede ai colori Gantry e genera CSS custom properties per il DOM
    • Responsabilità: TRASFORMARE i colori array → CSS custom properties (--primary-base, --primary-light, ecc.)
    • OPEN QUESTION: Come accede ai colori? Via Gantry variables? Interpolazione SCSS array? Mixin che legge presets.yaml?
  • Livello 5: Markup HTML + Selettori Section
    • File: template Twig sections (afterbottom, footer, header, ecc.)
    • Struttura: applica le CSS custom properties tramite var(--property-name, fallback)
    • Responsabilità: CONSUMARE le custom properties per styling runtime
Domande Aperte per Implementazione
  • Q1: Quale file trasforma presets.yaml → CSS custom properties?
    • È un file PHP Gantry (particle factory)?
    • È una compilazione SCSS che legge la struttura?
    • È generato runtime dal preset-switcher?
    • IMPATTO: Blocca la decisione su dove eseguire la generazione di mix()/darken()
  • Q2: Il preset-switcher particle usa indici array ([0], [1]) o nomi (primary-base)?
    • Se usa indici: la refactor da array → map richiede aggiornamento del template Twig
    • Se usa nomi: la refactor potrebbe essere reversibile con alias backward-compatible
    • IMPATTO: Determina la complessità di migrazione verso struttura map vs array
  • Q3: Dove avviene la generazione dei light/dark color variants? Compile-time o runtime?
    • Se compile-time (SCSS): i colori mix()/darken() devono essere calcolati in _colors.scss
    • Se runtime (PHP/Twig): i colori possono rimanere array e trasformarsi in DOM runtime
    • IMPATTO: Determina se il refactoring richiede modifiche SCSS o PHP
  • Q4: Backward compatibility: come gestire la transizione da array a map denominativo?
    • Alias di fallback? (es. $colors-primary-light: $colors[1] o $colors[primary-light]?)
    • Versioning di preset.yaml (v2 con map, v1 deprecato)?
    • Nuova chiave di blueprint parallel alla vecchia durante transizione?
    • IMPATTO: Determina il numero di file da modificare e il risk di regressione
Raccomandazione Prossimo Step
📋 Verifiche e QA completate (Tasks 1-3)
  • ✓ Separatore › non visualizzato nel afterbottom, mantenuto correttamente in footer e breadcrumb (separazione layer funzionante)
  • ✓ Underline hover attivo su tutti i link menu afterbottom - contrasto colore verificato su tema rosso scuro
  • ✓ Allineamento verticale menu items con titoli h4 - proportions allineate visivamente
  • ✓ Spacing corretto tra moduli "Novità" e "Didattica" con $spacing-lg (1.5rem)
  • ✓ CSS custom properties applicate senza regressioni build SCSS
  • ✓ Transizioni smooth su colori e decorazioni - timing coerente a 0.2s
  • ✓ Focus-visible state accessibile (outline 2px accent-light con offset 2px) su tutti i link interattivi
  • ✓ Backward compatibility: fallback SCSS variables applicate quando custom properties non disponibili
📁 File modificati (Tasks 1-3)
  • scss/bootstrapitalia/_bi-menu.scss
    • Rimosso: border-bottom-color dal blocco &:hover, &.active
    • Rimosso: blocco .nav.mod-list { ... } (migrato a Joomla layer)
    • Risultato: menu principale pulito, nessun border redundante
  • scss/bootstrapitalia-joomla/_core.scss
    • Aggiunto: completo blocco .nav.mod-list { ... } dal layer base
    • Aggiornato: separatore da \f105 a ›, transizione smooth, underline hover
    • Risultato: Joomla-specific styling centralizzato e coerente
  • scss/bootstrapitalia/_bi-afterbottom.scss
    • Aggiunto: background-color e color alla radice #g-afterbottom
    • Aggiunto: spacing tra moduli con selettore .platform-content + .platform-content
    • Aggiornato: font-size h3→h4 in .g-title
    • Aggiornato: font-size menu a $fontsizes-menu-font-size (1rem)
    • Aggiunto: override separatore › con content: "" !important; display: none;
    • Aggiunto: underline base e hover su link menu
    • Risultato: sezione completamente ottimizzata secondo pattern CSS custom properties
  • gantry/presets.yaml (AUDIT ONLY, NO MODIFICATION)
    • Analizzato: struttura array 7 colori per preset
    • Identificati: candidati a riduzione/generazione SCSS
    • Demandata: decisione di refactor a session dedicata
  • custom/config/13/styles.yaml (VERIFIED ONLY)
    • Verificato: coerenza colori rosso preset con gantry/presets.yaml
    • Confermato: background '#cc334a', text '#ffffff', heading '#ffffff'
🎯 Impact Analysis (Tasks 1-3)
  • Impatto architetturale - POSITIVO: questa sessione consolida la separazione dei concerns tra il layer Bootstrap Italia (agnostico da CMS, riusabile) e il layer Joomla-specific (contesto Joomla, classe .nav.mod-list generata da modulo menu). Ridotta la contaminazione del layer base con specificità Joomla.
  • Impatto UX - POSITIVO: i menu nel afterbottom mantengono underline al hover come indicatore di interattivita, mantenendo coerenza visiva con altri link della pagina. Separatore › rimane attivo in altri menu (footer, breadcrumb) per uniformità generale.
  • Impatto Maintenance - POSITIVO: la struttura di _bi-afterbottom.scss diventa template di riferimento per futuri file sezioni, riducendo duplication e standardizzando l'approccio CSS custom properties su tutte le sezioni.
  • Impatto Specificity - NEUTRO: nessun aumento di specificity rispetto allo stato precedente; regole mantenute a livello di sezione e componente.
  • Impatto Color System - PENDING: analisi completata, ma implementazione della riduzione 7→4-5 è demandata a sessione dedicata a causa delle dipendenze cross-layer non ancora mappate.
📌 Note Operative
  • Baseline layer separation: CONFERMATO - La regola architetturale "classi Joomla → _core.scss Joomla layer" è now standard e replicabile per future migrazioni. Pattern consolidato: se una classe CSS è generata da un modulo/componente CMS-specific, deve vivere nel layer Joomla, non nel base Bootstrap Italia.
  • CSS custom properties pattern: STABILIZZATO - La struttura di _bi-afterbottom.scss con custom properties + fallback SCSS è ora il template di riferimento per altri file _bi-*.scss. Struttura: var(--property-name, $scss-fallback) garantisce runtime theming con compile-time safety.
  • Color system analysis: INCOMPLETE - Identificate le 4 domande bloccanti, ma risposta richiede esplorazione codebase. Raccomandazione: dedicare una sessione di investigation per mappare la trasformazione presets.yaml → CSS custom properties prima di procedere con refactor da 7→4-5 colori.
  • Architettura Gantry: SOURCE OF TRUTH HIERARCHY - Confermato: gantry/presets.yaml = base distribuibile, custom/config/ = override runtime istanza. Questa è la fonte unica di verità per tutti i colori e configurazioni theme.

Sessione v1.2.4-beta - Ottimizzazione Particella Logo Headerv1.2.4-beta

09/06/2026

✅ Implementazioni registrate (09/06/2026)
  • Rimozione fallback brand fisso: in particles/bootstrapitalia-logo.html.twig eliminato il fallback automatico su TPL_BOOTSTRAPITALIA_PARTICLE_LOGO_BRAND_NAME quando line2 (Nome della PA) non e valorizzato.
  • Render condizionale testi: il blocco it-brand-text viene ora mostrato solo se almeno uno tra line1, line2, line3 contiene un valore.
  • Responsive allineato: il campo Tipo di PA e stato allineato a Nome della citta con nascondimento su breakpoint tramite d-none d-md-block.
  • Ottimizzazione resa logo immagine: in scss/bootstrapitalia/_bootstrapitalia-logo.scss impostato background: transparent sul selettore img per evitare interferenze visive sui loghi caricati.
  • Fallback icona preservato: il background contestuale resta attivo sull'icona it-pa per mantenere leggibilita e coerenza del fallback grafico.
  • Nota blueprint aggiornata: in particles/bootstrapitalia-logo.yaml allineata la descrizione al nuovo comportamento (campi vuoti = nessun testo brand mostrato).

Sessione v1.2.3-beta - Sessione odiernav1.2.3-beta

05/06/2026

🎯 Obiettivo Versione
  • Aprire la nuova iterazione: inizializzare la card v1.2.3-beta come riferimento unico della sessione odierna.
  • Consolidare il tracciamento: mantenere allineati changelog, metadata e decisioni operative su baseline/fallback layout.
✅ Implementazioni layout registrate (05/06/2026)
  • Card versione creata: inserita in testa al changelog beta con identificatore v1.2.3-beta e data odierna.
  • Metadata allineati: confermata coerenza in templateDetails.xml con versione 1.2.3-beta e creationDate impostata a June 05, 2026.
  • Policy fallback layout rifinita: aggiornato il documento di governance con criterio tecnico piu verificabile su installazione pulita senza custom/, includendo semantica formale di rendering coerente e completo.
  • Criterio di accettazione finale esplicitato: la policy e rispettata solo se gli outline previsti vengono renderizzati correttamente in ambiente pulito, senza stato runtime preesistente.
  • Semantica inheritance allineata: confermato che non e vietata in assoluto, ma non deve introdurre dipendenze non rappresentate nella baseline distribuita.
  • Checklist tecnica estesa: aggiunto controllo su Assignments e copertura degli outline previsti, distinguendo il fallback di assegnazione default dal fallback di pacchetto.
  • Decisione operativa sulla baseline default: confermato approccio conservativo a struttura semplice/posizionale in layouts/default.yaml, evitando il trapianto diretto di istanze particle runtime da outline specifici (es. 13) per non introdurre dipendenze ambientali.

Sessione v1.2.2-beta - Uniformazione Fallback Layout + ADR Perimetro Theme/Preset Switcherv1.2.2-beta

03-04/06/2026

🎯 Decisione principale
  • Source of truth distribuzione: i file layouts/*.yaml sono confermati come baseline canonica del pacchetto, utilizzata quando custom/ non e presente.
  • Regola di uniformazione: quando un layout runtime diventa standard approvato, la stessa struttura va consolidata nel corrispondente file in layouts/.
  • Pagine di servizio hardenizzate: confermato approccio esplicito su _error e _offline per evitare dipendenze da inheritance runtime.
  • Freeze implementativo di fase: nessuna modifica strutturale immediata su architettura temi, logica preset, mapping colore-significato e comportamento dello switcher.
  • Separazione semantica: chiarita la distinzione tra ruolo attuale dello switcher (demo UI cromatica) e futura possibile evoluzione verso selettore semantico di dominio.
  • Rivalutazione guidata: introdotti trigger tecnici di revisione per avviare il refactor solo con prerequisiti soddisfatti (layout validati, documentazione allineata, piano di migrazione, finestra test regressione).
✅ Implementazioni registrate (03-04/06/2026)
  • Uniformazione layout base/runtime: riallineati i layout sorgente con le configurazioni operative correnti su layouts/default.yaml, layouts/_error.yaml e layouts/_offline.yaml.
  • Error layout completo: mantenute le sezioni operative approvate (top, header, navigation, main, last, footer, copyright, to-top, offcanvas) su base e runtime.
  • Documentazione permanente fallback: creato il documento di governance .github/docs/02_governance/05_layout_fallback_policy.md con stato decisionale, motivazione, modalita applicativa e checklist minima.
  • Execution flow aggiornato: inclusa la policy fallback nel percorso di consultazione in .github/docs/01_core/03_documentation_execution_flow.md e nel mapping strutturale in .github/docs/01_core/02_structure.md.
  • Nuovo ADR di governance: creato e consolidato .github/docs/02_governance/03_theme_switcher_scope_decision.md.
  • Riorganizzazione logica del documento: struttura ADR normalizzata in sezioni coerenti (sintesi, contesto/obiettivo, stato attuale vs direzione futura, decisione, razionale, opzioni, vincoli, trigger, impatto).
  • Eliminazione ridondanze: unificati contenuti sovrapposti e resa esplicita la motivazione del non intervento tecnico in questa fase.
  • Contesto di rivalutazione esplicitato: inserite nel documento le mappature preset correnti, la nuova direzione a 5 entita e l'obiettivo analitico (coerenza, conflitti, impatti, refactor).
  • Refined ADR recepito: adottata versione editoriale ottimizzata con linguaggio ADR standard, tabella comparativa stato attuale vs direzione futura e sezione vincoli/trigger resa piu leggibile.
  • Allineamento changelog beta: aggiornata la card esistente con tracciamento puntuale delle attivita odierne, mantenendo coerenza tra riepilogo iniziale e dettaglio della sessione.

Sessione v1.2.1-beta - Apertura Iterazione Operativav1.2.1-beta

01/06/2026

🎯 Obiettivo Versione
  • Aprire la nuova iterazione: inizializzare la card v1.2.1-beta come riferimento unico della sessione corrente.
  • Preparare il tracciamento operativo: predisporre sezione implementazioni e verifiche da valorizzare nel corso della sessione.
✅ Stato attuale (01/06/2026)
  • Card versione creata: inserita in testa al changelog beta con data odierna e identificatore allineato.
  • About admin localizzato tramite costanti: aggiornato admin/templates/pages/about/about.html.twig per usare chiavi tradotte (|trans/|trans|raw) al posto dei testi inline; contenuto servito da language/it-IT/it-IT.tpl_bootstrapitalia.ini e language/en-GB/en-GB.tpl_bootstrapitalia.ini.
  • Particelle localizzate e hardcoded ridotti: aggiornati particles/bootstrapitalia-logo.html.twig, particles/bootstrapitalia-modale-login.html.twig e particles/bootstrapitalia-modale-ricerca.html.twig sostituendo i default testuali con chiavi |trans.
  • Allineamento dizionari lingua: estese le chiavi in language/it-IT/it-IT.tpl_bootstrapitalia.ini e language/en-GB/en-GB.tpl_bootstrapitalia.ini (fallback logo/login/search, not configured icone-link, alias coerente TPL_BOOTSTRAPITALIA_PARTICLE_MENU_INFO in EN).
  • Ottimizzazione finale logo: mantenuto il modello senza campo Testo, fallback centrale su TPL_BOOTSTRAPITALIA_PARTICLE_LOGO_BRAND_NAME e comportamento ripristinato dopo verifica regressione (evitata duplicazione forzata del label su title/alt).
  • Nota comportamento logo riallineata: aggiornata in particles/bootstrapitalia-logo.yaml per esplicitare la logica reale (campi opzionali, visualizzazione della sola riga centrale con Bootstrap .Italia quando i campi sono vuoti).
  • Compattazione descrizioni particelle YAML: semplificati i blocchi info-content in particles/bootstrapitalia-copyright-istituto.yaml, particles/bootstrapitalia-icone-link.yaml, particles/bootstrapitalia-modale-login.yaml, particles/bootstrapitalia-modale-ricerca.yaml e particles/bootstrapitalia-preset-switcher.yaml.
  • Fix hover icona modale ricerca: in scss/bootstrapitalia/_bootstrapitalia-modale-ricerca.scss riallineato lo stacking del trigger ricerca al comportamento della login (layer ::before dietro l'icona, icona in primo piano) per evitare la scomparsa dell'icona al passaggio mouse.
  • Uniformazione transizioni hover tra particelle: aggiornati scss/bootstrapitalia/_bootstrapitalia-modale-ricerca.scss e scss/bootstrapitalia/_bootstrapitalia-icone-link.scss per usare timing coerente con login (0.2s ease-in-out su color/fill/background) e comportamento di ingrandimento del cerchio hover allineato.
  • Allineamento layout Offline lato progetto: in custom/config/_offline/layout.yaml consolidato l'assetto di servizio con logo centrale del progetto, rimozione componenti non essenziali (ricerca/link utili), mantenimento del blocco principale offline (messaggio + autenticazione), footer/copyright coerenti.
  • Blindatura Offline lato distribuzione: aggiornato layouts/_offline.yaml sostituendo il riferimento legacy logo-3431 con bootstrapitalia-logo-8845, per garantire coerenza anche senza override runtime in custom/config.
  • Blindatura Error lato distribuzione: aggiornato layouts/_error.yaml sostituendo il logo core Gantry con bootstrapitalia-logo-8845 e relativa voce content, mantenendo la pagina errore allineata all'identita grafica del progetto.
  • Allineamento layout base Default: portata in layouts/default.yaml la configurazione operativa consolidata del progetto (header/top/navigation/footer/copyright/particle content) per ridurre la dipendenza dalle sole configurazioni runtime.
  • Outlines installabili esplicitati: esteso install/outlines.yaml con _body_only, _error e _offline in aggiunta a default/home, per coerenza tra installazione pulita e layout base distribuiti.
  • Reset outline runtime per inheritance controllata: svuotati custom/config/_error/layout.yaml e custom/config/_offline/layout.yaml (layout/content) mantenendo il solo scheletro strutturale, per riattivare una ereditarieta pulita dai layout base del template.
  • Allineamento finale pagine di servizio: confermata la strategia operativa su Error/Offline con override runtime minimali e definizione della base stabile nei file layouts/_error.yaml e layouts/_offline.yaml.
  • Consolidata strategia Gantry source-of-truth: fissata la regola operativa layouts = base distribuibile, custom/config = override runtime istanza, con validazione della priorita di override e fallback sui layout base.