Getting started

Scaffold and verify @shavin/ui configuration in any React or Next.js app in one command. The CLI automatically installs @shavin/ui, injects Tailwind presets, imports global CSS, wraps your root layout in ThemeProvider, scaffolds brand-tokens.css for custom brand colors (with brand:gen / brand:check / predev / prebuild scripts auto-wired), writes the SHAVIN.md design brain, installs .agents/skills/, and configures .cursor/mcp.json for instant zero-config IDE autocomplete:

npx @shavin/cli init

1. Install "@shavin/ui"
2. Configure Tailwind Preset
3. Import Styles
4. Wrap App in ThemeProvider
5. Scaffold Brand Color Tokens
6. Install Agent Skills (.agents/skills/)
7. Configure IDE MCP Integration (.cursor/mcp.json)
8. Verify Setup

Add the @shavin/ui/tailwind-preset to your tailwind.config.ts so your application resolves all semantic token utilities:

// tailwind.config.ts
import preset from "@shavin/ui/tailwind-preset";

export default {
  presets: [preset],
  content: ["./src/**/*.{ts,tsx}", "./node_modules/@shavin/ui/src/**/*.{ts,tsx}"],
};

Add the design system stylesheet import to your project's root CSS file:

/* Add to your existing app stylesheet (e.g. globals.css / global.css) */
@import "@shavin/ui/styles.css";

ThemeProvider is mandatory for Shavin to function correctly. It applies your theme configuration (accent, neutral, radius, density) as CSS variables and auto-mounts ShavinDevInspector in development mode so you get a live design inspector in your dev server preview. Wrap your entire application inside it:

// app/layout.tsx (Next.js App Router)
import { ThemeProvider } from "@shavin/ui";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

The CLI init command auto-detects your root layout (app/layout.tsx, pages/_app.tsx, src/App.tsx, app/root.tsx) and wraps it automatically. For manual placement in other frameworks, see the Shavin Dev Inspector guide.

By default, Shavin uses the RGB color space for maximum browser compatibility. For projects on Tailwind v4 that want wider gamut support and perceptual color mixing, pass --oklch during init:

npx @shavin/cli init --oklch

This deploys global-oklch.css and theme-v4-oklch.css instead of the RGB variants, and sets colorSpace="oklch" on your ThemeProvider. Your hex inputs remain unchanged — the color space is an internal implementation detail. RGB remains the default and is fully supported on both v3 and v4.

npx @shavin/cli init automatically scaffolds a brand-tokens.css file alongside your global CSS, with brand:gen, brand:check, predev, and prebuild scripts wired into package.json. The Tailwind preset is merged into your config automatically. See the Colors page for full documentation:

/* brand-tokens.css — scaffolded automatically */

To scaffold manually (without running full init): npx @shavin/cli brand --init. Then add hex values to the INPUT section and run npm run brand:gen.

Install the @shavin/ui cognitive skill files into your repository so AI coding assistants (Cursor, Antigravity, Claude Code) automatically enforce visual hierarchy, concentric geometry, and token discipline:

# Via CLI (installs into .agents/skills/ automatically)
npx @shavin/cli init

# Or install/update skills standalone via MCP
npx @shavin/mcp install_skills

Skills are placed in .agents/skills/ at your project root and are automatically discovered by Cursor, Antigravity, and other MCP-compatible editors. They include shavin-app, shavin-webpage, visual-compositor, shavin-ui-qa-linter, and shavin-ui-builder.

Enable zero-hallucination AI autocomplete and real-time AST linting in Cursor or compatible IDEs:

// .cursor/mcp.json
{
  "mcpServers": {
    "shavin": {
      "command": "npx",
      "args": ["-y", "@shavin/mcp"]
    }
  }
}

Run the diagnostic check to verify that all Tailwind presets and stylesheets are wired correctly:

npx @shavin/cli check