Skip to content

Installation

One command sets up Shavin in an existing React project: components, Tailwind, the theme, and your AI agent.

Beta

Shavin is in beta. Component APIs and tokens can still change between releases; check the release notes when you update.

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 init
$ npx @shavin/cli init
✔ @shavin/ui already installed
Tailwind CSS v4 detected (via package.json)
Framework: nextjs (via package.json)
✔ Created brand-tokens.css (brand color tokens — edit INPUT section to add colors)
✔ Created brand-theme-v4.css (auto-generated @theme inline CSS)
✔ Added the brand:gen, brand:check, predev and prebuild scripts to package.json
✔ Added <ThemeProvider> to layout.tsx
✔ Created SHAVIN.md (your project's design brief for agents)
✔ Initialized .shavin/config.json
✔ @shavin/mcp and @shavin/skills already installed
✓ Deployed 62 skill file(s) to .agents/skills/
✓ Deployed 9 AI slash command(s) to .agents/commands/
… 62 file paths omitted
✔ Created AGENTS.md (rules for AI agents in this repo)
✔ Created CLAUDE.md (instructions for Claude Code)
✔ Created .mcp.json (MCP server for Claude Code)
✔ Created .cursor/mcp.json (MCP server for Cursor)
✔ Created .vscode/mcp.json (MCP server for VS Code)
✔ Configured VS Code / Cursor IDE helpers (.vscode/vscode.html-custom-data.json & snippets)
▲ Add bridge auto-start to your Next config:
import { withShavinBridge } from "@shavin/mcp/next";
export default withShavinBridge(yourNextConfig);

init 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: imports tokens.css, base.css (in the base layer) and theme-v4.css after Tailwind, and adds the @source lines.
  • Imports the Shavin stylesheet in your global CSS (app/globals.css, src/app/globals.css, src/index.css and 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 entry src/main, src/App or app/root) in ThemeProvider. 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 .dark class that provider sets.

Brand tokens

  • Creates brand-tokens.css and adds brand:gen and brand:check scripts. When @shavin/cli is installed in the project, brand:gen also runs before dev and build. See Brand colour tokens.

AI agent setup

  • Asks before installing @shavin/mcp and @shavin/skills as dev dependencies, then copies the skills into .agents/skills/.
  • Writes SHAVIN.md (your project's design brief), AGENTS.md and CLAUDE.md.
  • Registers the MCP server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json).
  • If @shavin/mcp is 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 check

Confirms 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-signin

If @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.

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