Installation
One command sets up Shavin in an existing React project: components, Tailwind, the theme, and your AI agent.
Beta
Requirements
- React 19
- Tailwind CSS 3.4 or 4
- Next.js, Vite or Remix. Other React setups work too; you may need to add the provider by hand.
1. Run init
Run this in your project root. It detects your framework and Tailwind version and only changes what is missing.
npx @shavin/cli initinit in a new Next.js 15 and Tailwind 4 app. It reports each change, and asks before installing the agent packages when they are missing.
Add --oklch to use OKLCH colour values instead of RGB. It works with Tailwind 3 and 4.
What init changes
Components and styles
- Installs
@shavin/ui. - Tailwind 3: adds the Shavin preset and the package path to
tailwind.config. Tailwind 4: importstokens.css,base.css(in the base layer) andtheme-v4.cssafter Tailwind, and adds the@sourcelines. - Imports the Shavin stylesheet in your global CSS (
app/globals.css,src/app/globals.css,src/index.cssand similar), right after Tailwind's own import. If it can't find one, it prints the lines to add. - Wraps your root layout (
app/layout,pages/_app, the Vite entrysrc/main,src/Apporapp/root) inThemeProvider. If it cannot find one, it prints the two lines to add. If the layout already has another theme provider (next-themes, shadcn/ui), it leaves the layout alone: Shavin follows the.darkclass that provider sets.
Brand tokens
- Creates
brand-tokens.cssand addsbrand:genandbrand:checkscripts. When@shavin/cliis installed in the project,brand:genalso runs beforedevandbuild. See Brand colour tokens.
AI agent setup
- Asks before installing
@shavin/mcpand@shavin/skillsas dev dependencies, then copies the skills into.agents/skills/. - Writes
SHAVIN.md(your project's design brief),AGENTS.mdandCLAUDE.md. - Registers the MCP server for Claude Code (
.mcp.json), Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json). - If
@shavin/mcpis installed, wires the live audit bridge to start with your Next.js or Vite dev server, or prints the two lines to add when it cannot edit the config itself.
In development, ThemeProvider also shows the Shavin inspector, a small panel for checking tokens and contrast on the running page. It does not render in production.
2. Check the setup
npx @shavin/cli checkConfirms the package, the Tailwind setup and ThemeProvider. If something is missing, see Debug setup.
3. Render a component
import { Badge, Button, Card, Flex, Heading, Text } from "@shavin/ui";
export function WelcomeCard() {
return (
<Card padding="lg">
<Flex direction="column" gap="3">
<Flex align="center" justify="between">
<Heading as="h2" size="md">Welcome</Heading>
<Badge tone="brand">New</Badge>
</Flex>
<Text color="subtle">Your workspace is ready.</Text>
<Button>Create a project</Button>
</Flex>
</Card>
);
}Components work in Server and Client Components. Helpers such as cn must be imported from @shavin/ui/server in files without "use client".
4. Add a block
Blocks are whole sections and screens. add copies the source into components/blocks/ (src/components/blocks/ if you have a src folder), where it is yours to edit.
npx @shavin/cli add auth-signinIf @shavin/ui is not installed yet, add offers to run init first. After copying the block it installs any npm package the block needs that your project lacks, or has at an older version, with your package manager. It asks before each step; pass --yes to skip the questions.
Browse them in Blocks, or run npx @shavin/cli list.