Debug setup

Step 0: Run The Automated Health Check

Before manually editing configuration files, run the Shavin CLI diagnostic tool. It inspects your project tree, scans for missing dependencies, verifies Tailwind configurations, and validates root ThemeProvider wiring in seconds:

npx @shavin/cli check

If the CLI check passes all 7 checks with green checkmarks, your design system is properly wired and ready for use. If any layer fails, use the debug checklist below to resolve it.

7-Layer Setup Diagnostic Checklist

Package Dependencies

Check core npm packages are installed.

Tailwind Preset

Verify preset and content scan globs.

Stylesheets

Ensure design system tokens are imported.

ThemeProvider

Verify root layout wrapper is mounted.

Font Loading

Confirm Outfit font weights are loaded.

Brand Tokens

Validate brand color scripts and CSS.

AI & MCP Config

Verify agent skills and IDE connection.

1. Package Dependencies Check

Ensure @shavin/ui and its peer dependencies are present in your package.json:

npm install @shavin/ui lucide-react clsx tailwind-merge class-variance-authority

If using icons or specialized animations, ensure lucide-react is installed.

2. Tailwind Preset & Content Scanner

Ensure tailwind.config.ts (or tailwind.config.js) includes the preset and includes @shavin/ui in its content array so Tailwind extracts all class utilities:

// tailwind.config.ts
import preset from "@shavin/ui/tailwind-preset";
import type { Config } from "tailwindcss";

const config: Config = {
  presets: [preset],
  content: [
    "./src/**/*.{ts,tsx}",
    "./app/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./node_modules/@shavin/ui/src/**/*.{ts,tsx}",
  ],
};

export default config;

3. Design System Stylesheet Import

Verify that @import "@shavin/ui/styles.css"; is placed at the top of your global CSS entrypoint (e.g. globals.css, app.css, or index.css):

/* globals.css */
@import "@shavin/ui/styles.css";
@tailwind base;
@tailwind components;
@tailwind utilities;

4. Root Layout ThemeProvider Mounting

<ThemeProvider> is required to inject semantic CSS variables and prevent unstyled flashes. Wrap your root layout inside it:

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

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider accentColor="grass" grayColor="gray" radius="large" scaling="95%">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

In development mode, ThemeProvider auto-mounts the ShavinDevInspector HUD.

5. Typography & Outfit Font Setup

Import the Outfit font weights in your root layout or global stylesheet:

import "@fontsource/outfit/400.css";
import "@fontsource/outfit/500.css";
import "@fontsource/outfit/600.css";

For Next.js Google Fonts optimization, see the Custom Fonts Guide.

6. Custom Brand Color Tokens (Optional)

If using custom branding colors, initialize and compile brand-tokens.css:

# Scaffold brand-tokens.css
npx @shavin/cli brand --init

# Compile brand tokens after adding your brand hex values
npm run brand:gen

# Validate brand tokens
npm run brand:check

7. AI Assistant & MCP Integration

Verify that your AI assistant (Cursor, Antigravity, Claude Code) has the Shavin MCP server configured in .cursor/mcp.json:

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

You can also install or update the agent cognitive skill files manually with npx @shavin/mcp install_skills.

Render Sanity Test

Once all layers are verified, render this minimal test card to ensure proper styling and token inheritance:

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

export function SanityCheck() {
  return (
    <Card className="max-w-md p-6">
      <Flex direction="column" gap="3">
        <Flex align="center" justify="between">
          <Heading size="md">Setup Verified</Heading>
          <Badge color="accent" variant="soft">OK</Badge>
        </Flex>
        <Text color="muted">
          All design system tokens, font styles, and radius geometries are active.
        </Text>
        <Button variant="solid" size="md">Confirm</Button>
      </Flex>
    </Card>
  );
}

Need standard 1-command scaffolding? Switch back to the Installation Guide .