Changelog - Template Bootstrap .Italia

• Strategia: Aggiornamento file base da Hydrogen ultima versione mantenendo metadata personalizzati (author, copyright, versioni)
• File sincronizzati:
  • component.php - Author: Tiger12 (da RocketTheme)
  • error.php - Author: Tiger12
  • index.php - Author: Tiger12
  • offline.php - Author: Tiger12
  • html/layouts/joomla/system/message.php - Author: Tiger12
  • html/layouts/chromes/gantry.php - Author: Tiger12
  • includes/gantry.php - Author: Tiger12
  • install/templates/update.html.twig - Tiger12 link
• Modifiche applicate: Solo metadata (author name, copyright year, links), NO modifiche funzionali al core logic Hydrogen
• Rationale: Mantenere base Hydrogen aggiornabile facilmente, customizzazioni solo nei layer A2/C3 (vedi architetture_report.md § 5.1)

• Problema: Fatal error "Cannot redeclare class WarningField" quando si clicca "Stili Template" in backend Joomla
• Causa: Conflitto tra plugins/system/gantry5/fields/warning.php (WarningField) e templates/bootstrapitalia/fields/warning.php (WarningField duplicato)
• Diagnosi comportamento atteso:
  • Clic "Stili Template" → Plugin system/gantry5 intercetta
  • Redirect automatico a administrator/index.php?option=com_gantry5&view=configurations/13/layout&theme=bootstrapitalia
  • Apre Layout Manager di Gantry (non form config generica Joomla)
• Tentativi di fix:
  1. ❌ Rinominato classe: WarningField → BootstrapItaliaWarningField (plugin non riconosce più)
  2. ❌ Rimosso <config> completamente da templateDetails.xml (perso trigger redirect)
  3. ❌ Ripristinato <config> con field type="bootstrapitalia" (plugin non intercetta)
• Soluzione finale:
  • ✅ Rimosso <config> da templateDetails.xml (evita conflitto classe)
  • ✅ Eliminata cartella fields/ completamente dal template
  • ✅ Rimosso riferimento <folder>fields</folder> dalla sezione <files>
  • ✅ Plugin system/gantry5 gestisce redirect tramite <group>gantry5</group> e <library>gantry5</library>
• ⚠️ Nota configurazione critica: Il redirect funziona SOLO se system/gantry5 plugin ha impostazione "Use Gantry 5 Assignments" = Yes. Se impostato su "No", Joomla carica form generica invece di redirigere a com_gantry5

• File: install.php (righe 23-27)
• Modifica: Rinominata classe installer per coerenza progetto
• Prima: class G5_HydrogenInstallerScript (generico Hydrogen)
• Dopo: class BootstrapItaliaInstallerScript (specifico template)
• Rationale: Nome classe coerente con identità template "Bootstrap .Italia", non riferimento generico Hydrogen

• Directory rimossa: fields/ (conteneva solo warning.php)
• Motivo: Eliminazione conflitto classe WarningField con plugin system/gantry5
• Migration path: Template usa field "warning" del plugin Gantry5, non necessita field custom
• Audit trail:

  grep -r "fields/" templateDetails.xml
  # Risultato: 1 match (riga 20)
  # Azione: Rimosso <folder>fields</folder> dalla sezione <files>

• Struttura finale: Template senza cartella fields/, redirect gestito dal plugin system/gantry5

• Nuovo documento: hydrogen_sync.md con procedura completa di sincronizzazione Hydrogen (file core, metadata, checklist)
• Struttura aggiornata: .github/structure.md allineato a file core e rimozione fields/
• Riferimenti incrociati: link a documentazione e regole permanenti per mantenere coerenza con instruction.md

• Layer A1 (Core Hydrogen): File sincronizzati, NO modifiche funzionali (solo metadata)
• Layer A2 (Sezioni bi-*): Nessuna modifica (non toccati dal fix)
• Layer C3 (Configuration): Nessuna modifica (non toccati dal fix)
• Layer Runtime (Gantry): Dipendenza plugin system/gantry5 per redirect, configurazione "Use Gantry 5 Assignments" critica
• templateDetails.xml: Pulizia <config> e <files>, riferimenti fields/ rimossi

• architetture_report.md § 5.1 - Regole di governance architetturale (core Hydrogen non modificato)
• architetture_report.md § 2.2 - Layer Hydrogen Core (dipendenza del template)
• instruction.md § 1.1 - Scopo e Ambito (template basato su Gantry 5)

• Scope: Aggiunta metadata headers standardizzati a tutti 8 file configurazione Foundation Layer per coerenza architetturale
• File aggiornati: scss/configuration/_base.scss, _colors.scss, _typography.scss, _spacing.scss, _breakpoints.scss, _z-index.scss, _dimensions.scss, _nav.scss
• Metadata pattern (già in templateDetails.xml):

  /**
   * @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
   * 
   * Foundation Layer Configuration - Design Tokens
   * [Descrizione modulo specifico]
   * https://italia.github.io/bootstrap-italia/
   */

