Panoramica

Snapp supporta il theming a runtime tramite un singolo file CSS che sovrascrive i design token dell’applicazione.

Non esiste alcun passaggio di rebuild, nessuna ricompilazione di Tailwind e nessun override a livello di componente.

Lo styling viene applicato ridefinendo CSS custom properties già utilizzate da Tailwind e dal layer UI.

Come viene caricato lo stile personalizzato

Snapp inietta un foglio di stile alla fine del documento HTML.

<!-- Custom Style Override -->
<link rel="stylesheet" href="/custom.css" />

Poiché questo link è inserito dopo l’intero markup dell’applicazione, tutte le definizioni presenti in custom.css hanno precedenza tramite le normali regole della cascade CSS.

Da dove proviene custom.css

Il file /custom.css viene servito da Snapp a runtime.

Internamente viene letto da:

config/custom.css

Questo file viene tipicamente montato tramite Docker.

Esempio di mapping dei volumi:

volumes:
  - ./config/custom.css:/app/config/custom.css

Snapp lo espone tramite un endpoint dedicato con caching a lungo termine:

• Content-Type: text/css
• Cache-Control: max-age=31536000

Non è necessario riavviare l’applicazione per modificare lo stile; conta solo il contenuto del file.

Cosa inserire in custom.css

È previsto che tu ridefinisca solo variabili CSS, non che scriva CSS a livello di componenti.

L’approccio consigliato è:

• Generare un tema usando un generatore compatibile con Shadcn (ad esempio: https://www.shadcn.io/theme-generator)
• Copiare solo i blocchi :root { ... } e .dark { ... }
• Incollarli in config/custom.css

Struttura di esempio:

:root {
	--background: oklch(...);
	--foreground: oklch(...);
	--primary: oklch(...);
	--radius: 0.25rem;
	--font-sans: 'Lato', sans-serif;
	/* … */
}

.dark {
	--background: oklch(...);
	--foreground: oklch(...);
	/* … */
}

Queste variabili sostituiscono direttamente i default forniti con Snapp.

Integrazione con Tailwind

Snapp utilizza token Tailwind mappati su variabili CSS.

La mappatura è definita una sola volta e riutilizzata ovunque:

@theme inline {
	--color-background: var(--background);
	--color-foreground: var(--foreground);
	--color-primary: var(--primary);
	--radius-lg: var(--radius);
	/* … */
}

Di conseguenza:

• Tutte le utility Tailwind (bg-background, text-foreground, ecc.) si aggiornano automaticamente
• Tutti i componenti UI si aggiornano automaticamente
• Grafici, sidebar, modali e form restano coerenti

Non sono richieste modifiche alla configurazione di Tailwind.

Font e tipografia

Puoi sovrascrivere i font nello stesso modo, usando variabili CSS:

:root {
	--font-sans: 'Lato', sans-serif;
	--font-serif: 'Merriweather', serif;
	--font-mono: 'Roboto Mono', monospace;
}

Se importi font da Google Fonts o altri provider, fallo all’inizio di custom.css.

Dark mode

La dark mode è gestita tramite il selettore .dark.

Snapp applica la classe dark all’elemento root. Il tuo unico compito è definire le variabili.

Non c’è JavaScript da scrivere né logica di switch del tema da implementare.

Cosa non consente questo sistema

• Nessun override CSS per singolo componente
• Nessuna ricompilazione di Tailwind
• Nessuna iniezione di classi a runtime
• Nessuna mutazione di stili inline

Lo styling è dichiarativo, globale e basato su token per progettazione.

Se un valore non è esposto come variabile CSS, non è pensato per essere tematizzato.