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>
Sito web dello Studio Grasso
Sito statico dello Studio Grasso — Studio Tributario e Societario (Montegrosso d'Asti e Asti), realizzato con Astro. Nessun tracciamento, nessun cookie, nessuna risorsa di terze parti caricata senza un'azione esplicita dell'utente; pacchetto di rilascio universale (un file zip di soli file statici, con .htaccess) pronto per qualsiasi hosting.
- Requisiti di progetto:
docs/BRIEF.md· Mockup:docs/mockups/ - Decisioni tecniche:
DECISIONS.md· Dati da fornire:TODO-STUDIO.md· Novità:CHANGELOG.md - Wiki del repository (come vedere e provare il sito, CI e release, dati da fornire): Wiki · Release (lo zip del sito da mettere online): elenco delle release
- Pubblicazione sull'hosting:
docs/DEPLOY.md· Aggiornare i contenuti:docs/CONTENUTI.md· Conformità:docs/CONFORMITA.md
Requisiti
- Node.js LTS: versione in
.nvmrc(24), minimo 22.22.3. Con nvm:nvm install && nvm use. - npm (incluso in Node.js).
- Per i test: Chromium di Playwright. Se manca:
npx playwright install --with-deps chromium(una volta sola).
Avvio rapido
npm ci # installa le dipendenze esatte di package-lock.json
npm run dev # sito in sviluppo su http://localhost:4321 (si aggiorna a ogni modifica)
npm run build # genera il sito statico in dist/
npm run preview # serve dist/ su http://127.0.0.1:4321
npm run verify # tutti i controlli di qualità (gli stessi della CI)
npm run package # crea lo zip di rilascio in release/
Avvio in debug con VS Code
Dopo npm ci, aprire il pannello Esegui e debug (Ctrl+Maiusc+D), scegliere una configurazione e premere F5:
| Configurazione | Cosa fa |
|---|---|
Sito: sviluppo (Edge) / (Chrome) |
astro dev con il debugger di Node; quando il server è pronto apre il browser con il debugger collegato (punti di interruzione negli script di src/scripts/) |
Sito: anteprima della build (Edge) |
esegue npm run build e serve dist/ come in produzione su http://127.0.0.1:4321 |
Maiusc+F5 ferma il server e chiude il browser quando è selezionata la sessione del server, come all'avvio. Dopo una pausa su un punto di interruzione nel browser è selezionata la sessione del browser, e Maiusc+F5 chiude solo quella: premerlo una seconda volta, oppure usare Stop sulla sessione «Sito: sviluppo» nel pannello dello stack di chiamate. Le configurazioni sono in .vscode/launch.json e .vscode/tasks.json. Astro avvia un solo server di sviluppo per progetto: se npm run dev è già aperto in un terminale, chiuderlo prima di premere F5.
Comandi
| Comando | Cosa fa |
|---|---|
npm run dev |
server di sviluppo |
npm run build |
build statica in dist/ |
npm run preview |
anteprima di dist/ |
npm run lint |
ESLint (JavaScript, TypeScript, Astro) |
npm run format / format:check |
Prettier: corregge / verifica la formattazione |
npm run check |
astro check: tipi TypeScript e componenti |
npm run test:html |
validità HTML di tutte le pagine (html-validate) |
npm run test:links |
link interni, asset e ancore (linkinator); -- --external anche i siti esterni |
npm run test:e2e |
test end-to-end (Playwright): pagine, navigazione, menu, privacy, mappa, modulo |
npm run test:a11y |
accessibilità: axe su tutte le pagine a 1440 e 390 px, tastiera, zoom, reflow |
npm run test:compliance |
conformità (P.IVA, pagine legali, nessun tracciamento, JSON-LD, titoli professionali…) |
npm run test:lighthouse |
Lighthouse CI: Performance ≥ 0.95, Accessibility 1, Best Practices ≥ 0.95, SEO 1 |
npm test |
html + link + e2e + a11y + conformità |
npm run verify |
lint + formattazione + tipi + build + npm test + Lighthouse |
npm run package |
build + zip in release/ + verifica del contenuto dello zip (test:package) |
npm run icons |
rigenera marchio, favicon, apple-touch-icon e immagine di condivisione |
npm run verify deve terminare senza errori prima di ogni rilascio: la CI ne ripete i controlli uno per uno e release.yml lo esegue prima di creare lo zip.
Struttura
src/data/ dati e testi: studio.ts (anagrafica, sedi, orari, professionisti, abilitazioni,
partner, modulo), pagine.ts (testi delle pagine), testi.ts, navigazione.ts
src/content/ servizi/*.md, legali/*.md (privacy, cookie, note legali, accessibilità),
link-utili.json — schemi in src/content.config.ts
src/components/ componenti Astro (intestazione, footer, card, mappa, modulo…)
src/layouts/ BaseLayout.astro: <head>, SEO, dati strutturati, struttura della pagina
src/pages/ una pagina per file; servizi/[slug].astro genera le 6 pagine dei servizi
src/styles/ tokens.css (colori, tipografia, spaziature), global.css, fonts.css, print.css
src/scripts/ piccoli script: menu, mappa su consenso, modulo, ancore del vecchio sito
public/ .htaccess, favicon e immagini statiche (copiati così come sono)
scripts/ script di test, pacchetto, icone, note di rilascio, upload della release
tests/ e2e/ e a11y/ (Playwright), helpers/
deploy/ nginx.conf.example, optional-php-form/contact.php, gitea-deploy.yml.example
(esempio di deploy automatico, disattivato)
.gitea/workflows/ ci.yml (verifica e zip di prova) e release.yml (zip e pubblicazione della release)
.vscode/ launch.json e tasks.json: avvio del sito in debug (F5)
docs/ brief, mockup, guide di deploy e contenuti, conformità
site.config.mjs dominio pubblico del sito (unica fonte per build, test e pacchetto)
Configurazione
| Impostazione | Dove | Valore predefinito |
|---|---|---|
| Dominio del sito (canonical, sitemap, robots, dati strutturati) | site.config.mjs, oppure variabile SITE_URL (in CI: variabile del repository SITE_URL) |
https://www.grassoezio.it |
Modulo di contatto: off, php, endpoint |
MODALITA_PREDEFINITA in src/data/studio.ts, oppure variabile CONTACT_FORM_MODE |
off (card «Scrivici una e-mail») |
| Data riproducibile (anno nel footer, date negli archivi) | variabile SOURCE_DATE_EPOCH |
ora corrente / data dell'ultimo commit |
Le variabili valgono per tutti i comandi della sessione (build, verify, package), non solo per la build. Esempio, nel terminale di VS Code (PowerShell):
$env:SITE_URL = 'https://studiograssoezio.it'
npm run verify
Remove-Item Env:SITE_URL
In Git Bash, macOS o Linux: SITE_URL=https://studiograssoezio.it npm run verify. Per un cambio di dominio definitivo modificare invece il valore in site.config.mjs, oppure la variabile del repository SITE_URL su Gitea (Impostazioni → Actions → Variabili), che CI e release usano per la build. Lo zip della release contiene un sito costruito per quel dominio.
Per verificare il modulo attivo (validazione, anti-spam, pagina di conferma), in PowerShell:
$env:CONTACT_FORM_MODE = 'php'
npm run build
npx playwright test tests/e2e/form.spec.ts
Remove-Item Env:CONTACT_FORM_MODE
npm run build # ripristina la versione senza modulo
In Git Bash, macOS o Linux: CONTACT_FORM_MODE=php npm run build && npx playwright test tests/e2e/form.spec.ts && npm run build.
Pubblicare il repository su Gitea
Il repository è su Gitea: https://gitea.encke-hake.ts.net/BalboSoft/Studio_Grasso. In un clone il remote origin è già configurato (git remote -v per controllare). Per un repository nuovo: git remote add origin <url-del-repository>.
git push -u origin main # pubblica il codice: parte la CI (.gitea/workflows/ci.yml)
git push origin vX.Y.Z # pubblica un tag: parte la release (.gitea/workflows/release.yml)
Consigliato: proteggere il branch main (Impostazioni del repository → Branch → nuova regola per main: niente push forzati, merge solo con i controlli di stato, cioè la CI, superati) e lavorare con branch e pull request. I messaggi di commit seguono Conventional Commits in italiano (feat:, fix:, docs:, ci:, test:, chore:).
CI e release usano Gitea Actions, con i workflow in .gitea/workflows/:
ci.ymlparte a ogni push sumain, a ogni pull request e a mano dalla scheda Actions: ripete passo per passo i controlli dinpm run verify(così si vede subito quale è fallito), poi crea lo zip di rilascio e ne verifica il contenuto.release.ymlparte a ogni tagvX.Y.Z: verifica tutto, crea lo zip e lo pubblica nella sezione Release (vedi sotto).
I job girano su un runner act_runner con label ubuntu-latest, il label predefinito di act_runner (modificabile in cima ai file dei workflow). Perché i workflow partano, le Actions devono essere attive sul repository (Impostazioni del repository → «Enable Repository Actions») e il runner deve essere registrato su Gitea. I runner del repository, con i loro label, e il token per registrarne uno nuovo si trovano in Impostazioni del repository → Actions → Runner (<url-del-repository>/settings/actions/runners); i passi per l'installazione e la registrazione sono nella guida di Gitea Actions. Le azioni di terze parti (checkout, setup-node, upload-artifact) sono indicate con URL completo su github.com, quindi non dipendono dalla configurazione dell'istanza, ma il runner deve poter raggiungere github.com. I report dei test sono caricati con upload-artifact@v3: la v4 non funziona su Gitea.
Fare una release
-
Aggiornare
versioninpackage.json(SemVer: si aumenta l'ultima cifra per le correzioni, la cifra centrale per le novità, la prima per i cambiamenti importanti) enpm installper allinearepackage-lock.json. -
Aggiungere in
CHANGELOG.mdla sezione## [X.Y.Z] - AAAA-MM-GG: diventa il testo della release. -
npm run verify, commit (chore(release): prepara vX.Y.Z) e push sumain. -
Creare e pubblicare il tag:
git tag vX.Y.Z git push origin vX.Y.Z
Il workflow release.yml verifica che tag, package.json e CHANGELOG coincidano, esegue npm run verify e npm run package e pubblica nella sezione Release del repository (https://gitea.encke-hake.ts.net/BalboSoft/Studio_Grasso/releases) un solo file allegato: sito-studio-grasso-vX.Y.Z.zip. È il sito pronto da estrarre nella cartella pubblica dell'hosting: il contenuto di dist/ sta alla radice dello zip, .htaccess compreso, senza cartelle di primo livello. Il dominio del sito è quello di site.config.mjs, oppure la variabile del repository SITE_URL se impostata (vedi «Configurazione»).
Quale file scaricare: a ogni release Gitea aggiunge da solo due archivi, «Source code (ZIP)» e «Source code (TAR.GZ)». Contengono il codice sorgente, non il sito: per metterlo online scegliere sempre lo zip sito-studio-grasso-vX.Y.Z.zip. La procedura di pubblicazione sull'hosting è in docs/DEPLOY.md.
Token: per impostazione predefinita la release è pubblicata con il token automatico del workflow. Se lo step di pubblicazione fallisce con errore 403 o 404, oppure per avviare in automatico il deploy facoltativo (docs/DEPLOY.md sezione 9: le azioni compiute con il token automatico non avviano altri workflow), creare un access token (Impostazioni utente → Applicazioni → Genera nuovo token, permesso write:repository) e salvarlo come segreto del repository RELEASE_TOKEN (Impostazioni del repository → Actions → Segreti): se esiste, il workflow lo usa al posto di quello automatico. I nomi di segreti e variabili non possono iniziare con GITEA_ o GITHUB_.
La release è pubblicata da scripts/release-upload.sh (solo curl e node) con l'API REST di Gitea, senza action esterne: crea la release in bozza, carica lo zip e solo allora la pubblica. Lo stesso script serve anche a mano (istruzioni in testa al file e in docs/DEPLOY.md).
Aggiornare le dipendenze
Le versioni sono bloccate (senza ^) e package-lock.json è committato. Per aggiornare: npm install <pacchetto>@<versione> --save-exact, poi npm run verify. Playwright: la versione di @playwright/test, playwright e playwright-core deve coincidere con l'immagine mcr.microsoft.com/playwright:vX.Y.Z-noble usata in .gitea/workflows/ci.yml e release.yml (oggi 1.56.1): aggiornandola, cambiare la versione in tutti e due i file.
Note
- Le icone (favicon,
og-default.png, logo) si rigenerano connpm run iconsdopo modifiche al marchio; i file generati vanno committati. - Telemetria di Astro: disattivata in CI (
ASTRO_TELEMETRY_DISABLED=1); in localenpx astro telemetry disable. - Caratteri Fraunces e Inter: SIL Open Font License 1.1; icone Lucide: licenza ISC.