Che cos'è shadcn/ui (e cosa non è)

shadcn/ui è una raccolta di componenti React che una CLI copia nel tuo repository, non una libreria da installare come dipendenza. Ogni componente arriva come file leggibile, costruito su Radix UI e Tailwind CSS.

Cosa scrive davvero nel repository

Il comando di init crea components.json, aggiunge le dipendenze Radix e Tailwind e copia i token in app/globals.css. Il comando add scrive un file per componente in components/ui. Dopo l'installazione il codice è tuo: rinomini le prop, cambi una variante, elimini un componente.

Cosa non è

Non è un pacchetto npm: non c'è una versione da aggiornare in package.json. Non è un design system: non contiene regole di prodotto, contenuti o governance. Non è un kit Figma. È uno strato di distribuzione del codice, e la licenza MIT di shadcn/ui è documentata su ui.shadcn.com.

Come si installa

npx shadcn@latest init
npx shadcn@latest add button

L'init chiede stile, colore base e percorsi dei file. Il comando add accetta un nome dal registry pubblico, un URL o un namespace: npx shadcn@latest add @eneui/hero. Il formato del record è descritto in che cos'è un registry.

Un esempio concreto: una variante nuova

import { cva } from "class-variance-authority";

export const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md text-sm font-medium",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground",
        outline: "border border-input bg-background",
        quiet: "bg-transparent text-muted-foreground hover:bg-accent",
      },
    },
    defaultVariants: { variant: "default" },
  },
);

La variante quiet è una riga in un file che possiedi: nessuna patch, nessun fork, nessun !important. Il prezzo è che il file non riceve più aggiornamenti automatici, quindi la variante va confrontata a mano quando il componente a monte cambia. In cambio, il markup usa token come bg-accent e text-muted-foreground, e il tema scuro continua a funzionare senza eccezioni.

Dove finisce il confine con Radix

shadcn/ui non implementa il comportamento: lo delega a Radix UI, pacchetto MIT che gestisce focus, tastiera e stato. Il confronto tra le primitive è in Radix, Base UI e React Aria.

Il conteggio del 1 novembre 2026 su data/blocks.json, snapshot del 31 ottobre 2026, trova 381 blocchi su 1.556 con «shadcn» nell'identificativo della fonte, distribuiti su 5 fonti; la sola shadcn-ui-ui ne pubblica 97. La cifra misura la diffusione del modello di distribuzione, non la qualità del codice copiato. I cinque identificativi non sono tutti fork diretti: alcuni pubblicano solo blocchi sopra shadcn/ui e non toccano i file dei componenti.

Un record vivo

Nel catalogo EneUI il record sidebar di shadcn/ui mostra file, dipendenze e licenza a monte; la stessa libreria compare con chart. Per esplorare per categoria parti da 111.985 componenti.

La limitazione

Nessun aggiornamento automatico. Quando shadcn/ui cambia un componente, il tuo file resta com'era: rilanci il comando, leggi il diff e riconcili a mano. Con più repository la deriva cresce in silenzio.

La regola di decisione

Installa un componente quando prevedi di cambiare almeno una prop o un token entro il primo mese. Se non lo modificherai, un pacchetto npm con API stabile costa meno manutenzione. Se devi riscrivere più di un terzo dello stile, parti da Radix e scrivi il tuo CSS: a quel punto stai già pagando il costo di un fork, e ti conviene possedere il codice dall'inizio.

L'errore da evitare

Aggiungere classi arbitrarie dentro components/ui, per esempio bg-[#111], rompe il cambio di palette e il tema scuro: il valore non passa da un token. L'override va nel punto d'uso, con className, oppure diventa una variante nel file. Se lo ripeti tre volte, non è un'eccezione: è una variante che manca.

Dove continuare

L'installazione passo per passo è in come installare shadcn/ui; il modello copy-paste contro il pacchetto headless è in copy-paste o headless. Per le sezioni complete parti da 1.556 blocchi.