Creare un tema shadcn da qualsiasi sito web

Un tema shadcn (in inglese shadcn theme) è un insieme di variabili CSS, di solito in globals.css, che tutti i componenti di shadcn/ui leggono: --background, --foreground, --primary, --primary-foreground, --border, --ring, --radius e poche altre, definite una volta per il tema chiaro e una per quello scuro. Per creare un tema shadcn da un sito qualsiasi raccogli i design token di quel sito (colori per ruolo, raggi, tipografia), assegni ognuno alla variabile corrispondente e aggiungi la variante scura. Puoi farlo a mano con i DevTools oppure estrarre i token con uno strumento e ritoccare il risultato.

In questa guida vediamo come funziona il theming di shadcn, come leggere i token di un sito a mano, come accelerare il lavoro con Pickode e cosa controllare prima di andare online.

Cos’è un tema shadcn

shadcn/ui non è una libreria che installi come dipendenza: la CLI copia i file sorgente dei componenti nel tuo progetto. Quei componenti non hanno colori scritti a mano. Usano classi Tailwind come bg-primary, text-muted-foreground o border-input, e queste classi puntano a variabili CSS. Cambi le variabili e pulsanti, card, dialog e campi si adeguano.

Nei progetti attuali con Tailwind CSS v4 le variabili stanno in globals.css: i valori in :root e in .dark, poi un blocco @theme inline che le espone a Tailwind come colori e raggi. Ecco un esempio accorciato, con valori indicativi per un brand blu:

@import "tailwindcss";

@custom-variant dark (&:is(.dark *));

:root {
  --radius: 0.5rem;
  --background: oklch(0.99 0 0);
  --foreground: oklch(0.21 0.02 260);
  --primary: oklch(0.55 0.2 260);
  --primary-foreground: oklch(0.99 0 0);
  --muted: oklch(0.96 0.01 260);
  --muted-foreground: oklch(0.5 0.02 260);
  --border: oklch(0.91 0.01 260);
  --input: oklch(0.91 0.01 260);
  --ring: oklch(0.55 0.2 260);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
}

Un file vero ha più coppie (card, popover, secondary, accent, destructive, i colori dei grafici e della sidebar). I progetti più vecchi su Tailwind v3 salvano i colori come canali HSL e li richiamano da tailwind.config.js; il principio è lo stesso.

Quando si cercano i “colori shadcn” spesso si intendono i colori base che la CLI propone all’installazione (neutral, gray, zinc, stone, slate). Sono solo palette di partenza: un tema preso da un sito vero li sostituisce con i valori del brand.

Design token in breve: colori, raggi, tipografia

I design token sono le decisioni con un nome dietro uno stile visivo: “il primario è questo blu”, “le card hanno un raggio di 8 px”, “il testo è Inter a 16 px”. Un sito raramente li pubblica, ma li applica sempre, e un tema shadcn non è altro che design token scritti con il vocabolario di shadcn.

Per un tema ti servono tre gruppi:

• Colori per ruolo: sfondo, testo, primario, secondario, accento, errore, bordo, e il colore del testo che sta sopra ogni colore pieno.
• Forme: il raggio degli angoli di pulsanti, campi e card. shadcn ricava i raggi più piccoli e più grandi da un unico --radius.
• Tipografia: famiglie di font e scala dei testi. shadcn non mette i font nelle variabili dei colori, quindi li imposti a parte, per esempio come --font-sans nel tema Tailwind.

Spaziature e ombre contano per un risultato fedele, ma i componenti shadcn usano la scala di spaziature di Tailwind, quindi nel tema di solito sono facoltative.

Il metodo manuale: leggere i token con i DevTools

Puoi raccogliere tutto con gli strumenti per sviluppatori del browser:

Funziona, ma è lento ed è facile sbagliare. La scheda Computed mostra valori risolti, quindi vedi il colore ma non il suo ruolo; i colori di hover e focus compaiono solo se forzi quegli stati; e un sito può usare cinque grigi quasi uguali dove a te serve un solo --border. Su un sito grande trovare tutti i ruoli può richiedere un’ora.

Estrarre i token di un sito con Pickode

La finestra Design token di Pickode fa la raccolta al posto tuo. Pickode è un’estensione del browser: apri una pagina qualsiasi, apri Design token dal pannello e trovi i colori per ruolo (primario, secondario, accento, successo, errore, sfondo, testo, bordo), i colori del brand, i gradienti, la scala delle spaziature con rilevamento della griglia 4/8 px, la scala dei testi, i raggi, le ombre e i font.

Da lì esporti i token nel formato del tuo progetto: variabili CSS, @theme per Tailwind v4, tailwind.config.js, globals.css per shadcn, theme.json di WordPress o JSON. Per un progetto shadcn esporta il globals.css, mettilo nel progetto e rivedilo con la tabella qui sotto.

Se lavori con un assistente AI, Copia per AI ti dà i token (o un intero componente con token, breakpoint e stati del sito) come testo Markdown per Claude, ChatGPT, Cursor o v0. Contiene solo dati trovati nella pagina, quindi puoi chiedere all’assistente di applicarli alle variabili shadcn senza che si inventi i colori.

Vedere, copiare e scaricare i token è gratis. Trovi i dettagli nei prezzi e nella documentazione dei design token.

Mappare i token sulle variabili shadcn

Che tu abbia raccolto i token a mano o con uno strumento, il cuore del lavoro è questa tabella:

