Il committente ha chiesto un sito più moderno, con pagine ed effetti di scorrimento di alto livello. La palette e i font restano gli stessi; cambia il linguaggio visivo (DECISIONS.md, D-058): - palchi navy arrotondati per hero, testate, credenziali, banda CTA e footer; servizi in griglia bento con la prima card in evidenza; nuova sezione «Come lavoriamo»; fascia di numeri ricavati dai dati; menu mobile a tutto schermo; indice laterale fermo nelle pagine legali, che segue la lettura (toc.ts); - movimento solo CSS (scroll-driven animations e View Transitions), dentro @supports e prefers-reduced-motion: senza supporto o con «riduci movimento» tutto resta fermo e visibile. La comparsa usa solo spostamento e scala, mai l'opacità, che lasciava semitrasparente il testo sul bordo della finestra; - budget di 120 KB rispettato con lo scoping a classi, il marchio richiamato con <use> e gli stili di checklist e documenti in file separati; - compatibilità con Safari/iOS 15 e Firefox: overflow: clip in un blocco @supports separato (il minificatore eliminava la riserva hidden), nessun :has() per gli stacchi tra i palchi; - stampa dei palchi in nero su bianco, dichiarazione di accessibilità e decisioni aggiornate (D-042 superata in parte, deroga a §2.6 per toc.ts). Testi nuovi da far confermare allo Studio: TODO-STUDIO.md, C14. Verifiche: eslint, prettier, astro check, build, html-validate, link, conformità (1467 controlli), Playwright e2e e a11y (90 superati), Lighthouse (prestazioni 98-100, accessibilità, best practice e SEO 100), pacchetto v1.1.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
67 KiB
Registro delle decisioni
Ogni scelta non banale presa durante lo sviluppo (brief §0.4). Formato: data · contesto · scelta · alternative scartate · motivazione.
D-001 — Repository esistente su Gitea e branch di lavoro
- Data: 2026-10-15
- Contesto: il brief (§14.0) prevede
git init, ma il repositoryBalboSoft/Studio_Grassoesiste già su Gitea con un commit iniziale (README di due righe e.gitignore). - Scelta: si lavora sul clone del repository esistente. Lo sviluppo avviene sul branch
feat/sito-v1(un commit per fase, Conventional Commits in italiano); a fine fase 8 il branch viene unito inmaincon un merge commit (--no-ff), cosìmainlocale è pronto per il push. - Alternative scartate:
git initdi un nuovo repository (perderebbe la storia remota e richiederebbe un push forzato); commit diretti sumain(meno leggibile la storia per fasi). - Motivazione: conserva la storia remota, nessun push forzato necessario,
mainresta pulito fino al merge finale.
D-002 — Sostituzione del .gitignore iniziale
- Data: 2026-10-15
- Contesto: il
.gitignoredel commit iniziale è il modello «VisualStudio» (C#/.NET), non pertinente a un progetto Node/Astro. - Scelta: sostituito con un
.gitignorespecifico (node_modules,dist,release,.astro,test-results,playwright-report,.lighthouseci, file di sistema). - Alternative scartate: aggiungere le voci in coda al modello esistente (centinaia di regole inutili, alcune potenzialmente fuorvianti).
- Motivazione: semplicità e chiarezza (§0.3, punto 4).
D-003 — Versione di Node.js
- Data: 2026-10-15
- Contesto: il brief chiede «Node.js LTS corrente (≥ 22)». A ottobre 2026 la LTS attiva è Node 24 (Krypton); Node 22 è in manutenzione.
eslint-plugin-astro3.x richiede Node^22.22.3 || ^24.16.0 || >=26.3.0, Astro 7 richiede>=22.22.0. - Scelta:
.nvmrc=24;engines.node=>=22.22.3. Sviluppo e test eseguiti con Node 24.22.0. - Alternative scartate: Node 22 come riferimento (LTS in manutenzione);
engines>=24(escluderebbe inutilmente Node 22 aggiornato). - Motivazione: LTS attiva per lo sviluppo, compatibilità dichiarata con il minimo realmente supportato dalle dipendenze.
D-004 — Astro 7.4.0
- Data: 2026-10-15
- Contesto: il brief chiede l'ultima versione stabile di Astro, verificata con
npm view astro version. - Scelta:
astro@7.4.0(risultato dinpm view astro versionil 2026-10-15), con@astrojs/sitemap@3.7.4. - Alternative scartate: nessuna (requisito esplicito).
- Motivazione: requisito del brief §3.1.
D-005 — TypeScript 6.0.3 invece di 7.0.2
- Data: 2026-10-15
- Contesto: l'ultima TypeScript è la 7.0.2, ma
@astrojs/check@0.9.10dichiaratypescript ^5 || ^6etypescript-eslint@8.71.2richiedetypescript <6.1.0. - Scelta:
typescript@6.0.3(ultima 6.x), modalitàstricttramiteastro/tsconfigs/strict. - Alternative scartate: TypeScript 7 (fuori dai peer delle dipendenze, rischio di
astro checknon funzionante). - Motivazione: compatibilità garantita dalle dipendenze ufficiali.
D-006 — Playwright 1.56.1 (versione bloccata)
- Data: 2026-10-15
- Contesto: il brief usa come riferimento l'immagine CI
mcr.microsoft.com/playwright:v1.56.0-noblee chiede che coincida con la versione di@playwright/test. L'ambiente di sviluppo dispone di Chromium revision 1194, quella usata da Playwright 1.56.x; le versioni successive (1.57+) richiedono un Chromium diverso. - Scelta:
@playwright/test@1.56.1eplaywright@1.56.1(ultima patch della 1.56); immagine CImcr.microsoft.com/playwright:v1.56.1-noble. - Alternative scartate: Playwright 1.64.1 (richiederebbe lo scaricamento di un nuovo browser e un'immagine diversa da quella indicata nel brief).
- Motivazione: test riproducibili in locale e in CI con lo stesso browser; aggiornare Playwright significa aggiornare insieme
package.jsone l'immagine dei workflow (documentato nel README).
D-007 — Versioni esatte delle dipendenze
- Data: 2026-10-15
- Contesto: riproducibilità della build e del pacchetto di rilascio.
- Scelta: tutte le dipendenze sono dichiarate con versione esatta (senza
^) epackage-lock.jsonè committato; la CI usanpm ci. - Alternative scartate: intervalli semver (
^x.y.z). - Motivazione: build identiche nel tempo; gli aggiornamenti diventano commit espliciti.
D-008 — Avvisi di npm audit sulle dipendenze di sviluppo
- Data: 2026-10-15
- Contesto:
npm auditsegnala 17 vulnerabilità, tutte in dipendenze transitive di strumenti di sviluppo (soprattutto@lhci/cli:tmp,uuid,basic-ftp,extract-zip).npm audit --omit=dev= 0 vulnerabilità. - Scelta: nessuna azione; nessuno di questi pacchetti finisce nel sito pubblicato (che contiene solo file statici).
- Alternative scartate:
npm audit fix --force(introdurrebbe versioni incompatibili e romperebbe Lighthouse CI). - Motivazione: rischio nullo per il sito pubblicato; gli strumenti girano solo in locale/CI su input fidato.
D-009 — Nessun eslint-plugin-jsx-a11y
- Data: 2026-10-15
- Contesto: le regole a11y di
eslint-plugin-astrorichiedonoeslint-plugin-jsx-a11y, che non supporta ESLint 10. - Scelta: si usa la configurazione
recommendeddieslint-plugin-astro; l'accessibilità è verificata da axe-core (tutte le pagine, due viewport), html-validate (regole WCAG) e Lighthouse (punteggio 1.0). - Alternative scartate: declassare ESLint alla 9 solo per questo plugin.
- Motivazione: copertura a11y più forte a runtime che in lint statico; toolchain aggiornata.
D-010 — Icone Lucide senza astro-icon
- Data: 2026-10-15
- Contesto: il brief consente
@iconify-json/lucide+astro-iconoppure file SVG insrc/icons/. - Scelta: componente
Icon.astroche legge i tracciati da@iconify-json/lucide(JSON) a build time e genera SVG inline conaria-hidden="true". Nessuna integrazione aggiuntiva. - Alternative scartate:
astro-icon(porta con sé@iconify/toolse decine di dipendenze transitive, compatibilità con Astro 7 non dichiarata); copiare a mano i file SVG (manutenzione più scomoda). - Motivazione: zero runtime, meno dipendenze, stesso set di icone (Lucide, licenza ISC).
D-011 — Script segnaposto in fase 0
- Data: 2026-10-15
- Contesto: il brief chiede di definire in fase 0 tutti gli script npm di §3.3 «anche se vuoti».
- Scelta: gli script in
scripts/sono creati come segnaposto e implementati nelle fasi 1 (icone), 6 (test) e 7 (packaging e release). - Alternative scartate: nessuna.
- Motivazione: requisito del brief §14.0.
D-012 — Mockup e brief in docs/
- Data: 2026-10-15
- Contesto: i mockup sono stati forniti in formato WebP (non PNG come indicato nell'Appendice A).
- Scelta: copiati in
docs/mockups/con i nomi dell'Appendice A ed estensione.webp; il brief completo è conservato indocs/BRIEF.mdcome riferimento dei requisiti. - Alternative scartate: convertirli in PNG (file più pesanti senza benefici).
- Motivazione: il riferimento visivo resta nel repository insieme ai requisiti.
D-013 — Generazione di marchio e icone con tracciati vettoriali
- Data: 2026-10-15
- Contesto: favicon,
apple-touch-icon, immagine Open Graph elogo.svgdevono riprodurre la «G» e il logotipo in Fraunces/Inter. Un SVG con testo dipende dai font installati sul sistema (librsvg/sharp usa fontconfig);fontkitnon gestisce correttamente i font variabili WOFF2 e il motore di shaping diopentype.jsnon supporta tutte le tabelle GSUB di questi font. - Scelta:
scripts/generate-icons.mjslegge le versioni statiche WOFF (@fontsource/fraunces,@fontsource/inter, solo sviluppo) conopentype.js, impagina i testi glifo per glifo e li converte in tracciati SVG; sharp genera i PNG e il file ICO (PNG incapsulati). I file generati sono committati e rigenerabili connpm run icons. - Alternative scartate: testo SVG con font di sistema (risultato diverso da macchina a macchina); screenshot con Chromium (dipendenza dal browser per un'operazione grafica); disegnare la «G» a mano (non sarebbe Fraunces).
- Motivazione: risultato identico ovunque, nessun font di sistema richiesto, nessuna rete.
D-014 — Menu mobile con <dialog> modale e alternativa senza JavaScript
- Data: 2026-10-15
- Contesto: il menu mobile deve avere pulsante con
aria-controls/aria-expanded, chiusura con Esc e focus gestito, ma il sito deve restare navigabile senza JavaScript (§2.6). Script inline non sono ammessi dalla CSP. - Scelta: pulsante +
<dialog>aperto conshowModal()(sfondo inerte, Esc nativo, focus sul pulsante «Chiudi» e ritorno al pulsante menu). Un blocco<noscript><style>(consentito dalla CSP:style-src 'unsafe-inline') nasconde i pulsanti che richiedono JS e mostra le voci di menu sotto il logo; il sottomenu desktop resta raggiungibile da tastiera con:focus-withine la voce «Servizi» porta comunque alla pagina dei servizi. - Alternative scartate:
popover(non rende inerte lo sfondo, il focus può uscire dal menu); menu visibile di default e nascosto via JS (spostamento del layout al caricamento, CLS). - Motivazione: accessibilità completa con JS, navigazione garantita senza JS, nessuno script inline.
D-015 — Formato dei titoli di pagina
- Data: 2026-10-15
- Contesto: il brief chiede il formato «Titolo pagina — Studio Grasso | Studio Tributario e Societario, Asti» con un massimo di ~60 caratteri; il solo suffisso misura 54 caratteri, quindi il formato completo è possibile solo per titoli brevissimi.
- Scelta: regola in
src/lib/seo.ts: si usa il formato completo se il titolo resta entro 65 caratteri, altrimenti «Titolo — Studio Grasso, Asti», altrimenti «Titolo — Studio Grasso». La home usa «Studio Grasso | Studio Tributario e Societario, Asti». - Alternative scartate: formato completo ovunque (titoli fino a 100 caratteri, troncati nei risultati di ricerca); suffisso breve ovunque (perde le parole chiave dove c'è spazio).
- Motivazione: rispetta il formato dove possibile e la lunghezza sempre.
D-016 — Dati in src/data, testi condivisi in testi.ts, testi di pagina in pagine.ts
- Data: 2026-10-15
- Contesto: «Tutto il testo editabile sta in
src/dataesrc/content, mai hardcoded nei componenti». - Scelta:
studio.ts= anagrafica e fatti (unica fonte di verità);navigazione.ts= menu;testi.ts= testi ricorrenti (banda CTA, mappa, modulo);pagine.ts= testi e meta delle singole pagine;src/content= servizi, link utili e testi legali (Markdown). I componenti ricevono i dati come proprietà; restano nei componenti solo micro-etichette d'interfaccia (es. «Apri il menu»). - Alternative scartate: testi direttamente nelle pagine
.astro. - Motivazione: lo Studio può aggiornare i contenuti senza toccare la logica dei componenti (vedi
docs/CONTENUTI.md).
D-017 — Nessun numero di telefono attribuito alla sede di Asti
- Data: 2026-10-15
- Contesto: il mockup mostra «Tel. +39 0141 1762214» nella card della sede di Asti, ma §4.1 elenca i due numeri senza associarli a una sede.
- Scelta: i due numeri sono indicati come recapiti dello Studio; nella card di Asti compare «Su appuntamento» con il numero principale per fissare l'appuntamento.
- Alternative scartate: riprodurre il mockup (attribuzione non verificata).
- Motivazione: priorità ai fatti di §4 sui mockup (§0.3). Richiesta di conferma in TODO-STUDIO.
D-018 — URL dello scadenzario fiscale
- Data: 2026-10-15
- Contesto: §4.7 indica
https://www.agenziaentrate.gov.it/portale/scadenzario«da verificare». Dalla ricerca sul sito dell'Agenzia lo scadenzario consultabile per imposta, contribuente e data è pubblicato suhttps://www1.agenziaentrate.gov.it/servizi/scadenzario/main.php; sotto/portale/è presente solo l'archivio storico. - Scelta: si usa l'indirizzo
www1.agenziaentrate.gov.it/servizi/scadenzario/main.php. - Alternative scartate: l'indirizzo del brief (probabile 404 o archivio non aggiornato).
- Motivazione: il link deve portare allo scadenzario in uso. Il controllo dei link esterni (
npm run test:links -- --external) va eseguito prima del rilascio: dall'ambiente di sviluppo i siti esterni non erano raggiungibili (proxy).
D-019 — Aggiornamenti terminologici di §4.9 applicati ai contenuti
- Data: 2026-10-15
- Contesto: il vecchio sito usa terminologia superata (Commissioni tributarie, studi di settore, TASI, esterometro, CUD, ANF dei Comuni, bonus energia su convenzione, Camera di Commercio di Asti).
- Scelta: tutte le sostituzioni della tabella §4.9 sono applicate nei servizi (
src/content/servizi/*.md), nelle abilitazioni e nelle qualifiche (src/data/studio.ts); il copyright usa l'anno di build. Ogni voce è elencata in TODO-STUDIO «Consigliato: confermare». - Alternative scartate: riportare i testi originali (informazioni non più corrette).
- Motivazione: correttezza dei contenuti (§0.3, punto 1) con conferma finale dello Studio.
D-020 — Testo della «Consulenza societaria» come elenco
- Data: 2026-10-15
- Contesto: §4.5 riporta per la consulenza societaria tre voci in elenco e un «messaggio» descrittivo con altre attività (acquisizioni, operazioni straordinarie, contratti, arbitrati).
- Scelta: le attività del messaggio sono riportate come voci della checklist; il paragrafo introduttivo riassume struttura giuridica, adempimenti e rapporti tra soci e organi sociali.
- Alternative scartate: paragrafo unico (meno leggibile, attività difficili da individuare).
- Motivazione: stessi fatti, presentazione coerente con il layout a checklist (§7.4).
D-021 — Testi legali in Markdown con dati da studio.ts
- Data: 2026-10-15
- Contesto: privacy policy, cookie policy, note legali e accessibilità devono essere modificabili dallo Studio e coerenti con i dati (titolare, recapiti, dati societari, fornitori, modalità del modulo), che possono cambiare.
- Scelta: testi in
src/content/legali/*.md; i dati sono inseriti con segnaposto{{nome}}e blocchi condizionali<!-- se:condizione -->…<!-- /se:condizione -->risolti a build time dasrc/lib/legal.ts. Un segnaposto sconosciuto o non risolto blocca la build. La data di aggiornamento è il campoaggiornatodel frontmatter. - Alternative scartate: testi scritti nelle pagine
.astro(meno accessibili allo Studio); MDX (dipendenza in più per un'esigenza semplice). - Motivazione: un solo punto in cui cambiare un dato; testi sempre coerenti con l'uso effettivo del sito (ad esempio, con il modulo disattivato la privacy policy descrive solo i contatti via e-mail).
D-022 — robots.txt generato a build time
- Data: 2026-10-15
- Contesto: §3.2 prevede
public/robots.txt, ma la rigaSitemap:deve contenere l'URL assoluto, che dipende daSITE_URL. - Scelta:
src/pages/robots.txt.tsgeneradist/robots.txt(Allow all + Sitemap) dal valore disite. - Alternative scartate: file statico con dominio fisso (errato se cambia il dominio).
- Motivazione: correttezza garantita per qualsiasi dominio.
D-023 — Scelte sul .htaccess
- Data: 2026-10-15
- Contesto: l'hosting non è noto (§1); un
.htaccesscon direttive non permesse produce un errore 500 su tutto il sito. - Scelta: tutte le direttive dei moduli dentro
<IfModule>; redirect HTTP → HTTPS attivo (con controlloX-Forwarded-Protoper gli hosting dietro proxy), www/non-www commentato con le due varianti;RedirectMatch 301 ^/privacy/?$ /privacy-policy/al posto diRedirect 301 /privacy …(stesso effetto, senza ambiguità con/privacy-policy/); nienteOptions -Indexes(spesso vietato negli hosting condivisi): le cartelle senzaindex.htmlrispondono 404 tramite mod_rewrite; cache lunga eimmutableper i file con impronta nel nome; header CSP esattamente come §9.4 piùCross-Origin-Opener-Policy. - Alternative scartate: redirect HTTPS commentato (il problema principale del vecchio sito era l'HTTP);
<If>di Apache 2.4 per la cache (supporto incompleto su LiteSpeed). - Motivazione: massima compatibilità con gli hosting condivisi italiani senza rinunciare a HTTPS e header di sicurezza. Il passaggio a HTTPS va verificato al primo deploy (checklist in
docs/DEPLOY.md).
D-024 — public/images/README.md escluso dal sito pubblicato
- Data: 2026-10-15
- Contesto: §3.2 colloca in
public/images/README.mdl'elenco delle immagini che lo Studio può fornire; tutto ciò che è inpublic/viene copiato nel sito. - Scelta: il file resta dove previsto dal brief; una piccola integrazione in
astro.config.mjslo rimuove dadist/a fine build. - Alternative scartate: pubblicarlo (documento interno visibile online); spostarlo in
docs/(diverso dalla struttura obbligatoria). - Motivazione: struttura del brief rispettata, pacchetto di rilascio pulito.
D-025 — CSS incluso nelle pagine
- Data: 2026-10-15
- Contesto: con
assetsInlineLimit: 0(necessario perché nessuno script venga incluso inline, CSPscript-src 'self') Astro produceva 4–6 fogli di stile separati per pagina, tutti bloccanti per il rendering (segnalati da Lighthouse). - Scelta:
build.inlineStylesheets: 'always': il CSS di ogni pagina è incluso nell'HTML (consentito dastyle-src 'unsafe-inline'). La pagina più pesante (home) misura circa 95 KB di HTML + CSS non compressi, sotto il budget di 120 KB. - Alternative scartate: un unico foglio di stile esterno (una richiesta bloccante in più a ogni prima visita); soglia di inline più alta (avrebbe incluso anche gli script, vietati dalla CSP).
- Motivazione: prestazioni migliori (Lighthouse mobile 0.99–1) senza indebolire la CSP sugli script.
D-026 — Token --gold-800 per il testo delle chip
- Data: 2026-10-15
- Contesto: il testo oro
--gold-700sul fondo--gold-100delle chip dei valori ha contrasto 4.40:1, sotto il minimo 4.5:1 richiesto (§6.2). - Scelta: nuovo token
--gold-800: #806219(4.98:1 su--gold-100) usato solo per il testo delle chip; l'aspetto resta quello del mockup. - Alternative scartate: schiarire il fondo delle chip (si perde la tinta calda del mockup).
- Motivazione: contrasto AA per tutto il testo (priorità della specifica scritta sui mockup).
D-027 — Audit di Lighthouse declassati ad avviso
- Data: 2026-10-15
- Contesto: il preset
lighthouse:recommendedtrasforma in errore anche audit informativi o che dipendono dal server di test di LHCI (HTTP/1.1, assenza degli header del.htaccess), ad esempionetwork-dependency-tree-insight, che fallisce per qualsiasi catena HTML → font o script. - Scelta: in
lighthouserc.cjsrestano errori bloccanti le quattro soglie di §9.3 (Performance ≥ 0.95, Accessibility = 1, Best Practices ≥ 0.95, SEO = 1) e tutti gli audit del preset; sono declassati awarnsolo:network-dependency-tree-insight,critical-request-chains,render-blocking-insight,render-blocking-resources,uses-http2,bf-cache,csp-xss. - Alternative scartate: togliere il preset (si perderebbero i controlli puntuali).
- Motivazione: regole «rumorose» declassate come previsto dal brief (§11.6), senza allentare le soglie.
D-028 — Punti di interruzione in em e focus ciclico nel menu mobile
- Data: 2026-10-15
- Contesto: il test «testo al 200 %» (dimensione del carattere del browser raddoppiata) mostrava scorrimento orizzontale: con i punti di interruzione in px l'intestazione desktop restava attiva anche con testo doppio. Il test del menu mobile mostrava che il
<dialog>nativo lascia uscire il focus verso l'interfaccia del browser dopo l'ultimo elemento. - Scelta: media query in
em(960 px → 60em, 640 px → 40em, 1100 px → 68.75em, 420 px → 26.25em) e larghezze fisse inrem; nel menu mobile Tab/Maiusc+Tab ciclano tra il primo e l'ultimo elemento. - Alternative scartate: lasciare il comportamento nativo del dialog (accettabile ma meno prevedibile per chi usa la tastiera).
- Motivazione: WCAG 1.4.4 (ridimensionamento del testo) e 2.4.3 (ordine del focus) senza eccezioni.
- Aggiornamento (2026-10-16): il numero di telefono dell'intestazione compare da 71.25em (1140 px) invece che da 68.75em: vedi D-055.
D-029 — Correzioni ai test durante la fase 6
- Data: 2026-10-15
- Contesto: §0.6 chiede di spiegare ogni test corretto.
- Scelta:
check-compliance.mjs, controllo «commercialista»:DomUtils.findAllrestituisce solo elementi, quindi i nodi di testo non venivano esaminati; sostituito con una visita esplicita dei nodi di testo e una divisione in frasi che non spezza «Dott.», «n.», «sez.». Verificato con casi negativi iniettati (frasi errate rilevate, frasi sulla Dott.ssa Giulia Grasso accettate).- Test «testo al 200 %»: la prima versione iniettava
html { font-size: 200% }, che non agisce sulle media query e non corrisponde a nessuna impostazione reale; ora il test usa il protocollo DevTools (Page.setFontSizes) come la preferenza «Dimensione carattere» del browser. - Test axe con mappa caricata: l'iframe è contenuto di terze parti (nei test una pagina finta): escluso dall'analisi, che resta sul markup del sito.
- Alternative scartate: nessuna (i test non sono stati allentati: le soglie restano zero violazioni gravi/critiche).
- Motivazione: test corretti che verificano davvero il requisito.
D-030 — Link esterni nel Markdown e processore Markdown di Astro 7
- Data: 2026-10-15
- Contesto: in Astro 7 il processore Markdown predefinito (Sätteri) ignora
markdown.rehypePlugins(deprecato); i link esterni dei testi legali risultavano senzarel="noopener"(rilevato dacheck-compliance). - Scelta: l'HTML generato dal Markdown (servizi e testi legali) passa da
src/lib/html.ts, che aggiungerel="noopener"ai link verso altri domini; i link si aprono nella stessa scheda (§4.7). - Alternative scartate: installare
@astrojs/markdown-remarksolo per un plugin. - Motivazione: nessuna dipendenza in più, comportamento verificato dai test.
D-031 — Dipendenze di test esplicite
- Data: 2026-10-15
- Contesto:
@axe-core/playwrightdichiaraplaywright-corecome peer e npm installava la 1.64.1 accanto alla 1.56.1 di Playwright (tipi incompatibili);check-compliance.mjsusahtmlparser2, già presente come dipendenza di linkinator. - Scelta:
playwright-core@1.56.1ehtmlparser2@12.0.0dichiarati esplicitamente indevDependencies. - Alternative scartate: affidarsi alle dipendenze transitive.
- Motivazione: una sola versione di Playwright nel progetto; nessuna dipendenza usata senza essere dichiarata.
D-032 — Test del modulo con il modulo attivo
- Data: 2026-10-15
- Contesto: con la configurazione predefinita (
contactForm.mode = 'off') i test del modulo (validazione, honeypot, tempo minimo, pagina di conferma) vengono saltati. - Scelta: la variabile d'ambiente
CONTACT_FORM_MODE(off,php,endpoint) ha la precedenza sustudio.ts; i test del modulo sono stati eseguiti conCONTACT_FORM_MODE=php npm run buildseguito da Playwright (tutti verdi, insieme a html-validate, axe e conformità). Il README spiega come ripeterli. L'invio a/contact.phpè simulato nei test (nessun PHP inastro preview). - Alternative scartate: attivare il modulo per impostazione predefinita (moduli rotti su hosting senza PHP, §10.1).
- Motivazione: il modulo resta verificato anche se disattivato.
D-033 — Pacchetto di rilascio riproducibile e verificato senza dipendenze aggiuntive
- Data: 2026-10-15
- Contesto: §12.4 chiede uno zip deterministico; §11.7 chiede di aprirlo e confrontarlo 1:1 con
dist/. L'immagine CI potrebbe non avereunzip. - Scelta:
scripts/package.mjsusaarchiver(ZipArchive) con voci ordinate, permessi 0644, fuso orario UTC e data fissa =SOURCE_DATE_EPOCHo data dell'ultimo commit (il workflow di release la imposta dal commit del tag). Il contenuto didist/sta alla radice dello zip,.htaccesscompreso, senza cartelle di primo livello.check-package.mjslegge lo zip con un lettore minimale in Node (directory centrale, store/deflate, controllo CRC32); verifica che inrelease/ci sia solo lo zip, che non superi 5 MB e che percorsi, dimensioni e contenuto coincidano condist/(pagine del sitemap e.htaccesscomprese). A parità didist/lo zip è identico su Windows, macOS e Linux. Il pacchetto fallisce se il tag non coincide conpackage.json. Il pacchetto è un solo file: D-057. - Alternative scartate:
unzip/zipdi sistema (non garantiti nel container); librerie di estrazione aggiuntive. - Motivazione: integrità verificabile ovunque, nessuna dipendenza in più.
D-034 — Verifica reale di .htaccess, configurazione nginx e contact.php
- Data: 2026-10-15
- Contesto: l'hosting non è noto; un errore in
.htaccesso nel gestore PHP si scoprirebbe solo in produzione. - Scelta: durante lo sviluppo sono stati installati localmente Apache 2.4.58, nginx 1.24 e PHP 8.3: il
.htaccess(conAllowOverride All) edeploy/nginx.conf.example(connginx -t) sono stati provati servendodist/(redirect HTTPS e /privacy, barra finale, 404, file nascosti, header, cache, compressione);contact.phpè stato provato con il server integrato di PHP (405, honeypot, validazione, header injection, tempo minimo, limite di 5 invii/ora, e-mail UTF-8 con Reply-To). - Alternative scartate: nessuna verifica (solo revisione del codice).
- Motivazione: ridurre il rischio al primo deploy. Le prove non fanno parte di
npm run verify(richiedono server non presenti nel container CI).
D-035 — Workflow Gitea
- Data: 2026-10-15
- Contesto: §12.2–12.3.
- Scelta:
ci.yml(push su main, pull request, avvio manuale) con i comandi dinpm run verifynel container Playwright 1.56.1 e Node da.nvmrc, report Playwright e Lighthouse come artifact, job dei link esterni non bloccante;release.ymlsui tagv*.*.*con controllo preliminare tag/versione/CHANGELOG,SOURCE_DATE_EPOCHdal commit,verify,package, note dal CHANGELOG e pubblicazione conscripts/release-upload.sh(API REST di Gitea; tokenRELEASE_TOKENse presente, altrimenti quello automatico). Telemetria di Astro disattivata (ASTRO_TELEMETRY_DISABLED). Il deploy automatico resta un esempio non attivo (deploy/gitea-deploy.yml.example, eventorelease, varianti rsync/FTPS/rclone). - Alternative scartate: un job di deploy dentro
release.yml, che porterebbe nel workflow attivo segreti e varianti ancora da scegliere (D-047). - Motivazione: nessuna release senza test verdi; workflow che non dipendono dall'impostazione
DEFAULT_ACTIONS_URLdell'istanza (D-056). - Aggiornamento (2026-10-16):
continue-on-errordel job dei link esterni spostato sullo step,include-hidden-filesper il report Lighthouse e token personaleRELEASE_TOKEN(segreto facoltativo): vedi D-045. - Aggiornamento (2026-10-22): la CI ripete i controlli come passi separati e alla fine crea e verifica lo zip; la release è un solo file zip pubblicato senza action esterna: vedi D-056 e D-057.
D-036 — Checkbox del modulo: presa visione, non consenso
- Data: 2026-10-15
- Contesto: §10.1 riporta l'etichetta del vecchio sito («… e acconsento al trattamento dei miei dati personali…») e §8.3 indica come base giuridica l'art. 6.1.b «e, per quanto non necessario, consenso»; §8.2 chiede invece una «checkbox obbligatoria di presa visione». Un consenso obbligatorio per inviare la richiesta non è libero (art. 7.4 e considerando 43 GDPR) e renderebbe ambigua la base giuridica; inoltre non esiste un trattamento «non necessario» a rispondere.
- Scelta: per §0.3 (conformità legale prima di tutto; §8 prevale su §10) la checkbox è di sola presa visione: «Ho letto l'informativa sulla privacy». Base giuridica: art. 6.1.b (misure precontrattuali) oppure, per le richieste di sole informazioni, art. 6.1.f (legittimo interesse a rispondere). Messaggi di errore, testo della privacy e riga dell'e-mail di
contact.php(«Presa visione dell'informativa privacy: sì») sono allineati. La revoca del consenso (§8.3, punto 6) resta descritta per l'unico consenso raccolto dal sito, quello per le mappe. - Alternative scartate: etichetta del vecchio sito (consenso non libero); seconda checkbox facoltativa di consenso (nessun trattamento ulteriore da autorizzare).
- Motivazione: base giuridica univoca e conforme; nessun consenso fittizio. Da confermare con il consulente (TODO-STUDIO B4).
D-037 — Mappe di Google: base giuridica, ruoli e revoca
- Data: 2026-10-15
- Contesto: il caricamento della mappa su richiesta trasmette a Google indirizzo IP, browser e pagina di provenienza. La prima stesura citava Google solo come «titolare autonomo» nella sezione sui trasferimenti, senza base giuridica né modo di revocare la scelta, che vale per tutto il sito fino alla chiusura della scheda.
- Scelta: nella Privacy policy c'è una sezione dedicata. La base giuridica è il consenso espresso con «Carica la mappa» (art. 6.1.a GDPR e art. 122 del Codice). Per la sola raccolta e trasmissione dei dati lo Studio è contitolare con Google Ireland Limited (CGUE, C-40/17 «Fashion ID»); i trattamenti successivi sono di Google come titolare autonomo. Il trasferimento a Google LLC avviene sulla base dell'EU-U.S. Data Privacy Framework, a cui Google dichiara di aderire (decisione di adeguatezza del 10/7/2023). Il riquadro avvisa che la scelta vale per tutte le mappe del sito: il clic carica tutte le mappe della pagina (focus su quella richiesta) e quelle delle pagine successive. Per la fase di contitolarità lo Studio è indicato come punto di contatto (art. 26 GDPR; l'accordo con Google è da verificare, TODO B4). Sotto ogni mappa caricata compare il pulsante «Non caricare più le mappe»: cancella la voce di
sessionStorage, rimuove gli iframe della pagina e riporta il focus sul pulsante di caricamento. La revoca è verificata datests/e2e/privacy.spec.ts. La Cookie policy è allineata. - Alternative scartate: consenso valido per un solo riquadro (costringerebbe a ripetere il clic in ogni pagina e il comportamento è già noto agli utenti); nessun comando di revoca, perché chiudere la scheda non è «facile quanto dare il consenso» (art. 7.3).
- Motivazione: informativa completa per l'unico contenuto di terze parti del sito.
D-038 — contact.php: limite di invii con dati minimi e cancellazione automatica
- Data: 2026-10-15
- Contesto: il limite di 5 invii all'ora creava nella cartella temporanea di sistema un file per IP. Il nome era un SHA-256 dell'IP con un sale facile da indovinare (quindi invertibile per forza bruta) e i file restavano con i permessi predefiniti, senza mai essere cancellati. Su un hosting condiviso altri utenti potevano leggerli, e la privacy policy non diceva nulla di questo trattamento.
- Scelta:
- Il nome del file è un HMAC-SHA256 dell'IP, calcolato con un segreto casuale di 32 byte generato al primo uso.
- I contatori stanno in una cartella privata fuori dalla webroot, configurabile (
CARTELLA_LIMITI, predefinita../.studio-grasso-form). Se quella non si può usare, si ripiega su una sottocartella della cartella temporanea, accettata solo se ha permessi 0700; altrimenti il limite non si applica. - I file sono creati con permessi 0600 e quelli più vecchi di un'ora vengono cancellati a ogni invio.
- Il blocco «moduloPhp» della Privacy policy dichiara il trattamento: impronta crittografica (HMAC) dell'IP e orario, usati per un'ora e cancellati al primo invio successivo, base giuridica art. 6.1.f. DEPLOY.md suggerisce un cron facoltativo per la cancellazione entro l'ora anche senza nuovi invii.
- Il comportamento è stato provato con il server integrato di PHP 8.3: 5 invii accettati e il 6° rifiutato con 429, permessi 0700/0600, contatore vecchio cancellato.
- Alternative scartate: nessun limite per IP, che sarebbe meno sicuro; un database, che non esiste su tutti gli hosting.
- Motivazione: minimizzazione dei dati e limitazione della conservazione (art. 5.1.c ed e GDPR), sicurezza (art. 32 GDPR).
D-039 — Testi legali e del modulo guidati dalla configurazione
-
Data: 2026-10-15
-
Contesto: alcune frasi erano vere solo in una configurazione. Esempi:
- la nota «nessun dato a terze parti», falsa in modalità
endpoint; - il consenso e i campi del modulo citati anche con il modulo spento;
- «il sito non trasferisce dati fuori dall'UE» affermato senza conoscere i fornitori.
Inoltre l'informativa breve del modulo indicava il titolare con un generico «lo Studio».
- la nota «nessun dato a terze parti», falsa in modalità
-
Scelta: nuovi dati in
studio.ts:fornitori.modulo, obbligatorio in modalitàendpoint: senza, la build si ferma;fornitori.soloSee,falsefinché la verifica di TODO-STUDIO B2 non è fatta.
Nuove condizioni nei testi legali:
soloSee,pecProfessionistie la negazionese:!modulo, già supportata. Nuovi segnaposto:{{fornitoreModulo}}e{{pecProfessionisti}}. I segnaposto dei fornitori includono la preposizione articolata («comunicati al fornitore…»).Il componente del modulo cambia così:
- l'informativa breve è composta con denominazione, indirizzo, durata di conservazione ed e-mail presi da
studio.ts; - la nota sul destinatario dei dati è diversa per
phpedendpoint; - i messaggi di validazione passano da
testi.tsaform.tstramitedata-messages, quindi c'è un'unica fonte dei testi.
La pagina Accessibilità descrive il modulo solo se è attivo e include tra gli usi di JavaScript lo script delle ancore del vecchio sito.
-
Alternative scartate: testi fissi da correggere a mano a ogni cambio di configurazione.
-
Motivazione: nessuna affermazione falsa in nessuna modalità (§2.3, §8).
D-040 — Convenzioni dei testi dopo la revisione finale
- Data: 2026-10-16
- Contesto: la revisione dei testi ha segnalato forme diverse per lo stesso oggetto, ripetizioni tra sottotitolo e primo paragrafo nelle pagine dei servizi, una voce narrante mista nella pagina «Lo studio» e un superlativo nei valori (§6.4).
- Scelta:
- «lo Studio» con la maiuscola quando indica lo Studio Grasso (forma già prevalente, usata anche nei testi legali); «Lo studio» resta solo come nome della pagina e della voce di menu (§5).
- «Centro autorizzato CAF» per il servizio (titolo, menu, home), come nel titolo di §4.5; le qualifiche personali del Dott. Ezio Grasso (schede e badge) usano la dicitura ufficiale «Centro Autorizzato Servizi C.A.F.» (§4.2, §8.1).
- Prima persona plurale in «Chi siamo»; primi paragrafi dei servizi che aggiungono informazioni invece di ripetere il sottotitolo (nessuna voce di §4.5 tolta).
- Il testo del riquadro della mappa è quello di §10.2, con in più la frase sulla durata della scelta (D-037).
- Nella scheda estesa dei professionisti la prima qualifica non ripete la qualifica principale già mostrata sotto il nome; le Note legali riportano il testo completo.
- Fatti scritti nei componenti (nome della sede di Asti, «Su appuntamento», «Per fissare un appuntamento») spostati in
studio.ts/testi.ts; il telefono per sede è il campo facoltativosede.telefono. - Spazi non separabili tra CAP, località e provincia e dopo «n.», «sez.», «L.», «D.Lgs.» nei badge e nelle schede.
- Alternative scartate: «studio» minuscolo ovunque (più modifiche nei testi legali da far validare).
- Motivazione: coerenza e fedeltà ai fatti di §4 senza cambiarne il contenuto.
D-041 — Pagine noindex senza canonical
- Data: 2026-10-16
- Contesto: la 404 aveva un canonical
/404/inesistente (il file è/404.html, servito a qualsiasi indirizzo inesistente). - Scelta: le pagine noindex (404 e conferma del modulo) non hanno né
canonicalnéog:url;check-complianceesmoke.spec.tslo verificano, senza più eccezioni per la 404. - Alternative scartate: canonical
/404.html(una pagina d'errore non deve essere indicata come versione preferita). - Motivazione: canonical sempre corretti (§9.1, §11.4).
D-042 — Pagine legali a colonna singola; link della mappa sotto il riquadro
Superata in parte da D-058: da 1024 px l'indice sta in una colonna laterale; la colonna di lettura resta singola. La parte sui link della mappa resta valida.
- Data: 2026-10-16
- Contesto: le pagine legali avevano su desktop l'indice in una colonna laterale, mentre §7.8 chiede un layout «documento» a colonna singola (max 68 ch) con indice interno. Il mockup 03 mostra i link «Apri in Google Maps / OpenStreetMap» dentro il riquadro della mappa; nel sito sono sotto.
- Scelta: pagine legali a colonna singola con l'indice in testa, a tutte le larghezze (la specifica scritta prevale sui mockup). I due link della mappa restano sotto il riquadro: così sono visibili anche dopo il caricamento dell'iframe e senza JavaScript (§10.2), accanto al pulsante «Non caricare più le mappe». Nelle card delle sedi sono allineati a sinistra come le altre azioni.
- Alternative scartate: spostare i link dentro il riquadro e poi fuori dopo il caricamento (layout che cambia a ogni stato).
- Motivazione: §7.8 e §10.2; un solo asse di allineamento nelle card.
D-043 — Release: note dal CHANGELOG e pubblicazione con l'API REST
- Data: 2026-10-16
- Contesto: le note della release sono la sezione del CHANGELOG, che contiene apici inversi e virgolette: passate come testo a una shell o a un'action, rischiano di essere alterate o di rompere il comando. Un'action esterna di release aggiungerebbe inoltre dipendenze da verificare nell'immagine Playwright. Gli eventi prodotti con il token automatico del workflow non avviano altri workflow (deploy automatico, D-047).
- Scelta: la release è pubblicata da
scripts/release-upload.sh(solo curl e node), che legge le note dal CHANGELOG conchangelog-notes.mjse le inserisce nel JSON con node, senza passare da interpolazioni di shell. Nessuna action esterna di release. Token:RELEASE_TOKENse presente, altrimenti quello automatico. Il deploy di esempio non esclude piùcontact.phpe protegge.well-known/,.user.iniecgi-bin/. - Alternative scartate: un'action esterna di pubblicazione (una dipendenza in più da raggiungere e da tenere aggiornata, con le note passate come testo alla shell); note senza alcuna trasformazione passate a una riga di shell.
- Motivazione: nessuna release bloccata o alterata da un dettaglio dell'istanza o del testo delle note. Consigliato un primo rilascio di prova sull'istanza reale prima di comunicare la versione.
- Aggiornamento (2026-10-16): il token personale è solo
RELEASE_TOKEN: i nomi dei segreti che iniziano conGITEA_oGITHUB_sono riservati (D-045). Lo script crea la release in bozza e la pubblica dopo i file (D-046). - Aggiornamento (2026-10-22): la pubblicazione passa solo dallo script, senza altri passi di ripiego (D-056). L'opzione
--shell-safedichangelog-notes.mjsnon serve più ed è stata tolta.
D-044 — Controlli coerenti con la configurazione e portabili
- Data: 2026-10-16
- Contesto: la revisione del codice ha trovato tre situazioni in cui
verifyfalliva senza un difetto del sito, più due problemi di portabilità su Windows:- la modalità
endpointcon la CSP aggiornata; - una release a cavallo d'anno, con
SOURCE_DATE_EPOCHdell'anno precedente; - il controllo dei link esterni, che verificava canonical e JSON-LD sul dominio di produzione, dove c'è ancora il vecchio sito;
- su Windows:
import()con un percorso assoluto e il checkout con CRLF.
- la modalità
- Scelta:
- La CSP è confrontata per direttive; una direttiva ripetuta è un errore (il browser applica solo la prima); in modalità
endpoint,form-actiondeve contenere anche l'origine dicontactForm.endpoint(provato con una configurazione temporanea). - L'anno del footer è calcolato con
src/lib/build.ts, lo stesso modulo usato dal sito. - Gli URL del dominio del sito sono riscritti verso la build locale e controllati lì.
- Portabilità: import con URL
file://,.gitattributesconeol=lf. - Altre correzioni:
- il ripiego di
freePortrestituisce la porta assegnata; - il pattern del telefono è valido anche con il flag
vdei browser attuali, con un test sul formato; - l'avviso di invio troppo rapido è visibile;
- Esc chiude il sottomenu aperto al passaggio del mouse (WCAG 1.4.13);
contact.phpusa il mittente della busta (-f), non richiede mbstring (rifiuta l'UTF-8 non valido prima di contare i caratteri), non produce avvisi conopen_basedire usa il fuso Europe/Rome;- Esc su un sottomenu aperto al passaggio del mouse riporta il focus sul pulsante se era su un link del sottomenu.
- il ripiego di
- La CSP è confrontata per direttive; una direttiva ripetuta è un errore (il browser applica solo la prima); in modalità
- Alternative scartate: documentare i limiti invece di correggerli.
- Motivazione:
npm run verifydeve fallire solo per difetti reali (§11) e funzionare su Linux, macOS e Windows.
D-045 — CI su Gitea: job non bloccante, artifact, token e runner
-
Data: 2026-10-16
-
Contesto: la revisione dei workflow ha trovato difetti che si sarebbero presentati con il runner online:
continue-on-errora livello di job non è garantito dalla documentazione di Gitea Actions: il job «Link esterni (non bloccante)» avrebbe potuto rendere rossa la CI al primo sito esterno irraggiungibile;- il report Lighthouse sta in una cartella nascosta (
.lighthouseci/): senza un'indicazione esplicita, il caricamento degli artifact potrebbe non includerla; - i nomi dei segreti che iniziano con
GITEA_oGITHUB_sono riservati: il token personale per le release non può chiamarsiGITEA_TOKEN, serve un nome diverso (RELEASE_TOKEN).
-
Scelta:
continue-on-errorsullo step «Controllo dei link esterni», non sul job;include-hidden-files: truenell'upload del report Lighthouse: dalla v3.2.0upload-artifactesclude per impostazione predefinita i file e le cartelle nascosti, come.lighthouseci/, e l'opzione è quella che li fa caricare;- token
secrets.RELEASE_TOKEN || secrets.GITHUB_TOKENin release.yml; upload-artifact@v3, perchéactions/upload-artifact@v4fallisce su Gitea conGHESNotSupportedError(D-056);runs-on: ubuntu-latestin tutti i job, il label predefinito diact_runner, con un commento che invita ad adattarlo se il runner ne usa un altro;- variabile del repository
SITE_URLpassata a build e test di CI e release (D-051).
I job sono stati eseguiti in locale negli stessi container del runner (Playwright 1.56.1 noble come root, node:24): verdi,
verifyin circa 6 minuti. -
Alternative scartate:
actions/upload-artifact@v4(non funziona su Gitea); il controllo dei link esterni in un workflow pianificato (si perderebbe il controllo a ogni push). -
Motivazione: la CI deve diventare verde appena un runner con label
ubuntu-latestè online, senza altre correzioni.
D-046 — Release: pubblicazione dopo i file e controllo del tag
-
Data: 2026-10-16
-
Contesto:
scripts/release-upload.sh:- creava la release già pubblicata prima di caricare i file;
- lasciava in bozza una release rimasta a metà dopo un errore;
- cancellava un file prima di caricare il nuovo;
- non verificava il tag (senza tag Gitea lo crea sulla punta del branch predefinito).
-
Scelta:
- release nuova: bozza, file, poi pubblicazione con titolo e note del CHANGELOG;
- release esistente, anche in bozza: caricamento del nuovo file, cancellazione del vecchio, pubblicazione;
- tag verificato sul server e confrontato con quello locale.
Provato contro un'API simulata in 7 scenari: release nuova, bozza, release pubblicata, tag mancante, tag diverso, errore di caricamento su release nuova e su release pubblicata.
-
Alternative scartate: chiedere una conferma (es.
FORCE=1) per sostituire i file di una release pubblicata. È il comportamento documentato, e ora la sostituzione non lascia mai la release senza un file. -
Motivazione: nessuna release pubblicata senza file o con il tag sul commit sbagliato.
D-047 — Deploy automatico di esempio: evento, ultima release e percorsi protetti
- Data: 2026-10-16
- Contesto:
scripts/release-upload.sh(usato da release.yml) crea la release in bozza, carica lo zip e solo allora la pubblica; poiché il tag esiste già, Gitea notifica il passaggio come modifica della release («edited») e non come «published». L'esempio ascoltava solo «published» e quindi non partiva. Non escludeva le pre-release, e con un segretoDEPLOY_PATHmancantersync --deleteavrebbe sincronizzato la radice del server. - Scelta:
- eventi
publishedededited(i due tipi che Gitea supporta perrelease); - un job «controllo» lascia proseguire solo una release stabile che sia l'ultima pubblicata e, per «edited», solo se lo zip è stato caricato nell'ultima ora (la pubblicazione di release.yml o di release-upload.sh): una modifica successiva di titolo o note, anche dell'ultima release, non avvia il deploy; l'avvio manuale procede sempre, con un tag nel formato
vX.Y.Z; - se l'API delle release non risponde lo step fallisce, invece di saltare il deploy in silenzio;
- download dello zip
sito-studio-grasso-vX.Y.Z.zipcon il token automatico, controllo di integrità (unzip -t) e della presenza diindex.htmle.htaccess; dominio per il controllo finale dalla variabileSITE_URLo dalla rigaSitemap:delrobots.txtcontenuto nello zip; - l'avvio automatico richiede che la release sia pubblicata con il token personale (
RELEASE_TOKEN): Gitea non avvia workflow in risposta a ciò che fa il token automatico di un altro workflow; senza il segreto si avvia a mano dalla scheda Actions; - controlli su
DEPLOY_PATH,FTP_PATHeRCLONE_DEST; per rsync, sincronizzazione solo se nella cartella c'è il file di conferma.deploy-studio-grasso, creato a mano una volta.
- eventi
- Alternative scartate: un job di deploy dentro release.yml attivato da una variabile: più robusto, ma porta nel workflow attivo segreti e varianti commentate. Scartato anche il solo evento
published, che con la pubblicazione da bozza non scatta. - Motivazione: l'esempio deve funzionare quando viene attivato, non deve ripubblicare versioni per una semplice modifica delle note e non deve poter sincronizzare con
--deleteuna cartella diversa da quella del sito (per FTP la guida avverte di non indicare la radice dell'account).
D-048 — Browser supportati dal CSS generato
- Data: 2026-10-16
- Contesto: Astro imposta
build.target: 'esnext', quindi il minificatore (lightningcss) lavorava senza browser di riferimento. Scriveva le media query in sintassi a intervallo(width<=60em), che Safari e iOS ignorano prima della 16.4: niente layout mobile su iPhone fermi a iOS 15. Scartava inoltrebackdrop-filterscritto prima della forma con prefisso. - Scelta:
vite.build.cssTarget: ['chrome107', 'edge107', 'firefox104', 'safari15', 'ios15'];- in Header.astro solo la forma standard di
backdrop-filter(il prefisso lo aggiunge lightningcss); - check-compliance verifica che non ci siano media query a intervallo e che
-webkit-backdrop-filtersia sempre accompagnato dalla forma standard.
- Alternative scartate:
browserslistin package.json (il CSS minificato da Vite seguecssTarget); la sintassi a intervallo, che esclude iOS 15. - Motivazione: il sito deve funzionare anche sui telefoni che non si aggiornano oltre iOS 15.
D-049 — Anello di focus con contrasto misurato
- Data: 2026-10-16
- Contesto: l'anello oro
--gold-500aveva un contrasto di 2,68–2,97:1 sui fondi chiari (WCAG 1.4.11 chiede 3:1). Il test verificava solo che l'outline ci fosse. - Scelta:
- token
--focus-ring:--gold-700sui fondi chiari (almeno 4,28:1); --gold-500nei contenitori navy con elementi focalizzabili (barra superiore, footer, banda CTA, riquadro delle pagine dei servizi), dove--gold-700arriverebbe a 2,9:1;- il test da tastiera calcola il contrasto tra l'anello e il fondo (anche semitrasparente o a gradiente), esige almeno 3:1 e copre anche una pagina di servizio.
- token
- Alternative scartate: un doppio anello oro e navy, più invasivo nel design.
- Motivazione: conformità AA mantenendo il «focus visibile oro» del brief (§6.3).
D-050 — Bersagli touch: 44 px sui controlli principali, deroga per percorso e barra superiore
-
Data: 2026-10-16
-
Contesto: il brief (§9.5) chiede bersagli touch di almeno 44 px. Restavano sotto:
- la freccia del sottomenu (32 px);
- i link di telefono, e-mail e PEC nei recapiti (circa 29 px);
- i link del footer su mobile (circa 33 px);
- i link del percorso e della barra superiore (testo da 13 px).
Il «ponte» invisibile del sottomenu copriva inoltre la parte bassa delle voci vicine, con clic a vuoto.
-
Scelta:
- 44 px per freccia del sottomenu, recapiti e link del footer su mobile;
- ponte eliminato: il sottomenu tocca già la voce e sta dentro il suo
<li>; - deroga per i link del percorso e della barra superiore (solo desktop): sono navigazione secondaria, le stesse destinazioni hanno bersagli da 44 px (menu principale, footer, pagina Contatti) e rispettano i 24 px di WCAG 2.2 (2.5.8).
-
Alternative scartate: percorso e barra superiore a 44 px, che cambierebbero l'altezza della testata delle pagine e della barra rispetto ai mockup.
-
Motivazione: le azioni principali da telefono (chiamare, scrivere, aprire il sottomenu) hanno bersagli comodi senza stravolgere il design.
D-051 — Dati da un'unica fonte e controlli che leggono i dati
-
Data: 2026-10-16
-
Contesto: alcuni controlli confrontavano valori scritti a mano: orari, esattamente 6 servizi, l'e-mail, etichette e titoli. Alcune modifiche indicate in docs/CONTENUTI.md facevano quindi fallire
verifycon il sito corretto. Erano duplicati non derivati:- i giorni di apertura del JSON-LD;
- la ricerca per indirizzo e il titolo delle mappe;
- il numero breve dell'intestazione;
- il dominio, ripetuto in cinque file.
-
Scelta:
orari.giorniSettimanain studio.ts;mapQuery,mapTitleetelNationalin format.ts (riproducono esattamente i valori precedenti);site.config.mjscome unica fonte del dominio;- controlli e test che leggono studio.ts, testi.ts, pagine.ts e navigazione.ts;
- servizi: almeno i 6 del brief, verificati per slug e ancora del vecchio sito, con slug e ancore univoci.
check-compliance controlla inoltre:
- «commercialista» anche in meta, attributi e JSON-LD;
- le direttive del .htaccess solo su righe attive; HSTS commentato, oppure attivo con
HSTS_ATTIVO = truenello stesso script (scelta esplicita, documentata in DEPLOY.md); contact.phppresente solo in modalitàphp;- nessun contenuto dopo
</html>(lo script di/servizi/era fuori dal layout).
-
Alternative scartate: documentare quali test aggiornare a ogni modifica dei contenuti.
-
Motivazione:
verifydeve fallire solo per difetti reali (D-044), e le modifiche descritte in CONTENUTI.md devono funzionare.
D-052 — Modulo di contatto: stesse regole nel browser e in contact.php
-
Data: 2026-10-16
-
Contesto: con il modulo attivo il browser accettava valori che contact.php rifiutava: campi di soli spazi, e-mail senza dominio completo, testi vicini al limite con gli a capo contati due volte (CRLF). Gli altri problemi:
- il tempo minimo confrontava l'orologio del dispositivo con quello del server;
- il corpo dell'e-mail era in 8bit con righe di lunghezza illimitata, che i server di posta rifiutano oltre 998 byte;
- l'oggetto era codificato in un'unica parola;
- i messaggi d'errore non indicavano il requisito;
- due stili con scope non raggiungevano i contenuti generati;
- la modalità si attivava modificando un'espressione (e il lint falliva).
-
Scelta:
- validazione con
trim, lunghezza minima in caratteri comemb_strlen(un'emoji vale 1) e unpatterndell'e-mail allineato aFILTER_VALIDATE_EMAILnei casi comuni (parte locale fino a 64 caratteri, punto nel dominio, ultimo segmento che inizia con una lettera); - campo
ts_invio, così la durata è misurata con un solo orologio; calcolo in virgola mobile, perché con PHP a 32 bit i millisecondi superanoPHP_INT_MAX; - a capo normalizzati prima di misurare;
- corpo in quoted-printable;
- oggetto in parole RFC 2047 di al massimo 75 caratteri;
- messaggi con il requisito (
{min}); :global()per gli stili dei contenuti generati;- costante
MODALITA_PREDEFINITAin studio.ts.
Provato con PHP 7.4 e 8.3: 23 controlli superati, mentre con il gestore precedente ne falliscono 11.
- validazione con
-
Alternative scartate: sostituire
tscon la sola durata scritta all'invio: un programma che chiamaform.submit()non genera l'evento e passerebbe il controllo. -
Motivazione: nessuna richiesta rifiutata dal server dopo che il browser l'ha accettata, e nessuna e-mail respinta dal server di posta.
D-053 — nginx: header di sicurezza in un solo punto
- Data: 2026-10-16
- Contesto: in nginx un
add_headerdentro unalocationannulla tutti quelli ereditati. HSTS, una volta decommentato, non arrivava a pagine e asset, e la CSP era ripetuta in due punti. - Scelta: nessun
add_headernellelocation; Cache-Control da unamapsull'indirizzo (senzaalways, così le risposte d'errore non vengono messe in cache); la riga HSTS commentata anche nel blocco HTTPS del dominio senza «www», da attivare insieme a quella principale. Verificato con nginx:stable in Docker:nginx -t, header di pagine, asset, icone, sitemap, 404 e redirect; con HSTS attivato, HSTS su tutte le risposte, compreso il redirect dal dominio senza «www». - Alternative scartate: uno snippet con gli header incluso in ogni
location, che richiede di installare due file. - Motivazione: la configurazione deve essere davvero equivalente al .htaccess, che applica gli header a ogni risposta.
D-054 — Avvio in debug con VS Code
- Data: 2026-10-16
- Contesto: il manutentore ha chiesto di poter avviare il sito in debug per vederlo.
- Scelta:
.vscode/launch.json: sviluppo con Edge o con Chrome, e anteprima della build (con il taskSito: builddi.vscode/tasks.json);- Node lancia
astro.mjsconoutputCapture: "std", perché il logger di Astro scrive direttamente su stdout; serverReadyActionapre il browser con il debugger collegato (debugWithEdge/debugWithChrome,killOnServerStop), con un pattern che ignora i codici colore ANSI (su Windows Astro li scrive sempre, anche senza terminale);.gitignoreversionalaunch.jsonetasks.json.
- Alternative scartate: una configurazione composta server + browser, in cui il browser partirebbe prima che il server sia pronto.
- Motivazione: con F5 si apre il sito con i punti di interruzione attivi, senza comandi da ricordare.
D-055 — Intestazione desktop: voci su una riga e numero di telefono da 1140 px
-
Data: 2026-10-16
-
Contesto: durante il controllo visivo delle correzioni è emerso un difetto preesistente. Vicino ai punti di interruzione le etichette del menu desktop («Lo studio», «Dove siamo», «Link utili») andavano a capo su due righe: tra 961 e circa 980 px, e tra 1101 e circa 1120 px, dove compare il numero di telefono. La freccia del sottomenu portata a 44 px (D-050) allargava la prima fascia fino a circa 1000 px.
-
Scelta:
white-space: nowrapsulle voci del menu;- numero di telefono dell'intestazione da 71.25em (1140 px), perché sotto circa 1120 px non c'è spazio senza comprimere nulla (misurato pixel per pixel; il margine copre le differenze di resa dei caratteri);
- icona del telefono non comprimibile;
- tra 960 e 1020 px (63.75em) voci e spazio tra logo e menu più compatti: con le voci su una riga, lo spazio mancante ricadeva tutto sul logo, che andava a capo (con la barra di scorrimento classica di Windows anche il nome).
Misura dopo la correzione, con e senza barra di scorrimento: da 961 a 1400 px voci, numero, pulsante, nome e sottotitolo del logo su una riga, nessuna icona schiacciata e nessuno scorrimento orizzontale.
-
Alternative scartate: ridurre la spaziatura delle voci (cambia il design a tutte le larghezze); spostare il passaggio al menu mobile oltre i 960 px (punto di interruzione condiviso da molti componenti, D-028).
-
Motivazione: intestazione ordinata a ogni larghezza desktop, senza cambiare il design alle larghezze comuni.
D-056 — Repository definitivo su Gitea: workflow in .gitea/workflows
- Data: 2026-10-22
- Contesto: il repository
BalboSoft/Studio_Grassorisiede in via definitiva sull'istanza Giteahttps://gitea.encke-hake.ts.net: CI, release e deploy automatico devono funzionare con Gitea Actions (runneract_runner), senza dipendere dalla configurazione dell'istanza e indicando subito, in caso di errore, quale controllo è fallito. - Scelta:
- workflow in
.gitea/workflows/(ci.yml,release.yml); l'esempio di deploy automatico, sempre disattivato, èdeploy/gitea-deploy.yml.example, da copiare in.gitea/workflows/deploy.ymlper attivarlo; runs-on: ubuntu-latestin tutti i job, il label predefinito diact_runner; un commento in ogni workflow ricorda di adattarlo se il runner ne usa un altro. Container: Playwrightv1.56.1-noble(stessa versione di@playwright/test) per verifica e release,node:24per i link esterni;- azioni di terze parti con URL completo su github.com (
uses: https://github.com/actions/checkout@v4), così non dipendono dall'impostazioneDEFAULT_ACTIONS_URLdell'istanza; il runner deve poter raggiungere github.com; - artifact con
upload-artifact@v3, perché la v4 non funziona su Gitea (fallisce conGHESNotSupportedError); gli upload stanno su step concontinue-on-error, così un problema dello storage non rende rossa una verifica riuscita; - CI: il job «verify» ripete passo per passo
npm run verify, nello stesso ordine (lint, formattazione, controllo dei tipi, build, HTML, link interni, end-to-end, accessibilità, conformità, Lighthouse), poi crea lo zip di rilascio (scripts/package.mjs) e ne verifica il contenuto (npm run test:package); il controllo dei link esterni è un job a parte e non bloccante (D-045). Modificando gli scriptverifyotestdipackage.jsonvanno aggiornati anche i passi; - release: a ogni tag
vX.Y.Zil workflow controlla tag, versione e CHANGELOG, esegueverifyepackagee pubblica la release conscripts/release-upload.sh, che usa l'API REST di Gitea (variabiliGITEA_URL,GITEA_REPO,GITEA_TOKEN), senza action esterne di release (D-043); - token e variabili: segreto facoltativo
RELEASE_TOKEN(token personale con permessowrite:repository); se manca si usa il token automatico del workflow. I nomi di segreti e variabili non possono iniziare conGITEA_oGITHUB_. Il dominio si imposta con la variabile del repositorySITE_URL(D-051). timeout-minuteslarghi (90 perverifye per la release, 45 per il controllo dei link esterni; prima 30, 40 e 15): la rete del runner di casa è lenta. Il 22 ottobre 2026 la prima esecuzione ha impiegato più di venti minuti per scaricare l'immagine Playwright (oltre 1 GB), tre minuti per clonaresetup-nodeda github.com e minuti per le dipendenze; lo scarico dell'immagine si ripete se il runner la elimina con la pulizia delle immagini inutilizzate;- niente
cache: npminsetup-node: il server di cache del runner non è raggiungibile dal container del job (getCacheEntry failed: connect ETIMEDOUT), e a ogni esecuzione il passo aspettava circa cinque minuti prima di proseguire con un avviso. Le dipendenze si scaricano connpm ci;
- workflow in
- Alternative scartate:
- le copie delle azioni ospitate su gitea.com: restano la via d'uscita, indicata nel commento di
ci.yml, se il runner non raggiunge github.com, ma i workflow usano le azioni originali senza un secondo repository di azioni da tenere allineato; actions/upload-artifact@v4, che non funziona su Gitea;- workflow in
.github/workflows: sono scritti per Gitea Actions (URL completi delle azioni,upload-artifact@v3, label diact_runner) e la cartella indicata dalla documentazione di Gitea è.gitea/workflows/; - un unico passo
npm run verifynella CI: in caso di errore bisognerebbe leggere il log per capire quale controllo è fallito.
- le copie delle azioni ospitate su gitea.com: restano la via d'uscita, indicata nel commento di
- Motivazione: CI e release usano solo funzioni documentate di Gitea Actions e non dipendono dalle azioni predefinite dell'istanza né da action di terzi per la pubblicazione; la pagina dell'esecuzione mostra subito il controllo fallito e un errore di pacchetto emerge nella CI, non al momento del tag.
D-057 — Release con un solo file: lo zip del sito
- Data: 2026-10-22
- Contesto: la release serve a ottenere i file del sito da copiare sull'hosting per metterlo online. Il pacchetto conteneva quattro file (zip, tar.gz,
SHA256SUMS.txt,BUILD-INFO.txt): per copiare il sito bastava lo zip, il resto era da capire e ignorare. Gitea, inoltre, aggiunge da solo a ogni release due archivi, «Source code (ZIP)» e «Source code (TAR.GZ)», che contengono il codice sorgente del repository e non il sito. - Scelta: la release ha un solo file allegato,
sito-studio-grasso-vX.Y.Z.zip, con il contenuto didist/alla radice (nessuna cartella di primo livello) e.htaccesscompreso: va estratto nella cartella pubblica dell'hosting. L'archivio tar.gz,SHA256SUMS.txteBUILD-INFO.txtnon vengono più creati.package.mjscrea solo lo zip,check-package.mjsverifica cherelease/contenga solo quello (D-033) erelease-upload.shcarica i file che trova inrelease/. Versione del pacchetto: 1.0.1. Dove si spiega come scaricare il sito va detto di scegliere lo zipsito-studio-grasso-vX.Y.Z.zip, non i «Source code» di Gitea. - Alternative scartate:
- tar.gz,
SHA256SUMS.txteBUILD-INFO.txtaccanto allo zip: più file tra cui scegliere per chi deve solo copiare il sito; il tar.gz serviva ai server Linux, dove però lo zip si estrae conunzip(come nell'esempio di deploy); BUILD-INFO.txtdentro lo zip: aggiungerebbe un file alla radice pubblica del sito, raggiungibile da chiunque conosca l'indirizzo;- impronte SHA-256 separate: l'integrità è garantita dalla verifica del contenuto dello zip contro
dist/prima della pubblicazione (D-033) e, nel deploy di esempio, dal controllounzip -tdopo il download.
- tar.gz,
- Motivazione: chi pubblica il sito scarica un file e lo copia sull'hosting, senza altri passaggi. Conseguenza: i «Source code» che Gitea mette in ogni release non sono il sito, e le guide di deploy lo dicono. Il dominio per cui è costruito il pacchetto non è più scritto in
BUILD-INFO.txt: il deploy di esempio lo legge dalla variabileSITE_URLo dalrobots.txtcontenuto nello zip (D-047).
D-058 — Rework grafico: palchi scuri, movimento legato allo scorrimento, solo CSS
- Data: 2026-11-13
- Contesto: il committente ha chiesto un rework completo della grafica, «moderno, funzionale e di alto livello tecnico visivo», con elementi e pagine moderne ed effetti di scorrimento. Il brief (§6.1) prevedeva invece «movimento minimo: solo transizioni di hover». Restano validi tutti gli altri vincoli: contenuti, struttura delle pagine (§7, salvo le aggiunte elencate sotto), CSP senza script inline, nessuna risorsa di terze parti, WCAG 2.1 AA, budget di 120 KB per HTML+CSS di ogni pagina e di 15 KB per il JavaScript, Lighthouse.
- Scelta:
- Linguaggio visivo: palette e font invariati (navy, oro, carta; Fraunces e Inter), più un navy profondo (
--navy-950) per i «palchi»: blocchi scuri arrotondati, staccati dai bordi, per hero, testate interne, credenziali, banda CTA e footer. Il fondo è sempre pieno sul contenitore; trama a griglia e bagliori stanno in un livello decorativo a parte (.stage__decor), così il colore dietro testi e anelli di focus resta misurabile (test del contrasto del focus, axe). Sui palchi l'anello di focus è--gold-300(≥ 10:1). - Servizi in griglia «bento»: prima card in evidenza su due righe, l'ultima a tutta riga se resterebbe sola (con 6 servizi: 1 + 4 + 1); la card larga si dispone in orizzontale con una container query.
- Movimento: solo CSS, con le scroll-driven animations (
animation-timeline: view()/scroll()) dentro@supportseprefers-reduced-motion: no-preference: comparsa dei contenuti (.reveal,.reveal-group), barra di avanzamento della lettura, intestazione che diventa opaca, parallasse delle decorazioni, barra e numeri della sezione «Come lavoriamo». Transizioni tra pagine con@view-transition { navigation: auto }. Nessuna animazione infinita (WCAG 2.2.2): le decorazioni ruotano solo mentre si scorre. Il testo principale dell'hero non è animato (LCP). La comparsa dei contenuti usa solo spostamento e scala, mai l'opacità: legata allo scorrimento, lascerebbe semitrasparente (e sotto il contrasto AA) il testo di un blocco fermo sul bordo inferiore della finestra; axe e Lighthouse lo segnalavano su /contatti/ e /link-utili/. - Nessun cambio di altezza durante lo scorrimento: l'intestazione cambia solo fondo e ombra, per non spostare il contenuto (CLS).
- Struttura (§7): in home (§7.1) la fascia di numeri nell'hero e la sezione «Come lavoriamo» tra servizi e studio; nell'hub dei servizi (§7.3) «Come lavoriamo» tra la griglia e la banda CTA; nelle pagine legali (§7.8), da 1024 px, l'indice in una colonna laterale di 17rem, fermo durante lo scorrimento, accanto alla colonna di lettura che resta al massimo
--measure(68 ch); sotto i 1024 px, o con un solo titolo, l'indice resta in testa e il testo a colonna singola. Supera D-042 per la posizione dell'indice. - JavaScript: solo
src/scripts/toc.tsin più (meno di 1 KB): evidenzia nell'indice delle pagine legali la sezione in lettura. È un uso in più rispetto all'elenco chiuso del brief (§2.6), accettato perché non essenziale: senza JavaScript l'indice resta un elenco di link funzionante. È dichiarato nella pagina Accessibilità. Tutto il resto è CSS. - Budget:
scopedStyleStrategy: 'class'(selettori e markup più corti, stessa specificità), tracciato della «G» del marchio definito una volta per pagina e richiamato con<use>(LogoDefs), stili della checklist e dei documenti fuori dal CSS globale.
- Linguaggio visivo: palette e font invariati (navy, oro, carta; Fraunces e Inter), più un navy profondo (
- Alternative scartate:
- librerie di animazione JavaScript (GSAP, Lenis, AOS): peso oltre il budget, dipendenze in più e contenuti nascosti finché lo script non parte;
- comparsa dei contenuti con IntersectionObserver: richiede JavaScript, e senza di esso o prima del caricamento i contenuti restano invisibili; le animazioni CSS legate allo scorrimento lasciano tutto visibile dove non sono supportate;
- caroselli orizzontali su mobile per le fact card e le credenziali: aree scorrevoli senza elementi focalizzabili (axe: scrollable-region-focusable) e contenuti meno visibili;
- pulsante «torna su» fisso che compare scorrendo: invisibile ma focalizzabile in cima alla pagina; il link «Torna su» è nel footer.
- Motivazione: il sito ottiene un aspetto contemporaneo e un movimento curato senza perdere nulla di ciò che il brief garantiva: niente JavaScript necessario, niente risorse esterne, contenuti sempre leggibili e accessibili, prestazioni nel budget. La specifica §6.1 «movimento minimo» è superata da questa decisione, come §7.1, §7.3 e §7.8 nei punti indicati sopra e l'elenco degli usi di JavaScript di §2.6 per l'indice delle pagine legali; il resto del §6 resta valido.