Per sviluppatori e web designer

Hai preso in consegna un sito Primavista?

Qui trovi come sono fatti i nostri siti e le regole per lavorarci senza rompere niente. Ogni progetto ha anche il suo README, con i dettagli che valgono solo per quel sito.

Base: Astro, sito statico
Ambiente: Node, versione in .nvmrc
Database: Nessuno
Pannello: /admin se previsto

In questa pagina

Com'è fatto
Primi passi
Testi e immagini
Pubblicazione
Animazioni
Buone regole
Domande
Segnala una mancanza

Com'è fatto un sito Primavista

Ogni sito è disegnato su misura, quindi non esistono due progetti identici. Quello che resta uguale è il metodo: Astro genera pagine HTML statiche, i testi stanno separati dal layout e le versioni di tutto sono scritte nel progetto.

README.md	Da leggere per primo: avvio, pubblicazione, dove sta cosa, licenze.
.nvmrc	La versione di Node con cui il sito è stato costruito.
package.json	Versioni esatte di Astro e delle librerie.
astro.config.mjs	Indirizzo del sito e impostazioni di build.
src/	Il sorgente del sito.
├ pages/	Le pagine, una per file.
├ components/	Sezioni e blocchi usati nelle pagine.
├ content/ data/	Testi, elenchi e dati delle pagine.
├ scripts/	Animazioni e piccoli comportamenti.
└ styles/	Colori, font e spazi, raccolti in variabili.
public/	Immagini, video, font, favicon e `.htaccess`.
tools/	Script per rigenerare logo e immagini, se presenti.

I nomi delle cartelle possono cambiare da un sito all'altro. In caso di dubbio vale sempre il README del progetto.

Primi passi

Usa la versione di Node indicata nel progetto e installa le dipendenze con npm ci, che rispetta le versioni bloccate nel lockfile. Con un npm install rischi di aggiornare qualcosa senza accorgertene.

terminale

nvm use          # Node della versione scritta in .nvmrc
npm ci           # dipendenze esatte
npm run dev      # sito in locale su http://localhost:4321
npm run build    # sito finale nella cartella dist/
npm run preview  # prova la build prima di pubblicarla

Testi e immagini

Ci sono due casi, e il README dice quale vale per il tuo sito.

Con pannello

Il cliente modifica da `/admin`

Il pannello (Sveltia o Decap CMS) mostra campi già pronti per testi e foto. I campi si configurano in public/admin/config.yml. A ogni salvataggio il sito si ricostruisce da solo sull'hosting.

Senza pannello

Si cambiano i file di dati

Testi ed elenchi stanno in src/content o src/data, in Markdown o JSON. Cambi il file, rifai la build e pubblichi. I componenti non vanno toccati.

Sostituire una foto

Ogni sito usa pochi formati fissi (per esempio 4:5, 3:2, 16:9) e lo stesso trattamento colore ovunque. Una foto nuova va tagliata nello stesso formato di quella che sostituisce, salvata in WebP e con il testo alternativo aggiornato. Se nel progetto c'è uno script in tools/ per le immagini, usa quello.

Pubblicazione

La build produce file statici nella cartella dist/, che possono stare su qualsiasi hosting. Non serve PHP né un database.

Build automatica

Hosting collegato al repository

Su servizi come Cloudflare Pages o Netlify ogni modifica salvata avvia la build e mette online il sito. È la strada obbligata quando c'è il pannello /admin.

Caricamento manuale

Hosting tradizionale

Fai la build in locale e carichi il contenuto di dist/ nella cartella del sito, per esempio via FTP. Ricordati del file .htaccess, che contiene redirect e cache.

Dominio, hosting e account sono intestati al cliente. Gli accessi chiedili a lui: noi non li conserviamo.

Animazioni

Molti siti usano GSAP con ScrollTrigger per le animazioni e Lenis per lo scroll morbido. Il codice sta in src/scripts e il README dice quali librerie usa il sito.

Per spegnere lo scroll morbido basta togliere l'avvio di Lenis: la pagina torna allo scroll del browser senza altre modifiche. Ogni animazione parte da contenuti già visibili, rispetta prefers-reduced-motion e la pagina si legge anche con JavaScript disattivato.

Una trappola da evitare

Non osservare con IntersectionObserver un elemento nascosto con clip-path. Le versioni recenti di Chrome lo considerano invisibile, l'animazione non parte e il contenuto resta nascosto. Osserva il contenitore oppure misura la posizione con getBoundingClientRect.

Buone regole

Sono le cose che abbiamo imparato costruendo questi siti. Seguirle ti evita la maggior parte dei problemi.

Aggiorna una dipendenza alla voltaDopo ogni aggiornamento rifai la build e controlla la pagina. Se qualcosa si rompe sai subito cosa è stato.
Scrivi solo backdrop-filterNon aggiungere a mano -webkit-backdrop-filter: il minificatore di Astro le unisce, tiene la versione con prefisso e in Chrome l'effetto vetro sparisce. Controlla sempre il CSS compilato.
Prova a 390 px di larghezzaNessuna pagina deve scorrere in orizzontale su un telefono. Elementi che entrano di lato sono la causa più frequente.
Tieni la tastiera e il movimento ridottoIl focus deve restare visibile e con prefers-reduced-motion tutto deve essere fermo e leggibile.
Non perdere la SEOLascia meta description e dati strutturati schema.org. Se cambi l'indirizzo di una pagina, aggiungi un redirect 301 da quello vecchio.
Controlla le licenze prima di sostituireFont, foto e video stock hanno licenze precise, elencate nel README. Un'immagine presa altrove va verificata prima di usarla.
Usa il logo vettorialeIl logo del cliente è in SVG nel progetto. Non sostituirlo con un PNG ridimensionato.

Domande

Posso cambiare hosting?

Sì. Il sito è fatto di file statici e funziona su qualsiasi hosting. Se c'è il pannello /admin, il nuovo hosting deve saper fare la build automatica.

Posso portare il sito su WordPress?

Si può, ma vuol dire costruirlo di nuovo: il codice Astro non si importa in WordPress. Puoi riprendere testi, immagini e scelte grafiche.

Ci sono costi ricorrenti legati al sito?

Solo quelli di hosting e dominio, che paga il cliente. Il pannello di gestione e le librerie usate sono gratuiti.

Chi decide se una modifica rompe la garanzia?

La garanzia copre i difetti presenti alla consegna, per il periodo scritto nel contratto. Le modifiche fatte dopo da altri restano a carico di chi le fa.

Manca qualcosa in questa guida?

Se un'informazione non c'è, è sbagliata o non è chiara, scrivicelo. Leggiamo tutte le segnalazioni e aggiorniamo la guida quando serve.

Informazioni mancanti, errori nella guida o nel README, suggerimenti.
Richieste di assistenza o di interventi sul sito: non rispondiamo a queste.