Ruolo nel sito	Variabile shadcn	Note
Sfondo della pagina	--background	Buon valore di partenza anche per --card e --popover
Testo	--foreground	Anche --card-foreground e --popover-foreground
Primario (pulsanti principali, link)	--primary	Nella maggior parte dei temi è il colore del brand
Testo sui pulsanti primari	--primary-foreground	Di solito bianco o un tono molto scuro
Pulsanti secondari	--secondary e --secondary-foreground	Spesso una tinta chiara del primario o un neutro
Sfondi tenui, didascalie	--muted e --muted-foreground	Il testo attenuato è dove il contrasto cede più spesso
Accento	--accent e --accent-foreground	Nei componenti di default serve soprattutto per lo sfondo in hover di menu ed elenchi, non per grandi aree di brand
Errore	--destructive	Usato dai pulsanti distruttivi e dagli errori dei form
Bordi e campi	--border e --input	Scegli un solo grigio neutro, anche se il sito ne usa diversi
Contorno del focus	--ring	Spesso il primario, o una sua versione più chiara
Raggio degli angoli	--radius	Un solo valore; i raggi più piccoli e più grandi derivano da questo

Due ruoli richiedono una scelta. Successo non ha una variabile nel set di default di shadcn: se la tua app ne ha bisogno, aggiungi --success e --success-foreground in :root e in .dark, poi mappa --color-success in @theme inline. Nemmeno i gradienti corrispondono a una variabile: tienili come custom property separate e usali dove li usa il sito originale.

Tema chiaro e scuro con oklch e @theme di Tailwind v4

La maggior parte dei siti ha solo il tema chiaro, quindi i valori scuri di solito li progetti tu. Un approccio pratico con oklch, che descrive un colore come luminosità, croma e tinta:

• Mantieni la tinta di ogni colore del brand e regola luminosità e croma per lo sfondo scuro.
• Inverti i neutri: --background diventa molto scuro, --foreground molto chiaro e --border un grigio a bassa luminosità.
• Schiarisci un po’ il primario se sullo scuro risulta pesante, e verifica che --primary-foreground resti leggibile.

.dark {
  --background: oklch(0.18 0.02 260);
  --foreground: oklch(0.97 0 0);
  --primary: oklch(0.68 0.17 260);
  --primary-foreground: oklch(0.18 0.02 260);
  --muted: oklch(0.26 0.02 260);
  --muted-foreground: oklch(0.72 0.02 260);
  --border: oklch(0.3 0.02 260);
  --input: oklch(0.3 0.02 260);
  --ring: oklch(0.68 0.17 260);
}

Dato che il blocco @theme inline richiama solo variabili, non va ripetuto per il tema scuro: la classe .dark cambia i valori e tutte le classi si adeguano.

Controllare il contrasto prima di pubblicare

Un tema preso da un sito può comunque fallire sull’accessibilità nella tua app: magari usi il colore del brand per testi piccoli che il sito originale metteva solo su pulsanti grandi, oppure metti testo attenuato su uno sfondo attenuato. Il livello AA delle WCAG 2.2 chiede un rapporto di contrasto di almeno 4,5:1 per il testo normale e 3:1 per il testo grande, e 3:1 per i contorni visivi dei componenti dell’interfaccia, indicatori di focus compresi.

Controlla almeno queste coppie, in chiaro e in scuro: --foreground su --background, --primary-foreground su --primary, --muted-foreground su --background e su --muted, e --ring rispetto allo sfondo.

Quando l’app con il nuovo tema gira nel browser, la mappa del contrasto di Pickode segna ogni testo che non passa rispetto al suo sfondo effettivo, con le soglie AA e AAA, e suggerisce il colore più vicino che passa. È gratis, e l’audit di accessibilità completo usa axe-core sulle WCAG 2.2 AA.

Limiti e buone pratiche

• L’estrazione dei token legge quello che la pagina usa davvero. Considera l’assegnazione dei ruoli un punto di partenza e verificala a occhio, soprattutto sui siti con tanti grigi simili.
• Pickode non funziona sulle pagine chrome://, sul Chrome Web Store e sui PDF.
• Usalo per ricostruire lo stile dei siti su cui lavori, per migrare il brand di un cliente o per studiare uno stile. Non clonare l’identità di un’altra azienda per il tuo prodotto.

Domande frequenti

Dove si definiscono i colori di un tema shadcn?

Nel foglio di stile globale, di solito globals.css (il percorso è indicato in components.json). I colori sono variabili CSS in :root per il tema chiaro e in .dark per quello scuro; con Tailwind v4 un blocco @theme inline li espone come classi tipo bg-primary.

Posso usare colori esadecimali al posto di oklch?

Sì. Le variabili accettano qualsiasi colore CSS valido. I template recenti di shadcn usano oklch perché rende più prevedibili le varianti chiare e scure della stessa tinta, ma vanno bene anche hex o rgb.

Posso ottenere un tema shadcn da un sito in automatico?

Con Pickode esporti i token di un sito come globals.css per shadcn e lo metti nel progetto. Rivedi la mappatura (soprattutto accento, attenuati e bordi) e progetta tu i valori scuri se il sito non ha un tema scuro.

Che differenza c’è tra design token e tema shadcn?

I design token sono le decisioni del brand in forma neutra: colori per ruolo, raggi, tipografia, spaziature. Un tema shadcn è un modo di scrivere una parte di quei token, con i nomi di variabile che i componenti shadcn si aspettano.

Se vuoi provarlo su un sito su cui lavori, installa Pickode, apri Design token sulla pagina e confronta quello che trova con la tabella qui sopra.