Installation

1-Command Automatic Setup (Recommended)

Scaffold and configure @shavin/ui in any React or Next.js project with a single command. The CLI auto-detects your framework, installs dependencies, configures Tailwind, imports stylesheets, mounts the root ThemeProvider, and wires AI coding assistant skills:

npx @shavin/cli init

Supports Next.js (App & Pages Router), Vite (React & Remix), Astro, and standard React build tools.

What The CLI Configures Automatically

Dependency Installation

Installs `@shavin/ui`, `lucide-react`, and required styling helpers into your package.json.

Tailwind Preset Injection

Merges `@shavin/ui/tailwind-preset` into your Tailwind configuration for instant token utilities.

Design System Stylesheet

Injects `@import '@shavin/ui/styles.css'` into your global CSS entrypoint.

Layout Root Wrapping

Auto-detects your root layout (`app/layout.tsx`, `pages/_app.tsx`, `src/App.tsx`) and mounts `<ThemeProvider>`.

Typography Setup

Configures Google Fonts Outfit stylesheets for calibrated display and body typography.

AI & MCP Integration

Installs `.agents/skills/` cognitive skills and `.cursor/mcp.json` for zero-hallucination agent pairing.

Brand Color Token Pipeline

Scaffolds `brand-tokens.css` with auto-wired `brand:gen` / `brand:check` scripts in `package.json`.

Live Dev Inspector HUD

Automatically wires `<ShavinDevInspector>` in development mode for in-browser token and contrast audits.

CLI Flags & Options

--oklchTailwind v4 / Wide Gamut

Initializes with perceptual OKLCH color spaces instead of standard RGB for smoother gamut transitions on modern displays.

npx @shavin/cli init --oklch

--overwriteForce Overwrite

Overwrites existing configuration files, templates, and theme settings if you are resetting a project setup.

npx @shavin/cli init --overwrite

Verify Installation

Once initialized, run the diagnostic check command to verify that all Tailwind presets, font stylesheets, and layout wrappers are wired correctly:

npx @shavin/cli check

If any layer reports a warning or error, follow the CLI recommendations or refer to the Debug Setup guide.

Quick Component Test

Import any primitive from @shavin/ui and render your first component:

import { Button, Card, Flex, Heading, Text, Badge } from "@shavin/ui";

export function WelcomeCard() {
  return (
    <Card className="max-w-md p-6">
      <Flex direction="column" gap="4">
        <Flex align="center" justify="between">
          <Heading size="md">Welcome to Shavin</Heading>
          <Badge color="accent">Active</Badge>
        </Flex>
        <Text color="muted">
          Enterprise-grade React design system with strict token architecture.
        </Text>
        <Button variant="solid" size="md">Get Started</Button>
      </Flex>
    </Card>
  );
}

Troubleshooting or Manual Pipeline?

Need to debug a misconfigured layer or manually install step-by-step?