Skip to content

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

Shavin is in beta. Component APIs and tokens can still change between releases, so move on a branch, one screen at a time, and read the release notes when you update.

What Shavin does for you

  • npx @shavin/cli init recognises shadcn/ui from components.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 .dark class 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-tokens flags 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 --primary does 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 Select takes an options array and Dialog takes trigger, title and footer props instead of composed parts.
  • Carry over your edits. Any change you made inside a shadcn component file has to become a prop, a className or 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:

Concernshadcn/uiShavin
Brand or primary colour--primary, --accent--brand (bg-brand, text-brand-contrast)
Surfaces, text, borders--background, --foreground, --borderbg-surface, text-fg, text-fg-subtle, border-hairline
Focus ring--ring, a 3px ring on its componentsA 2px outline in the theme's focus colour
Radius--radius-sm, --radius-lg, --radius-xlThe same three names, plus --radius-panel
Dark modeThe .dark classThe 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.json and 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.json

Or 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

  1. Move to Tailwind 4 if you are on 3, and React 19 if you are on 18.
  2. Run npx @shavin/cli init, then npx @shavin/cli check. Compare your global CSS with the shadcn example in Tailwind setup.
  3. Set a brand colour close to your shadcn --primary. See Theme system; for extra brand colours, see Brand colour tokens.
  4. Build new screens with Shavin. Move old ones when you are already changing them.
  5. Run npx shavin-lint-tokens on 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.

Configure Theme
Theme
Brand Color
Custom
Gray Family
Appearance
Radius
Scaling
Panel Style
Heading Font
Body Font