Questa documentazione spiega come utilizzare lo script fornito per configurare automaticamente un progetto con Tailwind CSS v4, generare un file input.css con un design system personalizzato e creare una struttura di progetto pronta all'uso.
- Salva lo script in un file, ad esempio
tailwind-starter.sh. - Rendi lo script eseguibile con il comando:
chmod +x tailwind-starter.sh
Lo script può essere eseguito in due modalità:
Richiede conferma per ogni step del processo.
./tailwind-starter.sh➡️ Ideale se vuoi controllare ogni passaggio manualmente.
Esegue tutti i passaggi senza richiedere conferma.
./tailwind-starter.sh --no-confirm➡️ Ideale per velocizzare il processo in ambienti di sviluppo ripetitivi.
Dopo l’esecuzione dello script, la struttura del progetto sarà la seguente:
├── package-lock.json # File generato da npm per gestire le dipendenze esatte.
├── package.json # Contiene le dipendenze e gli script npm del progetto.
└── src/ # Cartella principale dei file sorgente.
├── index.html # File HTML di esempio per testare le utility di Tailwind.
├── input.css # File di input contenente i token e la configurazione del design system.
└── output.css # File CSS generato automaticamente da Tailwind.
✅ Spiegazione dei file:
- package.json: Gestisce le dipendenze e le versioni dei pacchetti installati.
- package-lock.json: Blocca le versioni esatte dei pacchetti per coerenza tra ambienti.
- src/index.html: Contiene un boilerplate per testare le utility di Tailwind CSS.
- src/input.css: Include la definizione dei token e le variabili CSS per il design system.
- src/output.css: File CSS finale generato da Tailwind in base a
input.css.
Il file input.css definisce un sistema di design personalizzato tramite variabili CSS. Queste variabili sono la base per generare automaticamente le utility class di Tailwind CSS.
🔔 Importante: Utilizza sempre le variabili dei token (es. --text-color-primary, --background-color-secondary) e mai le variabili primitive (es. --color-brand-500, --color-base-white).
➡️ Questo approccio garantisce coerenza tra design e sviluppo, rispecchiando le pratiche di utilizzo delle variabili su Figma.
✅ Perché usare i token?
- I token sono contestualizzati per finalità d’uso (testo, sfondo, bordi, ecc.).
- Consentono un passaggio automatico tra modalità chiara e scura.
- Offrono una gestione centralizzata per uno stile consistente e scalabile.
I token sono organizzati in categorie per semplificare l’utilizzo e garantire la leggibilità:
Gestiscono i colori di sfondo degli elementi.
--background-color-primary--background-color-secondary--background-color-brand-primary
💻 Esempio:
<div class="bg-primary p-md">Sfondo primario</div>Gestiscono i colori del testo.
--text-color-primary--text-color-secondary--text-color-brand-primary
💻 Esempio:
<p class="text-primary">Testo con colore primario</p>Gestiscono i colori dei bordi.
--border-color-primary--border-color-secondary--border-color-brand
💻 Esempio:
<div class="border border-primary p-sm">Box con bordo primario</div>--color-error-primary--color-warning-primary--color-success-primary
💻 Esempio:
<span class="text-error-primary">Messaggio di errore</span>I token sono configurati per essere in modalità chiara (light mode) di default. Per attivare la modalità scura, aggiungi l’attributo data-theme="dark" al tag <body>.
💻 Esempio pratico:
<body>
<div class="bg-primary text-primary">Light mode attivo</div>
</body>
<body data-theme="dark">
<div class="bg-primary text-primary">Dark mode attivo</div>
</body>✅ Vantaggi:
- Non è necessario cambiare le classi CSS per la dark mode.
- La gestione dei temi è centralizzata e reattiva.
Una volta completata la configurazione:
npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch➡️ Monitora le modifiche al file input.css e aggiorna automaticamente output.css.
✅ Consiglio: Mantieni questo comando attivo durante lo sviluppo per vedere le modifiche in tempo reale.
- 📂 Organizza le variabili CSS per categoria (colori, spaziature, tipografia) per una migliore leggibilità.
- 📝 Utilizza sempre i token per mantenere la coerenza con il design system su Figma.
- 🌗 Gestisci la dark mode tramite
data-theme="dark"sul<body>, senza modificare le classi. - 🧩 Estendi i token solo se strettamente necessario per evitare ridondanze.
- 🚫 Evita l’uso diretto di variabili primitive per prevenire incoerenze tra design e sviluppo.
| Errore | Causa | Soluzione |
|---|---|---|
output.css non generato |
Comando npx non eseguito |
Avvia npx @tailwindcss/cli --watch |
| Classi non funzionanti | Uso di variabili primitive anziché token | Usa --text-color-primary anziché --color-brand-500 |
| Dark mode non attiva | Attributo data-theme="dark" mancante |
Aggiungi data-theme="dark" al <body> |
| Gradienti non visibili | Classe CSS errata | Usa bg-linear-gradient-01 correttamente |
✅ Se hai seguito correttamente la guida, sei pronto per lavorare con Tailwind CSS v4 e un design system solido e conforme agli standard di Figma! 🚀