Shavin Dev Inspector

What is the Shavin Dev Inspector?

ShavinDevInspector (also exported as ShavinDevTools) is a floating, draggable design inspector that auto-mounts in your dev server preview when you wrap your app in ThemeProvider. It gives you a live theme configurator, a real-time token discipline audit scanner, and an MCP connection status panel — all without leaving your browser.

Zero-config: The inspector appears automatically in development (NODE_ENV !== "production"). It never renders in production builds, so there is nothing to remove before deploy.

How It Gets Injected

The injection chain is simple:

You wrap your app in <ThemeProvider> at the root layout.
ThemeProvider computes showDevTools = devTools ?? (NODE_ENV !== "production").
When showDevTools is true, it renders <ShavinDevTools /> alongside your children.

The CLI init command auto-detects your root layout and wraps it for you — you do not need to manually add ShavinDevTools anywhere. It is entirely managed by ThemeProvider.

Manual Setup (Framework-Specific)

If you did not run npx @shavin/cli init, or the CLI could not auto-detect your layout, add ThemeProvider manually to your root layout. Ensure your entire application sits inside it:

Next.js App Router

// app/layout.tsx
import { ThemeProvider } from "@shavin/ui";

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

Next.js Pages Router

// pages/_app.tsx
import { ThemeProvider } from "@shavin/ui";

export default function App({ Component, pageProps }) {
  return (
    <ThemeProvider>
      <Component {...pageProps} />
    </ThemeProvider>
  );
}

Vite / CRA

// src/App.tsx (or src/main.tsx root)
import { ThemeProvider } from "@shavin/ui";

function App() {
  return (
    <ThemeProvider>
      <div className="App">
        {/* your entire app */}
      </div>
    </ThemeProvider>
  );
}

Remix

// app/root.tsx
import { ThemeProvider } from "@shavin/ui";

export default function App() {
  return (
    <ThemeProvider>
      <html>
        <head>
          <Meta />
          <Links />
        </head>
        <body>
          <Outlet />
          <Scripts />
        </body>
      </html>
    </ThemeProvider>
  );
}

ThemeProvider Props

ThemeProvider accepts the following props. All are optional — defaults apply the "Default" theme preset:

theme

Named preset (e.g. "Editorial", "Default"). Applies the whole config bundle.

accentColor

One of 24 named accents (e.g. "Grass") or a literal "#rrggbb".

grayColor

Neutral scale: "Zinc" | "Slate" | "Gray" | "Neutral" | "Stone".

radius

"none" | "small" | "medium" | "large" | "full".

scaling

Density percentage: 90 | 95 | 100 | 105 | 110.

panelBackground

"solid" | "translucent".

displayFont

Display heading font preset family string.

bodyFont

Body text font preset family string.

devTools

Explicitly show/hide the Dev Inspector. Defaults to true in dev, false in production.

Three Tabs

The inspector panel has three tabs:

Theme

Live theme configurator — pick accent, neutral gray, radius, scaling, panel background, display font, and body font. Changes apply instantly to your whole app via CSS variables. Generates a ready-to-paste ThemeProvider snippet.

Audit

Live DOM scanner that inspects your page for token discipline violations: hardcoded hex/RGB inline styles, arbitrary container radii instead of token variables. Click any violation to scroll to it with a highlight beacon.

MCP Status

Shows real-time connection status of the Shavin MCP server, available tool capabilities, and daemon health — so you can verify your AI assistant is wired to the design system brain.

Inspector Placement

The floating trigger button snaps to one of four screen corners and can be dragged to reposition. The default is bottom-left. To change the default, pass a position prop — but note this is set on ShavinDevTools directly, not ThemeProvider. For most projects the default is fine and you never need to touch it:

import { ThemeProvider, ShavinDevTools } from "@shavin/ui";

// ThemeProvider manages the inspector automatically.
// To customise placement, mount ShavinDevTools yourself:
<ThemeProvider devTools={false}>
  {children}
  <ShavinDevTools position="bottom-right" />
</ThemeProvider>

bottom-left

Default — 20px offset from bottom-left corner

bottom-right

20px offset from bottom-right corner

top-left

20px offset from top-left corner

top-right

20px offset from top-right corner

Forcing the Inspector in Production

By default, the inspector self-guards and never renders in production (NODE_ENV === "production"). If you need it in a staging or preview deployment that runs in production mode, use the forceShow prop:

<ShavinDevTools forceShow position="bottom-right" />

Do not ship forceShow to production. It adds ~60KB of inspector UI to your bundle. Reserve it for staging environments only.

Disabling the Inspector

To turn off the inspector entirely (e.g. for specific pages or environments), pass devTools={false} to ThemeProvider:

<ThemeProvider devTools={false}>
  {children}
</ThemeProvider>

Learn more about theme configuration options in the Theme System guide, or explore AI-assisted development in the MCP Setup guide.