• Descrizioni identificatori: Ogni file ha descrizione breve ("Configuration Base", "AGID Color Palette", "Typography System", etc.
• Benefici: Metadata garantisce tracciabilità codice, crediti archivio, licenza chiara, deprecation management, supporto IDE (hover doc)
• Nota DRY: Rimossi @version tag individuali (vedi sezione successiva "Eliminazione @version")

• Scope: Aggiunta metadata headers a 6 file mixins layer per coerenza con configuration layer
• File aggiornati: scss/mixins/_base.scss, _breakpoints.scss, _effects.scss, _dynamic-states.scss, _nav.scss, _section-styles.scss
• Pattern identico a configuration: Stesse 6 @-tag (@package, @author, @currentDeveloper, @copyright, @license, descrizione layer)
• Descrizioni differenziate: "Utility Layer Mixins Base" (orchestrator), "Responsive Breakpoint Mixins", "Transition & Hover Effects", etc.
• Validazione coerenza: File _base.scss (configuration) = "Foundation Layer Configuration Base"; File _base.scss (mixins) = "Utility Layer Mixins Base" (pattern identico, contesti diversi)
• Completamento architetturale: Metadata ora coerente su 14 file (8 configuration + 6 mixins); template pronto per future extensioni

• Problema identificato: Tag @version 1.0.22-beta duplicato in 9 file (8 configuration + 1 orchestrator)
• Impatto manutenzione: Ogni release richiede aggiornamento manuale di 9 file separati → rischio sincronizzazione fallita → versioni inquete
• Soluzione DRY: Single Source of Truth = templateDetails.xml (riga 3: <version>1.0.22-beta</version>)
• File corretti: Rimosso @version da:
  • Configuration: _base.scss, _colors.scss, _typography.scss, _spacing.scss, _breakpoints.scss, _z-index.scss, _dimensions.scss, _nav.scss
  • Mixins: _base.scss
• Metadata residuo: Conservati @package, @author, @currentDeveloper, @copyright, @license (invarianti nel tempo)
• Regola generale: Metadata immutabile nel codice sorgente (author, copyright, license); versioning dinamico solo in templateDetails.xml
• Beneficio: Eliminati 9 punti di sincronizzazione fragili; manutenzione versione centralizzata; git diffs più puliti

• Problema iniziale: 59 import A2 adapter layer sparsi senza categorizzazione; difficile navigazione file 172 righe
• Soluzione: Raggruppamento import per categorie logiche con commenti descriptivi
• Struttura finale:
  1. A1 HYDROGEN CORE (read-only Nucleus): @import "nucleus/theme/base"
  2. A2 CORE COMPONENTS: core, typography, utility, navigation, header, footer, breadcrumb, drawer, offcanvas (21 import)
  3. A2 LAYOUT SECTIONS: showcase, intro, feature, mainbody, sidebar, aside, bottom, last (14 import)
  4. A2 CONTENT & PAGE STYLES: forms, tables, variations, error, animations, content-array (6 import)
  5. A2 CUSTOM PARTICLES: bootstrapitalia-logo, modale-ricerca, modale-login, preset-switcher (4 import)
  6. A1 BREAKPOINTS (read-only Nucleus): @import "nucleus/theme/breakpoints/base"
• Benefici navigazione: Developer capisce immediatamente A1 vs A2; SCHEMA logico=layout fisico file; IDE fold/unfold per sezioni
• Mantenibilità: Aggiungere nuovo file? Clear section dove inserirlo; audit importi per completezza semplice; zero ambiguità ordine loading
• Semantica architetturale: Riflette cleanly layer model (A1=Hydrogen, A2=Bootstrap Italia, C3=Foundation esterna)

• Problema identificato: bootstrapitalia.scss importava @import "bootstrapitalia/particle-overrides" ma file _particle-overrides.scss era completamente vuoto
• Analisi semantica: Cartella particles/ contiene 22 file custom Bootstrap Italia (bootstrapitalia-logo, modale-*, preset-switcher, branding, sample, copyright) — ZERO file override Hydrogen
• Root cause: File creato come placeholder durante setup iniziale, mai completato, mai usato
• Azione intrapresa:
  • ✅ Verificato file vuoto (0 byte)
  • ✅ Confermato no dipendenze altre (grep search)
  • ✅ Rimosso import da bootstrapitalia.scss (linee 155-159)
  • ✅ File _particle-overrides.scss eliminato dalla directory
• Impatto semantico: Rimuove confusione "particles are overrides" — chiarisce "particles are custom creations"
• Completezza: 22 particles custom = layer Runtime indipendente; zero Hydrogen reuse; architettura pulita

• Contesto: bootstrapitalia-joomla.scss (compilazione backend Joomla) ha comment "Load Template Configuration" risultato ambiguo
• Approfondimento architetturale:
  • _dependencies.scss importa nucleus/theme/base (frontend Hydrogen)
  • bootstrapitalia-joomla.scss NON importa dependencies; importa direttamente nucleus/theme/joomla/base (backend-specific Hydrogen)
  • Due compilazioni diverse = due nuclei diversi (frontend vs backend rendering)
  • bootstrapitalia-joomla.scss necessa C3 Foundation layer (design tokens) INDIPENDENTEMENTE da dependencies
• Fix semantico: Aggiornato comment in bootstrapitalia-joomla.scss:

  // C3 FOUNDATION LAYER (Design Tokens)
  // Required prerequisite for all Joomla-specific styles
  // § scss/configuration/base - Design tokens (colors, spacing, breakpoints)
  // Tokens definiti in configuration/ sono usati da tutti i file _bi-*.scss del layer Joomla

• Chiarimento necessità: Foundation layer tokens NON sono "duplicate" da dependencies; sono "independent prerequisite" perché compilazione Joomla ha path import diverso
• Architettura definitiva: Due flussi import coerenti ma separati: frontend (@import dependencies→nucleus/theme) vs backend (@import joomla/theme) entrambi usando stessi C3 tokens

• Metodologia: Audit file-by-file per identificare dead code in scaffolding Bootstrap Italia (bi-*, bootstrapitalia-* file) escludendo core Hydrogen/Nucleus
• Scope esclusione: Nucleus-provided mixins/variables (breakpoints, functions) — audit SOLO layer personalization v1.0.22-beta
• Risultato audit:
  • ✅ 200+ variabili configuration verificate
  • ✅ 40+ smooth-transition() call confermati (usati)
  • ✅ 11 focus-shadow-dynamic() call confermati (modali)
  • ✅ 9+ breakpoint(mobile-only) call confermati
  • ⚠️ 4 breakpoint selectors unused (desktop, large-desktop, xl, small-mobile)
  • ⚠️ 6 media mixins duplicated (media-tablet, media-desktop, media-large, media-xl, media-mobile-only, media-tablet-down)
  • ⚠️ 4 effect mixins unused (smooth-transition-delayed, hover-scale, hover-scale-smooth, focus-ring)
  • ⚠️ 2 mixin files completely unused (131 righe _nav.scss, 150 righe _section-styles.scss)

• Duplicazioni eliminate:
  1. scss/configuration/_core.scss (linee 13-19): 7 variabili spacing ($spacing-xs → $spacing-3xl) — duplicate esatte di _spacing.scss
  2. scss/configuration/_breakpoints.scss (linee 29-63): 6 media query mixin — duplicati di funzionalità @mixin breakpoint() in scss/mixins/_breakpoints.scss
  3. scss/mixins/_breakpoints.scss: 4 breakpoint selector (@else if blocks) non usati in nessun file bi-* (desktop, large-desktop, xl, small-mobile)
• Righe eliminate: ~62 linee dead code
• Verifiche SCSS: ✅ configuration/_base.scss compila correttamente; ✅ mixins/_base.scss compila correttamente
• Nota di progettazione: Riordinamento import scss/configuration/_base.scss — _spacing.scss ora importata PRIMA di _core.scss perché _core.scss usa $spacing-lg nella variabile forma

• Strategia YAGNI + Beta Phase: Commento per review futura, non eliminazione permanente. Marcato // UNUSED v1.0.22-beta - Remove after v1.0 stable if still unused
• Mixin non utilizzati commentati:
  1. scss/mixins/_effects.scss: 4 mixin commentati — smooth-transition-delayed(), hover-scale(), hover-scale-smooth(), focus-ring() (potenziali per animazioni future, accessibilità)
• Variabili configuration commentate:
  1. scss/configuration/_core.scss: 10 variabili dimension non usate — $grid-min-height, $button-min-height, $input-min-height, $icon-size-sm/md/lg, $code-padding/background/border-radius
• File completamente commentati:
  1. scss/mixins/_nav.scss (131 righe): 2 mixin main-nav-colors() e main-nav-indicators() — 0 riferimenti nei file bi-*. Potenziale se navigazione refactorizzata per supportare tema dinamico
     
  2. scss/mixins/_section-styles.scss (150 righe): 6 mixin section-base-styles(), section-with-image(), ecc. — 0 riferimenti. Potenziale se sezioni standardizzate per eliminare ripetizione
• Import commentati: scss/mixins/_base.scss — 2 @import commentati (_nav.scss, _section-styles.scss) per evitare errori SCSS compilation
• Righe commentate: ~316 linee

• Test compilazione: ✅ sass scss/configuration/_base.scss — compila senza errori (solo deprecation warnings @import expected)
• Test compilazione: ✅ sass scss/mixins/_base.scss — compila senza errori
• Risultato: Struttura SCSS intatta e funzionale post-cleanup

• Linee eliminate: ~62 (duplicazioni confermabili)
• Linee commentate: ~316 (codice potenziale, reviw future)
• Totale inarchiviato: ~378 righe
• File modificati: 8 (configuration/_core.scss, configuration/_breakpoints.scss, configuration/_base.scss, mixins/_breakpoints.scss, mixins/_effects.scss, mixins/_nav.scss, mixins/_section-styles.scss, mixins/_base.scss)
• Impatto semantico: Codebase più pulita, intenti architetturali chiari, manutenzione semplificata senza ambiguità

• Timeline: Post v1.0 stable release (quando progetto entra produzione)
• Decisione binaria: Se codice commentato ancora non usato → eliminare definitivamente. Se usato → scommentare e integrare
• Tracciamento: Aggiungere note nelle issue di v1.0.1-stable per review archivio dead code

• Scope: Realizzazione del file .github/architetture_report.md con analisi architetturale e struttura a layer
• Nota: Release allineata al tracciamento giornaliero (regola 1:1 data-versione)
• Gantry: Reinstallato Gantry 5 (ultima versione) per diagnosi errore PHP WarningField

• Mapping sezione system messages: systemmessages → system-messages per allineare ID DOM (#g-system-messages) in particles/bootstrapitalia-preset-switcher.html.twig
• Fallback inline: stesso mapping applicato nel blocco CSS fallback per garantire coerenza anche senza output in <head>
• Generazione CSS corretta: Regole dinamiche per background-color, text-color, heading-color applicate alle sezioni Gantry via body.preset-*
• Preset frontend: Applicazione classe preset-* e sincronizzazione data-gantry-preset con priorita' localStorage > backend > fallback

• File aggiornati: scss/bootstrapitalia/_bi-top.scss, scss/bootstrapitalia/_bi-header.scss, scss/bootstrapitalia/_bi-navigation.scss, scss/bootstrapitalia/_bi-menu.scss, scss/bootstrapitalia/_bi-offcanvas.scss, scss/bootstrapitalia/_bi-offcanvas-toggle.scss, scss/bootstrapitalia/_bi-footer.scss, scss/bootstrapitalia/_bi-copyright.scss
• Naming convention: Rinominati _footer.scss → _bi-footer.scss e _copyright.scss → _bi-copyright.scss per coerenza con pattern _bi-[section].scss su tutte le sezioni template (instruction.md A2 layer)
• Top menu links: conversione a var(--top-text-color, $top-text-color) per link e item top
• Footer/Copyright: adozione di var(--footer-*) e var(--copyright-*) per background, testo e heading
• Cleanup footer/copyright: rimosso codice commentato legacy e blocchi vuoti senza output
• Pattern adottato: var(--section-property, $scss-fallback) per background-color, text-color, heading-color, toggle-color
• Beneficio: cambio preset immediato su tutte le sezioni template senza rebuild statico

• Analisi Decision Tree: Applicazione sistematica della regola "Lo uso 3+ volte?" per distinguere hardcoded accettabile da variabili centralizzate
• File _bi-offcanvas-toggle.scss: conversione width/height: 44px → $touch-target-min, margini hardcoded → $spacing-*, fallback colore #ffffff → $offcanvas-toggle-color
• File _bi-top.scss: conversione min-height: 60px (2 occorrenze) → $section-min-height, padding menu item hardcoded → $padding-menu-item-vertical/horizontal, box-shadow: 0 6px 6px rgba(0,0,0,0.05) → $shadow-dropdown
File _bi-footer.scss:
• Social link padding: 0.625rem → $spacing-md
• width: 3rem, height: 3rem → $spacing-xxxl
• line-height: 1.5rem → $spacing-xl
File _bi-header.scss:
• Navbar padding 0.5rem 1rem → $spacing-sm $spacing-lg
• Nav-link padding 0.5rem 1rem → $spacing-sm $spacing-lg
• Breadcrumb padding 0.5rem 1rem → $spacing-sm $spacing-lg
• border-radius: 0.25rem → $radius-sm
File _bi-menu.scss:
• Menu toplevel padding 1rem → $spacing-lg
• Menu mobile padding 0.5rem (2 breakpoint) → $spacing-sm
File _bi-navigation.scss:
• padding-top/bottom: 0px → $spacing-none
File _bi-offcanvas.scss:
• Toggle width/height 44px → $touch-target-min (2 conditional blocks)
• Toggle positioning 0.5rem, 0.75rem → $spacing-sm, $spacing-md
Benefici consolidamento: Manutenzione centralizzata, coerenza visiva, WCAG compliance, Guide future Decision Tree

• Preset Switcher: badge versione aggiornato a v1.0.3 in particles/bootstrapitalia-preset-switcher.yaml

• View implementate: Login (default_login.php), Registration (default.php), Reset (default.php, confirm.php), Remind (default.php)
• Alert pattern consistente: Tutti i form usano .alert.alert-info per description/legend con struttura uniforme
• Container .well: Classe custom ispirata a .bd-example di Bootstrap Italia (padding, border, shadow, background grigio)
• Alert escape visivo: Gli alert fuoriescono dal container .well con margini negativi e border-radius 0
• Classi minime: Solo Bootstrap Italia native nel PHP (.form-control, .btn-primary, .card)
• README.md: Documentazione centralizzata in html/com_users/README.md (v2.0.0)

• File creato: scss/bootstrapitalia-joomla/_bi-user.scss (v2.1.0)
• Contenuto: Login Module (mod_login legacy + Joomla 5+), Well Container, tutte le pagine componente (login, logout, registration, reset, remind, profile)
• Effetti custom: Lift button hover (transform: translateY(-2px)), icon animation (transform: translateX(2px))
• Selettori multipli: .com-users-login__form, .com-users-registration__form, .com-users-reset__form per evitare duplicazione
• Import: Aggiunto in scss/bootstrapitalia-joomla.scss

• File rinominato: _systemmessages.scss → _bi-systemmessages.scss (v2.0.0)
• Spostato in: scss/bootstrapitalia/ (sezione template, non override Joomla)
• Ottimizzazione visibilità: Pseudo-classi :empty e :has(> :empty) per nascondere quando vuoto
• Supporto Joomla 5+: Custom element <joomla-alert> con close button, alert-heading, wrapper
• Import aggiornato: scss/bootstrapitalia.scss (non bootstrapitalia-joomla.scss)

• File ottimizzato: scss/bootstrapitalia-joomla/_core.scss
• Rimosse: Tutte le regole com_users (Login Module, Login/Logout pages, Registration, Reset, Remind, Profile, .well styling)
• Spostate in: _bi-user.scss (centralizzazione completa)
• Contenuto attuale: Solo Joomla Menu Module, Bootstrap adjustments, generic form inputs, Gantry framework base
• Beneficio: Eliminati duplicati, zero conflitti border/styling, manutenzione semplificata

• Pattern applicato: var(--custom-property, $scss-fallback) a tutti i file SCSS
• File aggiornati: _bi-user.scss, _bi-systemmessages.scss, _variations.scss, _core.scss
• Variabili convertite:
  • Colori: --accent-color-1, --base-title-color, --base-border-color, --well-background, --systemmessages-*, --white
  • Background: --systemmessages-background-color/image/repeat/size/attachment
  • Border: --base-border-color in .box1, .box2, .title-border, .well
• Beneficio: Tematizzazione runtime tramite CSS custom properties, fallback SCSS sicuro, compatibilità browser legacy

• File configuration: configuration/_core.scss, configuration/_colors.scss
• Variabili aggiunte:
  • Spacing: $spacing-xs (0.25rem), $spacing-sm (0.5rem), $spacing-md (1rem), $spacing-lg (1.5rem), $spacing-xl (2rem)
  • Transitions: $transition-fast (0.15s), $transition-standard (0.3s), $transition-slow (0.5s)
  • Opacity: $opacity-disabled, $opacity-secondary (0.6), $opacity-hover, $opacity-full (1)
  • Typography: $font-weight-semibold (600), $line-height-base (1.6)
  • Shadows: $shadow-sm box-shadow
  • Colors: $well-background (hsl(0, 0%, 96%))
• Refactoring completo: 40+ sostituzioni hardcoded → variabili in _bi-user.scss e _bi-systemmessages.scss

• Problema identificato: Testo "Modifica profilo" nel button di edit profilo stesso colore del background (primary blue #0066cc)
• Causa root: Regola CSS body.preset-base #g-mainbody a { color: #0066cc !important; } sovrescriveva tutti i link nel mainbody
• Soluzione implementata: Selettore CSS con massima specificità body #g-mainbody .profile > ul.btn-toolbar li.btn-group > a.btn-primary con !important
• Colori dinamici: Migrazione da hardcoded #fff a CSS custom property var(--bs-white, #fff) per supportare theme switching
• Copertura pseudo-classi: Applicato color: var(--bs-white, #fff) !important a :link, :visited, :hover, :active, :focus
• Selettore universale: Uso di * { color: var(--bs-white, #fff) !important; } per forzare colore bianco su tutti gli elementi figli (span icone + testo diretto)
• Coerenza effetti: Button profile button toolbar utilizza gli stessi effetti di hover/active della sezione centralizzata:
  • Hover: transform: translateY(-2px) con box-shadow: $shadow-md
  • Active: transform: translateY(0) con box-shadow: $shadow-sm
  • Transitions: $transition-standard per smoothness
• File modificato: scss/bootstrapitalia-joomla/_bi-user.scss v3.0.0
• Validazione: Confermato che no exist cartelle methods/, captive/ con override PHP (solo logica backend 2FA/validazione)

• Status totale: ✅ COMPLETATO - Tutte le 8 view com_users + 3 subtemplate profile
• File modernizzati:
  • login/: default_login.php, default_logout.php (2)
  • registration/: default.php (1)
  • reset/: default.php, confirm.php (2)
  • remind/: default.php (1)
  • profile/: default.php, edit.php, default_core.php, default_params.php, default_custom.php (5)
• Optimizzazioni applicate: Rimozione form-horizontal, control-group, controls, dl-horizontal | Adozione .well | Alert per descrizioni | CSS custom properties | Lift button effects coerenti
• Documentazione aggiornata: html/com_users/README.md v3.0.0 con section "Aggiornamenti 11 Febbraio 2026"

• File aggiornato: .github/JOOMLA_OVERRIDE_CONVENTIONS.md (v1.0.0)
• Contenuto: Convenzioni standardizzate override Joomla, naming convention SCSS (_bi-[nome].scss), procedura creazione, testing requirements
• Esempi pratici: Login override completo, registration template, quick start script
• Regole fondamentali: Mantenere funzionalità Joomla core, styling tramite CSS/SCSS, struttura logica form

• Override PHP: 5 file com_users (login, registration, reset x2, remind) con classi Bootstrap Italia native
• SCSS Component: 1 file centralizzato (_bi-user.scss v2.1.0) per tutte le view com_users
• SCSS Section: 1 file system messages (_bi-systemmessages.scss v2.0.0) ottimizzato
• Configuration: Sistema variabili completo (spacing, transitions, opacity, typography, colors)
• CSS Custom Properties: Pattern var(--prop, $fallback) applicato globalmente
• Documentazione: README com_users + JOOMLA_OVERRIDE_CONVENTIONS.md aggiornati

• Custom ridondanti eliminati: 14 file in custom/config/default/particles/ (content, menu, module, social, spacer, totop, etc.)
• Sample Hydrogen eliminata: particles/sample.yaml + particles/sample.html.twig (demo non production)
• Logo Nucleus defaults rimosso: config/default/particles/logo.yaml (template usa bootstrapitalia-logo)
• Architettura consolidata: 3 livelli Gantry (particles/ + config/default/ + custom/config/)
• Distribuzione: template deve escludere custom/ (auto-generata da Gantry al primo salvataggio outline)

• Decisione: Template basato su Gantry 5 (non Cassiopea)
• Motivo: Configurabilita' nativa (particles/layout), SCSS scalabile (A1/A2/C3), minori override Joomla
• Trade-off accettato: Dipendenza da framework in cambio di produttivita' e controllo architetturale
• Regola permanente: Vedi .github/instruction.md § 2.3

• File Modificato: .github/instruction.md
• Problema Risolto: Bloat documentale, confusione tra regole permanenti e task completati, impossibilità tracking cronologico progressi
• Soluzione Architettonica: Separazione totale tra:
  • instruction.md: SOLO linee guida permanenti e principi architetturali immutabili
  • changelog: SOLO progressi, modifiche effettuate, verifiche, status task

• Prima di aggiungere qualsiasi contenuto chiedersi:
  • È una regola/principio che vale sempre? → instruction.md
  • È un'azione/verifica completata o in corso? → changelog
• Benefici Previsti:
  • Prevenzione bloat file instruction (difficile leggibilità)
  • Eliminazione confusione "cosa fare sempre" vs "cosa è stato fatto"
  • Tracciabilità cronologica progressi mantenuta

• Sezione 1 - Governance del Documento: Meta-documentazione, scopo, ambito, regole di gestione
• Sezione 2 - Contesto del Progetto: Obiettivi, stack tecnologico, compatibilità Joomla 5.x
• Sezione 3 - Regole Generali di Sviluppo: Principi fondamentali (colori dinamici, mixins, decisioni architetturali, pattern A1/A2/C3)
• Sezione 4 - Criticità e Lezioni Apprese: Avvertenze importanti, problemi risolti, workflow sicuri
• Sezione 5 - Design System e Standard: Linee guida Designers Italia, AGID, accessibilità, responsività
• Sezione 6 - Sistema SCSS e Architettura: Struttura file, import order, dependencies, mapping
• Sezione 7 - Governance Operativa (A1/A2/C3): Priorità architetturali, atoms, particles, convenzioni
• Sezione 8 - Pattern di Sviluppo e Guida Operativa: Variabili, mixins, conversioni, checklist

• Posizionamento: All'inizio del file instruction.md, prima della Governance
• Scopo: Dichiarare esplicitamente la separazione tra:
  • 📘 instruction.md: Standard codifica, regole architetturali, workflow, pattern, criticità
  • 📝 changelog: Modifiche effettuate, risultati verifiche, status task, matrici migrazione, tracking versioni
• Contenuto Chiave: Regola Fondamentale con decision tree per categorizzazione contenuti

• Ridondanze Rimosse: Eliminati riferimenti duplicati a regole sparse nel documento
• Terminologia Standardizzata: Uso consistente termini architetturali (A1/A2/C3, atoms, particles, configuration layer)
• Indice Ottimizzato: Riorganizzazione logica sezioni per navigazione intuitiva
• Manutenibilità: Principio "write once, reference forever" per regole architetturali

• Link Quick Reference:
  • STRUCTURE.md: Inventario directory/file completo
  • changelogs/version/stable/: Cronologia versioni stabili
  • changelogs/version/beta/: Cronologia versioni beta (questo file)
  • changelogs/version/alpha/: Prima release sperimentale
• Risorse Esterne:
  • Bootstrap Italia Docs e CDN (jsdelivr.com)
  • Design UI Kit e Design System Italia
  • Manuale Operativo Design (docs.italia.it)
  • Linee Guida AGID
  • Joomla Docs e Gantry 5 Docs

• Nuove Regole Architetturali: Aggiunte SOLO quando pattern ricorrenti o criticità identificate
• Progressi Operativi: Documentati ESCLUSIVAMENTE in changelog (MAI in instruction.md)
• Versioning Semantico: instruction.md segue semantic versioning solo per modifiche architetturali maggiori
• Modifiche Minori: Correzioni typo, chiarimenti non modificano versione documento

• .github/instruction.md: Ristrutturazione completa applicata
• changelogs/version/beta/changelog.html: Entry v1.0.18-beta aggiunta (questo file)
• changelogs/index.html: Aggiornato riferimento v1.0.18-beta

• 7 Regole Documentazione Changelog (sezione 8 instruction.md) ✅
• Fix Z-Index Header Mobile ✅
• Documentazione Eccezioni Hardcoded (sezione 7.2) ✅
• Regola 1:1 Gestione Versioni e Date (una data = una versione) ✅

• Fix Regressione Header Mobile (margin-left -65px → 0) ✅
• Audit Architetturale SCSS (centralizzazione variabili) ✅
• Normalizzazione 29 Pattern Legacy (26 transition mixin + 3 media query) ✅
• Conformità 100% Raggiunta (z-index, media query, variabili) ✅

• Sezione 8: Standardizzazione SCSS - Guida Operativa Completa (11 sottosezioni)
  • Variabili spacing centralizzate (_spacing.scss)
  • Mixin effects, breakpoints, section-styles documentati
  • Checklist conversione hardcoded → variabili
  • Esempio completo conversione (toggle, switcher, login)
  • Strategie anti-regressione (git workflow, pre-commit hook, VALIDATION.md)
  • Roadmap standardizzazione per sezioni rimanenti
• Sezione "Gestione Versioni e File Legacy" (ora in instruction.md § 8.11)
  • ⏳ Procedura Permanente: Procedure rollback sicuro ora centralizzata in instruction.md § 8.11
  • Creata in questa versione: Root cause analysis file cancellati vs riferimenti orfani identificato (v1.0.17)
  • Sintesi: 6 step obbligatori pre-rollback: identificare file creati, grep riferimenti, documentare dipendenze, decidere strategia (backport/refactor/fallback), checkout, validare compilazione
  • Rationale: Evitare "Undefined mixin" e errori compilazione SCSS post-rollback
• Correzzione Typography-Fonts Coherence
  • Font da "Lato"/"Cormorant SC" → "Titillium Web" (conforme Bootstrap Italia)
  • Monospace: "Menlo" → "Roboto Mono" (presente in /fonts/)
  • Serif: Georgia → "Lora" (presente in /fonts/, 20 file)
  • Fallback stack aggiornato con system fonts (-apple-system, Segoe UI)
  • Eliminazione riferimento orfano @include breakpoint() in _bi-top.scss

• Creazione mixin centralizzati (_dynamic-states.scss con focus-shadow-dynamic) ✅
• Normalizzazione Spacing (variabile $spacing-none centralizzata in 9 istanze) ✅
• Normalizzazione Overlay Color ($overlay-dark centralizzata per dropdown) ✅
• Verifica File Particelle (colori hardcoded → var(), z-index, breakpoints) ✅
• Verifica File Sezione bi-* (colori statici → CSS Custom Properties dinamici) ✅
• Fix Sintassi SCSS (4 errori: selettore SCSS, CSS var(), proprietà orfane, test classes) ✅

• □ Normalizzazione Transizioni complete (26 pattern legacy → @include smooth-transition())
• □ Normalizzazione Media Query (3 pattern legacy → @include breakpoint())

• scss/configuration/_typography.scss - Correzione font families (Titillium Web, Roboto Mono, Lora)
• scss/configuration/_spacing.scss - Creazione file (nuovo, v1.0.17)
• scss/configuration/_base.scss - Aggiunto import _spacing.scss
• .github/instruction.md - Sezioni 8 (Standardizzazione) e 7.3 (Gestione Versioni)
• scss/bootstrapitalia/_bi-top.scss - Correzione riferimento orfano @include breakpoint()

06/02/2026 - Sessione pomeriggio - Implementazione colori dinamici che rispondono al preset-switcher

• File sezione (bi-*) utilizzavano variabili SCSS statiche: $accent-color-1, $top-link-color, $accent-color-2
• Particelle utilizzavano correttamente CSS Custom Properties: var(--primary-color, ...)
• Risultato: offcanvas, menu, header non cambiavano colore quando utente selezionava diverso preset dal switcher
• Menu items, link hover, button background rimanevano hardcoded ai valori di default

• Mixin Centralizzato: @mixin focus-shadow-dynamic($opacity) creato in scss/mixins/_dynamic-states.scss (27 righe)
  • Applica focus shadow dinamico: 0 0 0 3px var(--accent-light, rgba(...))
  • Parametro opacità configurabile (default 0.1)
  • Applicato 11 volte in file particelle (modale-login, modale-ricerca)
• Variabili Configurazione:
  • $spacing-none: 0 !default; in _spacing.scss - centralizza zero-spacing (9 istanze standardizzate)
  • $overlay-dark: rgba(0, 0, 0, 0.8) !default; in _colors.scss - overlay dropdown menu
• CSS Custom Properties nei File bi-*:
  • _bi-offcanvas.scss: background: var(--primary-color, $accent-color-2); per button (2 posizioni)
  • _bi-top.scss: Links e hover trasformati in var(--primary-color) e var(--accent-light)
  • _bi-menu.scss: Menu items attivi/hover usano var(--accent-light) fallback $accent-color-1
  • _bi-header.scss: Navbar brand e links hover con var(--accent-light)

• _bi-menu.scss (Riga 30): Selettore SCSS incompleto menu-parent-indicator { → &.menu-parent-indicator {
• _bi-offcanvas.scss (Riga 4): CSS Custom Property syntax error color: --primary-color, ... → color: var(--primary-color, ...)
• _bi-navigation.scss: Rimossi 4 test color classes (.menu-color-red, .menu-color-purple, .menu-color-green, .menu-color-blue) - ~20 righe
• _bootstrapitalia-modale-ricerca.scss (Righe 283-284): Proprietà CSS orfane spostate in selettore valido #modal-search ~ .modal-backdrop { opacity: 0.3; }

• File Creati: 1 (scss/mixins/_dynamic-states.scss)
• File Modificati: 8 (_bi-offcanvas.scss, _bi-top.scss, _bi-menu.scss, _bi-header.scss, _bi-navigation.scss, _bootstrapitalia-modale-ricerca.scss, _colors.scss, _spacing.scss)
• Variabili Aggiunte: 2 ($spacing-none, $overlay-dark)
• Errori Sintassi Corretti: 4 (selettore SCSS, CSS var(), proprietà orfane, test classes)
• Colori Dinamicizzati: 15+ istanze convertite da variabili statiche a CSS Custom Properties

• ✅ Menu items cambiano colore al cambio preset tramite switcher
• ✅ Offcanvas button risponde ai preset dinamici
• ✅ Header navbar navbar items seguono tema selezionato
• ✅ Focus states mantengono feedback visivo dinamico
• ✅ Fade backdrop modale ricerca correttamente implementato
• ✅ Nessuna regressione in compilazione SCSS

• Verifica File SCSS Particelle:
  • Controllare allineamento con mixins centralizzati (smooth-transition, breakpoint, section-base-styles)
  • Verificare utilizzo variabili colore da _colors.scss (eliminare hex hardcoded)
  • Validare conformità z-index (tolleranza zero - solo variabili $z-*)
  • Sostituire media query hardcoded con @include breakpoint()
• Controllo Documentazione:
  • Aggiornare changelog per v1.0.14 non documentate (se presenti)
  • Verificare coerenza .github/instruction.md con modifiche effettuate
  • Validare applicazione 7 regole documentazione changelog
• Pulizia e Coerenza SCSS:
  • Preparare aggiustamenti file SCSS per garantire coerenza architetturale
  • Verificare import chain in tutti file principali (configuration → mixins → sections)
  • Validare naming convention file (bi-* per sezioni, bootstrapitalia-* per particelle)
• Gestione Modifiche Stesso Giorno:
  • Accumulare ulteriori modifiche 05/02/2026 in questa versione 1.0.15-beta
  • NON creare nuove sezioni changelog con stessa data (regola 1 data = 1 versione)
  • Aggiornare sezioni esistenti mantenendo cronologia modifiche

• Categoria: Fix Regressioni Critiche
• File Modificati: scss/bootstrapitalia/_bi-header.scss (191 righe totali)
• Data Fix: 06/02/2026

• Problema Rilevato: Logo header non visibile su viewport mobile/tablet (< 992px)
• File: scss/bootstrapitalia/_bi-header.scss - Riga 187
• Causa Tecnica: Margine negativo eccessivo margin-left: -65px; sposta il logo fuori viewport su dispositivi mobile/tablet
• Viewport Affettati:
  • ✅ Desktop (≥ 992px): OK - regola non applicata
  • ❌ Tablet (768px - 991px): Logo parzialmente/totalmente fuori schermo
  • ❌ Mobile (< 768px): Logo completamente fuori schermo
• Analisi DOM: Elemento presente nel DOM ma spostato oltre il margine sinistro del viewport
• Conflitti Z-Index: Nessuno - problema di posizionamento, non di stacking context

• Fix Implementato: Rimozione margine negativo critico
• Modifica Codice:

  // ❌ PRIMA (Regressione)
  #g-header .g-logo-image {
      @media (max-width: ($bp-desktop - 1px)) {
          margin-left: -65px;  // Sposta logo fuori viewport
          padding-top: 4px;
      }
  }
  
  // ✅ DOPO (Fix)
  #g-header .g-logo-image {
      @media (max-width: ($bp-desktop - 1px)) {
          margin-left: 0;      // Logo allineato correttamente
          padding-top: 4px;
      }
  }

• Rationale Fix: Eliminazione spostamento orizzontale garantisce visibilità logo su tutti i viewport mobile/tablet
• Pattern Conforme: Utilizzo variabile breakpoint $bp-desktop da _breakpoints.scss (accettabile secondo sezione 7.1 instruction.md)

• Desktop (≥ 992px): ✅ Logo visibile, nessuna regressione introdotta
• Tablet (768px - 991px): ✅ Fix verificato - logo ora visibile e allineato
• Mobile (< 768px): ✅ Fix verificato - logo completamente visibile
• Sticky Header: ✅ Comportamento scroll preservato (transizioni smooth intatte)
• Z-Index Hierarchy: ✅ $z-header: 1000 conforme alla scala centralizzata

• Transition Hardcoded: Rilevate 20+ occorrenze di transition: diretto nei file modali
• File Interessati:
  • _bootstrapitalia-preset-switcher.scss - 3 occorrenze (righe 32, 84, 135)
  • _bootstrapitalia-modale-login.scss - 11 occorrenze
  • _bootstrapitalia-modale-ricerca.scss - 10 occorrenze
• Decisione Architetturale: Pattern legacy accettabili - file non modificati in v1.0.15
• Rationale:
  • Pattern funzionanti e testati in produzione
  • Refactoring richiede testing esteso componenti modali complessi
  • Rischio/beneficio: priorità a fix regressioni critiche
  • Refactoring posticipato a sessione futura dedicata ottimizzazioni

• Import Chain: ✅ Verificata - C3 (configuration) → A1 (mixins) → A2 (sections)
• Naming Convention: ✅ Conforme - bi-* sezioni, bootstrapitalia-* particelle
• Z-Index Compliance: ✅ 100% - 0 hardcoded violations (solo variabili $z-*)
• Mixin Usage: ✅ 9 @include smooth-transition() in _bi-header.scss
• Breakpoint Pattern: ⚠️ 2 @media (max-width: ($bp-variable)) - pattern legacy accettabile (usa variabili)
• Nuove Violazioni: ✅ 0 introdotte dal fix
• Conformità Instruction: ✅ Rispetta sezioni 7.1 (Eccezioni Hardcoded) e 8.3 (Gestione Versioni)

• Categoria: Refactoring Architetturale SCSS
• Obiettivo: Eliminazione violazioni transition hardcoded e media query inconsistenti
• File Modificati (5 totali):
  • scss/bootstrapitalia/_bootstrapitalia-preset-switcher.scss (187 righe) - 3 patches
  • scss/bootstrapitalia/_bootstrapitalia-modale-login.scss (662 righe) - 12 patches
  • scss/bootstrapitalia/_bootstrapitalia-modale-ricerca.scss (441 righe) - 10 patches
  • scss/bootstrapitalia/_bi-header.scss (191 righe) - 2 patches
  • scss/bootstrapitalia/_bi-offcanvas-toggle.scss (65 righe) - 2 patches
• Patches Totali Applicati: 29 normalizzazioni (26 transition + 3 media query)
• Data Refactoring: 06/02/2026 (pomeriggio - stessa giornata del fix header)

• Patch 1 (Riga 32): Icon SVG fill/opacity animation

  // ❌ PRIMA
  .preset-icon svg {
      transition: fill 0.2s ease-in-out, opacity 0.2s ease-in-out;
  }
  
  // ✅ DOPO  
  .preset-icon svg {
      @include transition(fill 0.2s ease-in-out, opacity 0.2s ease-in-out);
  }

• Patch 2 (Riga 84): Dropdown margin-left animation

  // ❌ PRIMA
  .preset-dropdown {
      transition: margin-left 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
  }
  
  // ✅ DOPO
  .preset-dropdown {
      @include transition(margin-left 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94));
  }

• Patch 3 (Riga 135): Item hover background/color

  // ❌ PRIMA
  .preset-item {
      transition: background-color 0.15s ease-in-out, color 0.15s ease-in-out;
  }
  
  // ✅ DOPO
  .preset-item {
      @include transition(background-color 0.15s ease-in-out, color 0.15s ease-in-out);
  }

• Linee Modificate: 232, 241, 249, 264, 275, 383, 398, 433, 469, 534, 591 (e mobile responsive)
• Pattern Normalizzati:
  • Button transform + background animations (multi-property)
  • Icon SVG fill transitions
  • Text color hover states
  • Emergency fallback transitions
  • Input label floating animations
  • Password toggle button interactions
  • Submit button all-properties transition
  • Link hover border-bottom effects
  • Mobile label animations (responsive)
• Esempio Critico - Patch 10 (Riga 398): Login provider buttons

  // ❌ PRIMA (Violazione residua post-audit)
  .social-login-button {
      transition: all 0.2s ease-in-out;
  }
  
  // ✅ DOPO
  .social-login-button {
      @include smooth-transition(all, 0.2s);
  }

• Linee Modificate: 67, 78, 154, 187, 217, 232, 262, 296, 344, 362
• Pattern Normalizzati:
  • Search link text color hovers
  • Emergency fallback background transitions
  • Modal content scale animation (cubic-bezier custom)
  • Close button opacity transitions
  • Form label floating effects
  • Input focus state transitions
  • Submit button hover interactions
  • Backdrop opacity fade (0.3s ease-in-out)
  • Mobile input/button responsive transitions
• Esempio Tecnico - Patch 17 (Riga 154): Modal scale animation

  // ❌ PRIMA
  .modal-content {
      transition: all 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
  }
  
  // ✅ DOPO
  .modal-content {
      @include transition(all 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94));
  }

• Header (Righe 99, 186): Conversione media query a breakpoint() mixin

  // ❌ PRIMA (Pattern legacy - variabili ma non ottimale)
  @media (max-width: ($bp-tablet - 1px)) {
      .navbar { ... }
  }
  @media (max-width: ($bp-desktop - 1px)) {
      .logo { ... }
  }
  
  // ✅ DOPO (Pattern centralizzato)
  @include breakpoint(mobile-only) {
      .navbar { ... }
  }
  @include breakpoint(mobile-only) {
      .logo { ... }
  }

• Offcanvas-Toggle (Righe 26, 36): Normalizzazione breakpoint patterns

  // ❌ PRIMA
  @media (min-width: $bp-desktop) { ... }
  @media (max-width: ($bp-tablet - 1px)) { ... }
  
  // ✅ DOPO
  @include breakpoint(desktop-up) { ... }
  @include breakpoint(mobile-only) { ... }

• Rationale Pattern: Centralizzazione logica responsive in _breakpoints.scss
• Benefici: Modifiche breakpoint propagano automaticamente, nomenclatura semantica, testing semplificato

• transition($values...): Multi-property transitions con parametri variadic
  • Usa per: transform 0.3s, background 0.3s o cubic-bezier custom
  • File: scss/mixins/_effects.scss
  • Compatibilità: Gantry 5 nucleus framework
  • Applicazioni: 15/29 patches (preset-switcher multi-property, modale-login complex, modale-ricerca scale)
• smooth-transition($property, $duration, $easing): Single property con defaults
  • Usa per: color 0.2s, opacity 0.3s, simple animations
  • Defaults: $properties: all, $duration: 0.3s, $easing: ease-in-out
  • Applicazioni: 11/29 patches (modale-login simple hovers, modale-ricerca labels)
• breakpoint($selector): Responsive pattern centralizzato
  • Selettori: mobile-only, tablet-up, desktop-up, tablet-range
  • File: scss/configuration/_breakpoints.scss
  • Applicazioni: 3/29 patches (header navbar/logo, offcanvas-toggle positioning)

• Grep Search 1 - Transition Hardcoded:

  Pattern: transition:\s*[^;]+;
  File Scope: scss/bootstrapitalia/*.scss
  Risultato: ✅ 0 matches (PRIMA: 24 matches)

• Grep Search 2 - Media Query Legacy:

  Pattern: @media\s+\((?:min|max)-width:\s*(?:\(?\$bp-|\d+px)
  File Scope: scss/bootstrapitalia/*.scss  
  Risultato: ✅ 12 matches rimanenti (conformi - usano variabili C3)

• Analisi 12 Media Query Residue:
  • File: _bootstrapitalia-icone-link.scss (3), _bootstrapitalia-logo.scss (3), _bootstrapitalia-modale-login.scss (4), _bootstrapitalia-modale-ricerca.scss (2)
  • Pattern: @media (max-width: $bp-variable) - **approvato** secondo instruction.md 7.1
  • Range Complessi: @media (max-width: $bp-large) and (min-width: ($bp-tablet + 1px)) - non convertibile a breakpoint() simple
  • Decisione: Conformi - refactoring opzionale in sessione futura
• Grep Search 3 - Mixin Usage Verification:

  Pattern: @include (transition|smooth-transition|breakpoint)
  File Scope: scss/bootstrapitalia/*.scss
  Risultato: ✅ 50+ matches (tutte le normalizzazioni attive)

• Conformità Pre-Refactoring (Post-Header-Fix): 98%
  • Z-Index: ✅ 100% (0 violations)
  • Transition: ❌ 20+ hardcoded
  • Media Query: ⚠️ 14 legacy patterns (2 non-ottimali + 12 accettabili)
• Conformità Post-Refactoring (100% Raggiunto): 100%
  • Z-Index: ✅ 100% (unchanged)
  • Transition: ✅ 100% (26 normalizzazioni applicate - 0 violations)
  • Media Query: ✅ 100% (3 conversioni a breakpoint() - 12 conformi residue)
• Efficienza Refactoring:
  • Tool Calls: 6 (multi_replace_string_in_file batch operations)
  • Vs. Operazioni Individuali: 29 (efficienza 4.8x)
  • Success Rate: 100% (29/29 patches applicati correttamente)
  • Token Budget: Ottimizzato tramite batching strategico

• Instruction.md - Sezione 7.1: Eccezioni Hardcoded Approvate (righe 344-414)
• Instruction.md - Sezione 8.3: Gestione Versioni e Date (righe 510+)
• Regola 1:1 Versioning: Modifiche 06/02/2026 consolidate in v1.0.16-beta (unica versione per data)
• Configuration Layer: scss/configuration/_breakpoints.scss (5 variabili $bp-*)
• Z-Index Scale: scss/configuration/_z-index.scss (10 variabili $z-* - gerarchia 1000-1920)

• ⏳ Regole Permanenti: Standard changelog formalizzato in instruction.md § 1.5 (versione/data, sintesi, dettaglio tecnico, completeness, riferimenti, pulizia, chiarezza)
• Introdotte in v1.0.15-beta (05/02/2026) - applicate retroattivamente a v1.0.14

• Espansa documentazione v1.0.14-beta applicando le nuove 7 regole
• Aggiunti dettagli tecnici completi per Typography Configuration (Layer C3): file path, line count (26 righe), consolidamento font families, standardizzazione weights, sistema scalabile heading sizes
• Documentato Ampliamento Mixin Layer (A1): _effects.scss (227 righe) con 8 mixin, _section-styles.scss (142 righe) con 3 mixin, eliminazione 50+ duplicazioni pattern
• Specificati file sezioni rinominati (Layer A2): _bi-header.scss (193 righe), _bi-menu.scss (119 righe), _bi-navigation.scss (79 righe), _bi-offcanvas.scss (259 righe), _bi-offcanvas-toggle.scss (63 righe), _bi-top.scss (269 righe)
• Documentato aggiornamento dependencies: import chain bourbon → configuration → nucleus → mixins (19 righe)
• Aggiunti valori esatti per normalizzazione: breakpoints ($bp-tablet: 768px, $bp-desktop: 992px), z-index ($z-header: 1000, $z-offcanvas-toggle: 1035)
• Dettagliato fix offcanvas toggle: posizionamento assoluto, configurabilità left/right, WCAG touch target 44x44px

• Applicato formato consistente con tag <code> per file paths e variabili SCSS
• Utilizzato <strong> per evidenziare layer architetturali (A1, A2, C3) e modifiche critiche
• Suddiviso modifiche in sezioni semantiche chiare (Typography, Mixin, Sezioni, Dependencies, Normalizzazione, Cleanup, Verifiche)
• Inclusi line count per evidenziare ampiezza modifiche e facilitare code review

• Aggiornato badge v1.0.15-beta a bg-success text-white - milestone importante (documentazione completa)
• Mantenuto badge v1.0.14-beta come bg-primary text-white - versione completata standard

• File: scss/bootstrapitalia/_bi-header.scss (riga 3)
• Problema rilevato: z-index: 2 hardcoded rompeva gerarchia stacking context
• Impatto: Header (z: 2) finiva sotto navigation (z: 1002) e top (z: 1003)
• Soluzione: Rimosso valore hardcoded, aggiunto parametro $z-header a mixin section-base-styles()
• Chiamata mixin aggiornata: @include section-base-styles($header-background-color, $header-text-color, $header-heading-color, $z-header)
• Z-index ora correttamente gestito da _z-index.scss ($z-header: 1000)

• File: .github/instruction.md - Nuova sezione 7.1 "Eccezioni Hardcoded Approvate"
• Eccezione 1 - Utility Classes Menu Colors: Documentate classi .menu-color-red, .menu-color-purple, .menu-color-green, .menu-color-blue in _bi-navigation.scss
• Giustificazione: Colori intenzionali per markup Joomla, modifiche rare, pattern utility-first comune
• Eccezione 2 - Media Query con Variabili: Pattern @media (max-width: ($bp-tablet - 1px)) approvato come accettabile
• Motivo: Usa variabile breakpoint da configuration, non rompe centralizzazione
• Preferenza: Per nuovo codice preferire @include breakpoint(mobile-only)
• Eccezione 3 - Z-Index: Confermato ZERO tolleranza per z-index hardcoded, nessuna eccezione ammessa

• Definita procedura verifica trimestrale per pattern sospetti
• Grep pattern: z-index: \d+, @media.*\d+px, color: #[0-9a-f]{6}
• Processo valutazione: refactor vs documentare nuova eccezione
• Obbligo aggiornamento sezione instruction.md per nuove eccezioni approvate

• Strategia ibrida pragmatica: Fix bug critici (z-index) + documentazione eccezioni accettabili (utility colors, media query)
• Prioritizzazione fix architetturali con impatto stacking context
• Documentazione trasparente decisioni pragmatiche vs purismo architetturale
• Bilanciamento manutenibilità vs overhead gestione variabili per utility classes

• File: .github/instruction.md - Nuova sezione 8.3 "Gestione Versioni e Date"
• Regola fondamentale: Una data = una sola versione (relazione 1:1)
• Divieto: Non creare più sezioni changelog con stessa data
• Workflow: Più interventi stesso giorno → accumulare in versione esistente, non creare nuova
• Benefici: Chiarezza cronologica, no duplicazioni, timeline lineare senza ambiguità
• Applicazione pratica: v1.0.15-beta (05/02/2026) consolida tutte modifiche giornata (documentazione + fix z-index + regole versioning)

• Obiettivo: Verifica integrità architettura SCSS (Layer A1/A2/C3), eliminazione pattern hardcoded, risoluzione dipendenze mixin
• Metodologia: Grep sistematico pattern sospetti, cross-reference @include vs @mixin, validazione import chain
• Risultato: 8 fix z-index, 1 fix media query, 2 mixin critici creati, 5 file modificati

• File: scss/bootstrapitalia/_bootstrapitalia-preset-switcher.scss
• Violazione 1-3: Righe 61, 69, 79 - z-index: 1020 sostituito con $z-preset-switcher (1031)
• Violazione 4: Riga 91 - z-index: 1015 sostituito con ($z-offcanvas-overlay + 5) (calcolo dinamico)
• Violazione 5: Riga 104 - z-index: 9999 (valore eccessivo) sostituito con $z-popover (1920)
• Rationale: Dropdown menu deve stare sopra modal backdrop ma sotto tooltip/popover layer
• Impatto: Corretto stacking context, preset switcher ora integrato in gerarchia z-index globale

• File: scss/bootstrapitalia/_bi-offcanvas.scss (riga 213)
• Context: Media query IE11 (@media all and (-ms-high-contrast: none))
• Fix: z-index: 1010 → $z-offcanvas-overlay
• Motivo: Anche polyfill legacy devono rispettare gerarchia centralizzata

• File: scss/bootstrapitalia/_bootstrapitalia-icone-link.scss (riga 44)
• Fix: Rimosso z-index: 1 non necessario da link social icon
• Giustificazione: Pseudoelemento ::before già ha z-index: -1, sufficiente per corretto stacking
• Filosofia: Eliminare z-index ridondanti per ridurre complessità stacking context

• File: scss/bootstrapitalia/_bootstrapitalia-preset-switcher.scss (riga 67)
• Fix: @media (min-width: 769px) → @include breakpoint(tablet-up)
• Motivo: Valore 769px non allineato con $bp-tablet: 768px da configuration
• Beneficio: Centralizzazione breakpoint, modifiche future in un solo punto

• File creato: scss/mixins/_breakpoints.scss (79 righe)
• Problema rilevato: 10+ chiamate @include breakpoint() senza definizione mixin nel workspace
• File chiamanti: _bi-top.scss (3 chiamate), _bi-offcanvas.scss (1 chiamata), _bi-menu.scss (4 chiamate), _bootstrapitalia-preset-switcher.scss (2 chiamate)
• Root cause: Mixin probabilmente fornito da Gantry framework a runtime, mancante per verifica statica
• Soluzione: Implementato mixin completo con 8 selectors responsive
• Selectors supportati: mobile-only, tablet-range, desktop, large-desktop, xl, tablet-up, desktop-up, small-mobile
• Mapping variabili: Usa $bp-mobile-small (480px), $bp-tablet (768px), $bp-desktop (992px), $bp-large (1024px), $bp-xl (1200px)
• Fallback: Selector custom assume min-width con valore passato

• File modificato: scss/mixins/_effects.scss (aggiunto alla fine)
• Problema rilevato: @include transition(opacity 0.3s ease-out 0s, z-index 0s) in _bi-offcanvas.scss senza definizione
• Differenza da smooth-transition: Accetta valori variadic (comma-separated) per transizioni multiple con timing individuali
• Implementazione: @mixin transition($values...) { transition: $values; }
• Uso caso: Overlay con fade opacity (0.3s) e instant z-index change (0s)

• File modificato: scss/mixins/_base.scss
• Aggiunta: @import "breakpoints"; come prima import
• Ordine finale: breakpoints → nav → effects → section-styles
• Rationale: Breakpoints usati da tutti altri mixin, deve essere caricato per primo

• Z-Index Audit: 0 violazioni hardcoded restanti (grep completo workspace)
• Media Query Audit: 17 occorrenze pattern @media (min/max-width: $bp-*) conforme (usa variabili configuration)
• Mixin Dependencies: 100% risolte - tutti @include hanno @mixin corrispondente
• Import Chain: Verificato ordine corretto configuration → mixins → sections
• Pattern count: 50+ chiamate smooth-transition verificate, 10+ breakpoint verificate, 2+ section-base-styles verificate

• Categoria 1 - rgba() Shadows/Overlays: 6 occorrenze (pattern comune accettabile per opacità variabili)
• Categoria 2 - Print Media (#fff/#000): 6 occorrenze (eccezioni legittime per stampa bianco/nero)
• Categoria 3 - Utility Colors: 4 occorrenze _bi-navigation.scss (eccezioni approvate instruction.md 7.1)
• Categoria 4 - Misc: 3 occorrenze (fallback in var(), border utilities)
• Decisione: Non fixare - costo refactoring > beneficio manutenibilità per questi casi

• Offcanvas Toggle: posizionamento assoluto corretto, z-index ($z-offcanvas-toggle: 1035) allineato, fascia sopra #g-top rimossa
• Allineamento toggle a sinistra ripristinato, target touch WCAG 44x44px mantenuto
• Posizionamento configurabile (left/right) tramite variabile $offcanvas-toggle-position

• File: scss/configuration/_typography.scss (26 righe)
• Consolidamento font families con fallback coerenti (Lato, Cormorant SC, Menlo, Georgia)
• Standardizzazione font weights centralizzati: $font-weight-regular (400), $font-weight-medium (500), $font-weight-bold (700)
• Aggiunta variabili $font-family-mono e $font-family-serif per uso tipografico esteso
• Sistema scalabile heading sizes basato su $fontsizes-body-font-size (h1: 3x, h2: 2.3x, h3: 2x, h4: 1.5x, h5: 1x, h6: 0.9x)

• File: scss/mixins/_effects.scss (227 righe) - mixin per transition, hover, focus, border-radius
• Mixin aggiunti: smooth-transition(), smooth-transition-delayed(), hover-scale(), hover-scale-smooth(), focus-outline(), focus-ring(), border-radius-standard(), border-radius-circle()
• File: scss/mixins/_section-styles.scss (142 righe) - mixin per sezioni layout
• Mixin aggiunti: section-base-styles(), section-with-image(), section-link-styles()
• Eliminazione 50+ duplicazioni pattern tra particelle e sezioni

• Prefisso bi-* applicato: _bi-header.scss (193 righe), _bi-menu.scss (119 righe), _bi-navigation.scss (79 righe), _bi-offcanvas.scss (259 righe), _bi-offcanvas-toggle.scss (63 righe), _bi-top.scss (269 righe)
• Implementazione mixin centralizzati (@include section-base-styles, @include smooth-transition, @include breakpoint)
• Uso variabili da configuration: $bp-tablet, $bp-desktop, $z-header, $z-navigation, $z-top, $z-offcanvas-overlay
• Import chain aggiornata in bootstrapitalia.scss (146 righe) con ordine corretto: dependencies → nucleus → core → typography → sezioni bi-* → particles → breakpoints

• File: scss/_dependencies.scss (19 righe)
• Import chain ottimizzata: bourbon → configuration/base → nucleus → mixins/base
• Ordine garantisce ereditarietà corretta variabili (configuration → mixins → sezioni)

• Breakpoints: $bp-mobile-small (480px), $bp-tablet (768px), $bp-desktop (992px), $bp-large (1024px), $bp-xl (1200px)
• Mixin media query centralizzati: @mixin media-tablet, @mixin media-desktop
• Z-Index Scale: $z-base (1000), $z-header (1000), $z-navigation (1002), $z-top (1003), $z-offcanvas-overlay (1010), $z-offcanvas-toggle (1035), $z-modal (1900)

• Rimozione file SCSS di particelle non appartenenti al progetto template (file legacy esterni)
• File senza prefisso bi-* esclusi dalla import chain

• Controlli stacking context e responsive senza regressioni
• Test offcanvas overlay (z-index 1010) sotto toggle (z-index 1035)
• Verifica media query normalizzate su tutti breakpoints

• instruction.md aggiornato con architettura A1/A2/C3 (9 sezioni, 485 righe)
• Standard nomenclatura bi-* prefix per file sezioni documentato
• Regole hardcoding prohibition (NO @media hardcoded, NO z-index hardcoded, NO colori hardcoded)
• Mappature complete layer: A1 (mixins), A2 (sezioni bi-*), C3 (configuration)

• Particelle aggiornate: Login (v1.0.5), Ricerca (v1.0.5), Icone & Link (v1.0.7)

• Particelle aggiornate: Login (v1.0.5), Ricerca (v1.0.5), Logo (v1.0.4), Preset Switcher (v1.0.2)

• Particelle aggiornate: Login (v1.0.5), Ricerca (v1.0.5), Logo (v1.0.4), Icone & Link (v1.0.7)

• Nota: Issue preset-switcher mobile positioning rimasta aperta (rinviata)

• Aggiornata libreria Bootstrap Italia da 2.16.1 a 2.17.2
• Atom CDN aggiornato a v1.0.3 con nuova versione di default 2.17.2
• Atom Icons aggiornato a v1.0.2 con fallback a 2.17.2
• Corretta URL CSS di default in Icons: bootstrap-italia-icons.min.css (era bootstrap-italia.min.css)
• Implementata ereditarietà versione: Icons legge da CDN via gantry.config.get('particles.bootstrapitalia-cdn.version')
• Pattern singleton SVG unificato tra atoms e particelle: window.bootstrapItaliaSpritesLoaded
• Ridotto logging console in Fixed Section atom (rimossi 5 console.log)
• Migliorata gestione classi mobile in Fixed Section: aggiunto removeClass('it-has-fixed-header')
• Verificata compatibilità con modali, tooltip e comportamenti responsive

• Uniformati 150+ colori esadecimali in gantry/presets.yaml e 33 file YAML blueprints
• Implementate CSS Custom Properties per cambio preset istantaneo senza reload
• Variabili disponibili: --primary-color, --primary-medium, --accent-light
• Fallback SCSS per compatibilità browser legacy

• Particelle aggiornate: Icone Link (v1.0.6), Logo (v1.0.3), Modale Ricerca (v1.0.4), Modale Login (v1.0.4)

• Unificazione nomenclatura: GANTRY5_PARTICLE_* → TPL_BOOTSTRAPITALIA_PARTICLE_*
• Cleanup: rimosso replace filter ridondante in modal-body
• Standard mantenuti: GANTRY5_PARTICLE_MENU_INFO, GANTRY5_THEME_*, GANTRY5_PLATFORM_* rimangono invariati (standard Gantry)

• Generazione CSS dinamica da gantry/presets.yaml
• Ciclo generico per tutte le sezioni Gantry senza codice hardcoded
• Dual CSS output (head + inline body) per robustezza

• localStorage + URL hash support per deep linking
• i18n completa con chiavi TPL_BOOTSTRAPITALIA_PRESET_*
• ARIA completa e SVG sprite loader dinamico

• Pattern Bootstrap Italia nativo: dropdown + link-list-wrapper
• Indicatori colore square (border-radius 2px)
• Responsive auto-adattante

• Particle Gantry 5 per selezione preset colore (Base Blu, Verde, Rosso, Neutro)
• UI: icon-toggle + dropdown menu con icona #it-settings
• Persistenza localStorage, accessibilità ARIA completa
• Hover: scale(1.2) + transizioni 0.2s ease-in-out

• Bootstrap Italia: 2.8.2 → 2.17.0
• Bootstrap Icons: 1.11.3 → 1.13.1
• jQuery: 3.6.0 → 3.7.1
• Rimosso Bootstrap standalone (duplicazione con bundle)

• Risolto avviso "Installa framework Gantry 5!"
• Template base aggiornato: Hydrogen v5.5.19 → v5.5.25
• Reinstallazione pulita: Gantry Framework v5.5.25 + template Bootstrap .Italia
• Personalizzazioni preservate: SCSS, particles, configurazioni Gantry

• Riorganizzato instruction.md in 9 sezioni
• Changelog allineati con snapshot versioni e date corrette

• Variabili SCSS Gantry: $base-text-color e $accent-color-2 per tutti i preset
• Workflow: cambio preset → Compile CSS → aggiornamento automatico colori

• Modale Ricerca (v1.0.3): fix stacking context, backdrop in SCSS, hover scale(1.2)
• Modale Login (v1.0.2): colori preset-ready, pattern append-to-body
• Icone Link (v1.0.5): hover fluido con scale(1.2)
• Logo Header (v1.0.2): fill icone con $base-text-color

• Single source of truth: versioni nell'Atom CDN
• Rimossi campi version e css_url dalle particles
• Niente duplicazione CSS, aggiornamento semplificato

• Fix movimento layout: niente variazione di width/height, solo transform: scale()
• Applicato a tutte le particelle: icone-link, modale-ricerca, modale-login
• Background circolare #eaf4fb mantiene coerenza visiva

• Aggiornato instruction.md con workflow preset e note backdrop

• Gantry compila le variabili SCSS di scss/configuration/_colors.scss in base al preset selezionato
• Le CSS Custom Properties non sono supportate nel flusso di compilazione SCSS di Gantry
• transform: scale() ingrandisce visivamente senza alterare il box model (niente reflow)

• Aggiornato a bootstrap-italia.bundle.min.js (Bootstrap 5 + Popper.js)
• Aggiunto CSS icone Bootstrap Italia
• Ottimizzate priorità caricamento risorse

• Effetti interattivi su icone social media
• Particle login modale Bootstrap Italia con integrazione modulo Joomla
• Design modali e animazioni fluide
• Responsive design mobile/desktop ottimizzato

• Aggiornamento completato alla versione 2.16.1 per particles CDN e Icons.
• Verificata compatibilità e funzionalità con nuovo framework.

• Ottimizzato particle per rendere fisso qualsiasi elemento Gantry durante scroll.
• Supporto selettori CSS Gantry (#g-header, #g-navigation).
• CSS ottimizzato con background, shadow e z-index.
• JavaScript con calcolo dinamico padding e gestione responsive.

• Rimossi tag HTML non semantici dalle descrizioni particles.
• Sostituiti con markup accessibile per screen reader.

• Aggiornate descrizioni particles con maggiore chiarezza.
• Migliorata documentazione tecnica sviluppatori.

• Ottimizzata la particella logo/intestazione: migliorata la configurazione backend, la gestione del testo e la flessibilità per layout Gantry 5.

• Sviluppata la particella icone/link: aggiunto campo testo configurabile per ogni icona, visualizzazione personalizzata e accessibile, ottimizzato markup e stile con classi native Bootstrap Italia.

• Sviluppata la particella modale di ricerca: markup aderente a Bootstrap Italia, gestione multilingua, accessibilità migliorata e stile centralizzato tramite SCSS.

• La modale di ricerca ha presentato difficoltà nell’importazione degli stili SCSS tramite Gantry; per garantire la corretta visualizzazione, lo stile è stato scritto inline direttamente nel file Twig.
• Si consiglia di verificare la compatibilità del compilatore SCSS di Gantry e, se possibile, centralizzare lo stile in futuro per una migliore manutenzione.
• Attenzione alle cache di Gantry e Joomla che possono impedire la visualizzazione immediata delle modifiche agli stili.

• Rinominato l'Atom "Fixed Header" in "Fixed Sections" per riflettere meglio la sua funzionalità.

• Impostata direttamente la versione "2.13.4" nel file YAML per il particle "Fixed Sections".

• Aggiornate le note per chiarire lo scopo principale del particle "Fixed Sections" e aggiunti dettagli sulle funzionalità offerte.

• Ottimizzato il file `instruction.md` per maggiore chiarezza e coerenza.
• Ottimizzato il file di changelog per migliorare la struttura e la leggibilità.

• Aggiunto supporto per il caricamento condizionale delle icone tramite CDN.
• Verificata la coerenza del set di icone con Bootstrap Italia.

• Ottimizzato il comportamento sticky per migliorare la compatibilità con dispositivi mobili.
• Aggiunto supporto per la personalizzazione del colore del bordo tramite variabili SCSS.

• Aggiornate le versioni delle risorse per garantire compatibilità con Bootstrap Italia v2.14.0.
• Ottimizzato il caricamento condizionale di CSS e JS per migliorare le prestazioni.

• Migliorato Atom CDN per garantire maggiore compatibilità con le linee guida di Bootstrap Italia.

• Creato un Atom per il caricamento di Bootstrap Icons tramite CDN.
• Aggiunto supporto per il caricamento condizionale delle icone.

• Aggiunta una linea sottostante per migliorare la separazione visiva.
• Ottimizzati gli stili SCSS per supportare l'ereditarietà dei font.

• Rimosso FontAwesome.
• Sostituita l'icona con un carattere Unicode per migliorare la compatibilità.

• Aggiunta configurazione per il caricamento condizionale di risorse CSS e JS.

• Introdotta la variabile SCSS $header-border-color per personalizzare il colore del bordo dell'header.

• Ottimizzazioni generali per migliorare la leggibilità e l'estetica.

• Risolto un problema di compatibilità con il caricamento delle icone in alcuni browser.
• Ottimizzate le prestazioni del caricamento delle risorse CSS e JS.
• Aggiunto supporto per nuove variabili SCSS per una personalizzazione avanzata.

• Il file /templates/bootstrapitalia/layouts/defaults.yaml deve contenere tutte le posizioni stabilite nella cartella /templates/bootstrapitalia/blueprints/styles altrimenti non verranno visualizzate le posizioni nel layout. Questo è fondamentale durante la prima installazione del template.
• Rimossi i file degli outlines con preset a colonne per semplificare la struttura del template.

Creato un Atom per il caricamento di Bootstrap Italia tramite CDN, migliorando la compatibilità con le linee guida di Bootstrap Italia. Risorse caricate da questo Atom

• Head
• Bootstrap Italia CSS
• Splide.js CSS
• Popper.js
• Footer
• Bootstrap Italia JS
• Splide.js
• Anime.js