Skip to content

Coming from Tailwind CSS

Shavin runs on Tailwind; it does not replace it. You keep writing Tailwind classes for layout, spacing and type. Shavin adds colour, radius and shadow utilities named by role, React components that use them, and checks that keep code on them. This page says what changes in an existing Tailwind app, and what is still your job.

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 detects Tailwind 3 or 4. On 3 it adds the Shavin preset and the package path to tailwind.config; on 4 it adds the token, base and theme imports after @import "tailwindcss", plus the @source line. It removes nothing.
  • Utilities named by role: bg-surface, text-fg, text-fg-subtle, border-hairline, bg-brand, text-brand-contrast. They switch for dark mode on their own, so you stop writing a dark: twin for every colour class.
  • One brand colour themes everything. ThemeProvider also sets the grays, radius, scaling and fonts. See Theme system.
  • Components for the parts you would otherwise build by hand: dialogs, menus, selects, tabs, tables, forms. The interactive ones get keyboard and screen-reader behaviour from Radix.
  • Checks. npx shavin-lint-tokens flags raw hex, rgb() values, palette classes and fixed radius steps, in the terminal or CI. The MCP server gives an AI agent the same checks plus real component lookups, and the dev inspector shows problems on the running page.

What you still do yourself

  • Replace palette classes with tokens. The lint finds them, but only you can say which role a colour plays. --fix rewrites black and white hex values and fixed radius steps; it does not rewrite palette classes. Check its radius changes: it does not know a button from a card.
  • Replace hand-built pieces with components where it is worth it. Nothing does this automatically. An agent with the MCP server can do much of it, and you review the result.
  • Keep writing layout, spacing and type. Your Tailwind classes for those stay as they are, and new markup still needs them.
  • Move to React 19. The components need it. If you are not using React, only the tokens are useful to you: they are CSS variables any stack can read.

What changes when you add Shavin

These apply to the whole app, including screens you haven't touched. Look over a few existing pages after init.

WhatChange
Page defaultsThe body gets Shavin's background, text colour, body font and a 14px base size. A focus outline, text selection colour and scrollbar style are set too. On Tailwind 4 these sit in the base layer, so any utility you write wins.
font-sansPoints at Shavin's body font (Inter by default, or the bodyFont you set), so text that used Tailwind's default sans stack changes.
dark: variantBecomes class-based: it follows the .dark class ThemeProvider sets, not the operating system media query. With the default system setting the result usually matches, but a reader can now pick light or dark.
Radius on Tailwind 4Tailwind's rounded-sm, rounded-lg and rounded-xl read the same variables Shavin sets. Shavin's defaults equal Tailwind's, but the radius prop on ThemeProvider changes --radius-lg and --radius-xl, so rounded-lg and rounded-xl in your existing code change with it.
ease-out, ease-in-outUse Shavin's easing curves instead of Tailwind's.
Palette classesStill compile. The Shavin preset extends Tailwind's theme rather than replacing it. The lint flags them, because a fixed colour does not follow the theme or dark mode.

Palette classes to tokens

Starting points. The right token depends on what the element does, not on the shade it had:

BeforeShavinRole
bg-white, bg-gray-50bg-canvasPage background
bg-white on a cardbg-surfaceCards and panels
text-gray-900text-fgPrimary text and headings
text-gray-500text-fg-subtleDescriptions and secondary text
border-gray-200border-hairlineBorders and dividers
bg-blue-600 text-whitebg-brand text-brand-contrastPrimary actions

Controls use rounded-[var(--radius-lg)] and containers rounded-[var(--radius-panel)]. More examples, including a before-and-after card, are in Moving an existing app.

What to expect

  • What stays: Tailwind itself, your config, your build, and every class you already wrote. Old and new code run side by side.
  • What can break: the page-wide changes in the table above. The most visible are the body font and base text size, and dark: classes in an app that relied on the system setting alone.
  • Browsers: Shavin uses container queries, :has() and dynamic viewport units, which raises the minimum versions. See Browser support.
  • When plain Tailwind is enough: a one-page site, a short-lived prototype, or a project whose Tailwind config already is a design system the team follows.
  • How long it takes: setup is one command. Token swaps go screen by screen and give dark mode and theming to each screen as you go. How long the whole app takes depends on how many raw colours it has; run the lint on a folder to see the count before you plan.

Steps

  1. Run npx @shavin/cli init, then npx @shavin/cli check. See Installation for every file init touches, and Tailwind setup for the lines it adds.
  2. Open a few existing pages and check the page-wide changes above.
  3. Set your brand colour on ThemeProvider. For secondary brand colours, see Brand colour tokens.
  4. See how much there is to move with the lint (command below).
  5. Swap palette classes for tokens, one screen at a time.
  6. Add the lint to CI so new raw colours don't come back.
npx shavin-lint-tokens "src/**/*.tsx"

For what Shavin adds on top of Tailwind, and when plain Tailwind is enough, see Shavin and Tailwind CSS.

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