How to add a shadcn block without breaking the theme

Short answer: add the block with npx shadcn@latest add on a branch, after view and --dry-run have shown which files and tokens it touches. The theme breaks when the block ships hard-coded colours or overwrites a primitive you already customised.

Why a block can break the theme

A block is not an isolated component: it is a full section, with layout, spacing and often a palette of its own. When it was built on tokens with different names from yours, the classes exist but read values your CSS never defines.

The licence changes with the source registry: shadcn/ui is MIT, third-party blocks can be commercial. The /blocks page shows source and licence before installation, and that is the first filter to apply.

The safe path, in five steps

1. Create a branch: the install must be undoable with one command.
2. Read the block with view, writing nothing.
3. Try the install with --dry-run and count the files.
4. Install for real, then read git diff before you open the browser.
5. Check the page in light and dark theme, not only in the one you had open.

# guarda i file del blocco prima di scriverli
npx shadcn@latest view ./hero-01.json

# prova l'installazione senza modificare il progetto
npx shadcn@latest add ./hero-01.json --dry-run

When the block comes from a URL or a namespace, only the first argument changes: npx shadcn@latest add @eneui/hero. The rest of the flow stays the same, and so does the risk.

# installa davvero, su un ramo pulito
npx shadcn@latest add ./hero-01.json

# leggi cosa è cambiato prima di aprire il browser
git diff --stat

git diff --stat answers one question: how many files the command touched, and which. If a file in components/ui appears that you did not mean to edit, the block depends on a different primitive from yours and needs isolating.

The check that matters: tokens

{/* segue i token: cambia con il tema */}


{/* colori fissi: resta grigio anche in dark mode */}

The first section follows the theme because it uses roles, not colours. The second carries a hand-written palette: in dark mode it stays light, and no token change can fix it. The fix belongs in the block, not in the theme.

What to read in the diff

• New or renamed tokens in the global CSS.
• Dependencies added to package.json.
• Files in components/ui overwritten.
• Classes with hard-coded colours, which the theme cannot reach.

Blocks that ship their own CSS

Some registries ship the block with a stylesheet and variables your theme does not have. Install it, then map those variables in @theme inline: without the mapping the block's utilities are never generated and the section renders without colour. The syntax of view, add and --dry-run is documented on the shadcn/ui CLI page (MIT licence).

A named limitation

A block is not a versioned package: it gets no updates and has no changelog. Regenerate it with --overwrite and you also overwrite your manual changes, so the source of truth stays your repository, not the registry.

Where to continue

The EneUI catalogue lists 1,556 blocks with previews, for example a chart section and a hero. To see how they are organised read shadcn blocks in the catalogue; for the theme, dark mode without a second design system; for registries, tokens and namespaces. The comparison of ready-made themes is free versus premium.