Skip to content

Coming from Radix Themes

Shavin and Radix Themes are both styled component libraries built on Radix Primitives, so keyboard and focus behaviour will feel familiar. The theme settings map almost one to one. The component APIs do not, and Shavin needs Tailwind CSS, which Radix Themes does not. This page says what moves over, what you rewrite, and what is missing.

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

  • Themes the app from one ThemeProvider with props close to Radix Themes' <Theme> (table below), including dark mode and a saved light, dark or system choice.
  • Keeps Radix's keyboard and screen-reader behaviour. @shavin/ui depends on the Radix Primitives packages directly (@radix-ui/react-dialog, -select, -dropdown-menu, -tabs, -tooltip and others), not on @radix-ui/themes. See Accessibility.
  • Accepts any hex brand colour and adjusts text on it for contrast. Radix Themes only takes its named scales.
  • Gives you semantic Tailwind utilities (bg-surface, text-fg, border-hairline, bg-brand) for your own markup, and checks that flag raw colours: npx shavin-lint-tokens and the MCP server for AI agents.

What you still do yourself

  • Add Tailwind CSS 3.4 or 4. Shavin's components are styled with Tailwind classes and its tokens are exposed as Tailwind utilities. If your app has no Tailwind today, this is the largest change. See Tailwind setup.
  • Upgrade to React 19. It is a peer dependency.
  • Rewrite each component usage. Many names match, but props differ: sizes are words, overlays take props instead of dot parts, and layout spacing moves from props to className. There is no codemod.
  • Recheck your colours. Shavin's named brand colours share Radix's names, but the generated shades are Shavin's own. If you used Radix's --accent-* or --gray-* variables in your CSS, replace them with Shavin tokens by role, not by step number.
  • Remove Radix Themes and its stylesheet once the last screen has moved.

Theme props

Radix Themes' prop is accentColor; Shavin calls the same idea the brand colour, brandColor.

Radix ThemesShavinNotes
accentColorbrandColorTakes one of 24 names (Tomato, Ruby, Indigo, Grass and others, matched without case) or any #rrggbb value. Orange, Yellow and Gray are not among the names: pass a hex value instead. An unknown name falls back to black.
grayColorgrayColorZinc (the default), Slate, Gray, Neutral or Stone. Mauve, Sage, Olive, Sand and auto have no equivalent.
radiusradiusSame values: none, small, medium, large, full.
scalingscalingSame values: 90% to 110%. Numbers (95) work too.
panelBackgroundpanelBackgroundSame values: solid or translucent.
appearancedefaultThemelight, dark or system (the default). It is the starting value: the reader's choice is saved in localStorage and wins on later visits.
hasBackground

None

Shavin's base styles always paint the page background on body.
Font CSS variablesdisplayFont, bodyFont, subheadingFontFont names as props. See Custom fonts.

ThemeProvider renders no wrapper element: it sets the theme on the whole page. To theme one part of the page differently, the way you would nest a second <Theme>, use ScopedThemeProvider. It takes the same props plus appearance (light, dark or inherit). See Theme system and Custom fonts.

Components

Look each one up in the component docs before you port it. A matching name is a starting point, not a promise of the same props.

Radix ThemesShavinWhat differs
Box, Flex, Grid, Container, Section

Same names

No margin or padding props and no responsive object props. Use className.
Text, Heading, Code, Kbd, Link, Blockquote, Em, Strong, Quote

Same names

Sizes are words (sm, md, lg); Text also takes 1 to 4.
Button, IconButton, Badge, Callout, Card, Inset

Same names

Button has solid, soft, outline and ghost, with a brand or danger tone. No classic or surface variant.
Dialog, AlertDialog

Same names

Props, not dot parts: trigger, title, description, footer.
SelectSelectTakes an options array instead of Select.Item children.
DropdownMenuMenu or DropdownMenu for actions, Dropdown for picking a value.
Tabs, TabNavTabsWith as="navigation" and items that have an href, Tabs renders page links, which covers TabNav.
RadioCards

None

CheckboxCards and RadioGroup exist; there is no radio card component yet.
ThemePanelDev inspectorShown in development by ThemeProvider. It does not render in production.

One screen, before and after

Radix Themes:

import { Theme, Dialog, Button, Flex } from "@radix-ui/themes";

<Theme accentColor="indigo" grayColor="slate" radius="large" scaling="95%">
  <Dialog.Root>
    <Dialog.Trigger><Button>Add account</Button></Dialog.Trigger>
    <Dialog.Content>
      <Dialog.Title>Add account</Dialog.Title>
      <Dialog.Description>Connect a bank account to WiseOwl.</Dialog.Description>
      <Flex gap="3" justify="end">
        <Dialog.Close><Button variant="soft" color="gray">Cancel</Button></Dialog.Close>
        <Button>Connect</Button>
      </Flex>
    </Dialog.Content>
  </Dialog.Root>
</Theme>

Shavin:

import { ThemeProvider, Dialog, DialogClose, Button } from "@shavin/ui";

<ThemeProvider brandColor="Indigo" grayColor="Slate" radius="large" scaling={95}>
  <Dialog
    trigger={<Button>Add account</Button>}
    title="Add account"
    description="Connect a bank account to WiseOwl."
    footer={
      <>
        <DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose>
        <Button>Connect</Button>
      </>
    }
  />
</ThemeProvider>

Radix Themes lets you recolour any component with color and highContrast. Shavin has no per-component colour prop: buttons take a tone of brand or danger, badges and callouts take neutral, brand, success, warning or danger.

What to expect

  • What stays: Radix's behaviour for dialogs, menus, selects, tabs and tooltips; the radius, scaling and panel settings; your own app logic and data code.
  • What changes: imports, component props, how layout spacing is written, and the look. Shavin's components are not pixel copies of Radix Themes, so screens will look different even at the same settings.
  • What can break: any CSS that reads Radix Themes variables or .rt-* class names, responsive props written as objects, and components with no Shavin equivalent (listed above).
  • Running both at once: we have not tested Radix Themes and Shavin on the same page. If you move screen by screen, check each moved screen in light and dark mode before you ship it.
  • How long it takes: setup is one command. The rest grows with the number of screens and how many Radix Themes props each one uses; nothing converts them for you. An AI agent connected to the MCP server can look up each Shavin component's real props while it rewrites, which cuts the guesswork but not the review.

Steps

  1. Add Tailwind 3.4 or 4 if you don't have it, and upgrade to React 19.
  2. Run npx @shavin/cli init, then npx @shavin/cli check. See Installation for every file init touches.
  3. Copy your <Theme> settings onto ThemeProvider using the table above.
  4. Move one screen at a time. Start with a simple one to learn the API differences.
  5. Run npx shavin-lint-tokens on the files you changed, and remove @radix-ui/themes when no file imports it.

For moving hand-written Tailwind markup to tokens and components, see Moving an existing app. For secondary brand colours, see Brand colour tokens.

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