Coming from shadcn/ui
You don't have to remove shadcn/ui to try Shavin. On Tailwind 4 the two run in one project, and each keeps its own colours and focus styles. The main difference is ownership: shadcn/ui copies component source into your project, while Shavin's components come from a package that you style but do not edit.
Beta
What Shavin does for you
npx @shavin/cli initrecognises shadcn/ui fromcomponents.json. On Tailwind 4 it adds Shavin's imports after@import "tailwindcss"and leaves shadcn's lines untouched.- If your layout already has a theme provider (next-themes, or shadcn's own), init does not add Shavin's. Shavin's components follow the
.darkclass your provider sets. - Shavin's brand colour is
--brand. It redefines none of shadcn's variables, and a unit test in the Shavin repo checks that. - Shavin blocks also install through the shadcn CLI, so you can keep the tool you know (see below).
- Checks for your own markup:
npx shavin-lint-tokensflags raw hex and palette classes, and the MCP server lets an AI agent look up real component props and check its code.
What you still do yourself
- Keep two colour systems in step. Setting Shavin's brand colour does not recolour shadcn components, and changing
--primarydoes not recolour Shavin's. While both are in use, you match them by hand. - Port components one by one. There is no converter. Shavin's APIs differ from shadcn's: for example, Shavin's
Selecttakes anoptionsarray andDialogtakestrigger,titleandfooterprops instead of composed parts. - Carry over your edits. Any change you made inside a shadcn component file has to become a prop, a
classNameor a theme setting in Shavin. Some edits won't have a home: you cannot change a Shavin primitive's markup. - Upgrade to React 19 if you haven't. Shavin needs it.
Who owns what
With both on Tailwind 4 and Shavin's imports after Tailwind's:
| Concern | shadcn/ui | Shavin |
|---|---|---|
| Brand or primary colour | --primary, --accent | --brand (bg-brand, text-brand-contrast) |
| Surfaces, text, borders | --background, --foreground, --border | bg-surface, text-fg, text-fg-subtle, border-hairline |
| Focus ring | --ring, a 3px ring on its components | A 2px outline in the theme's focus colour |
| Radius | --radius-sm, --radius-lg, --radius-xl | The same three names, plus --radius-panel |
| Dark mode | The .dark class | The same .dark class |
The three radius names are the only overlap. shadcn's radius utilities keep shadcn's values, and Shavin's components keep Shavin's. If Shavin's lines sit before @import "tailwindcss", Tailwind's default radius and easing values replace Shavin's, so keep them after.
What to expect
- What stays: your shadcn components and their source, their colours, their focus rings, your
components.jsonand your theme provider. - What changes: Shavin's element defaults (body type, focus outline, selection, scrollbars) load in Tailwind's base layer. shadcn's base styles still set the page background and text colour. Where shadcn sets nothing, such as the body font and base text size, Shavin's defaults apply to the whole page, so check pages you haven't touched.
- Tailwind 3: the side-by-side setup is documented for Tailwind 4. On Tailwind 3 Shavin's element defaults are not layered and can override shadcn's base styles; init warns you when it sees this. Review your global stylesheet before shipping, or move to Tailwind 4 first.
- Ownership: blocks are copied into your project and are yours to edit, like shadcn components. Primitives are not: you update them by updating the package.
- Ecosystem: shadcn/ui has far more users, registries and answered questions. Shavin is newer and its community is small.
- How long it takes: setup is one command and does not touch your shadcn files. After that you can stop at any point: new screens in Shavin and old ones in shadcn is a supported state, not a broken one.
Install Shavin blocks with the shadcn CLI
Every open Shavin block is also a shadcn registry item. Install one by URL:
npx shadcn@latest add https://shavin.cc/r/shadcn/hero-centered-media.jsonOr register the namespace once in components.json:
{ "registries": { "@shavin": "https://shavin.cc/r/shadcn/{name}.json" } }Then npx shadcn@latest add @shavin/hero-centered-media or npx shadcn@latest search @shavin. The block lands in components/blocks/ and shadcn installs @shavin/ui with it. The shadcn CLI does not set up Shavin's styles or theme, so run npx @shavin/cli init once as well.
Steps
- Move to Tailwind 4 if you are on 3, and React 19 if you are on 18.
- Run
npx @shavin/cli init, thennpx @shavin/cli check. Compare your global CSS with the shadcn example in Tailwind setup. - Set a brand colour close to your shadcn
--primary. See Theme system; for extra brand colours, see Brand colour tokens. - Build new screens with Shavin. Move old ones when you are already changing them.
- Run
npx shavin-lint-tokenson the files you move.
For how the two differ, and when shadcn/ui alone is the better fit, see Shavin and shadcn/ui. For the full install, see Installation.