css-spec

An element inspector for your Next.js dev server,
built for pair-coding with AI.

Hover any element to read its box model, type, and color spec. Open the inventory to edit design tokens live and write them back to your globals stylesheet. When a change can’t be made safely in place, it copies a precise prompt for your AI coding tool — never a global find-replace.

$ npm i -D css-spec

$ npx css-spec init

inspect mode is already on — this page runs the real overlay against a simulated filesystem. Hover anything; turn it off with ⌥D or the switch up top.

Specimen

Turn Inspect on and hover the card. ⌥-click to pin a selection, esc to release.

Design tokens

globals.css · 14 tokens

live

Every value on this card resolves to a :root custom property. Inspect it to see which one.

What it does

One overlay, the whole redline workflow.

Hover to inspect

Box model, type scale, and color spec in a floating callout. Dotted guides, margin & padding rings, dimension tabs — DevTools precision, tuned for pair-coding with AI.

Pin & measure

Click to lock a selection. The rest of the page dims so you can read the spec, compare values, and edit without chasing your cursor.

Edit tokens live

The inventory panel lists every :root token with usage counts. Change a value, watch the page update, then write it back to your globals stylesheet.

AI-tool native

When an edit can’t be applied safely in place, css-spec copies a precise, natural-language prompt naming the exact CSS rule — for Claude Code, Cursor, Copilot. Never a global find-replace.

Architecture outline

An always-on wireframe layer that outlines every layout box with its tag — see the structure of a page the way you’d see it in a design file.

Dev-only by design

The server route returns 404 in production and the overlay is tree-shaken out of production builds. It cannot ship to your users.

Quick start

Zero config. init wires the route, the overlay, and the styles.

install
```
npm i -D css-spec
npx css-spec init
```
run your dev server
```
npm run dev
```

toggle the overlay

press ⌥D  // hover · pin · edit · ship

Prefer to wire it yourself?

// app/api/design-spec-dev/route.ts
import { createDesignSpecHandler } from "css-spec/server";

export const POST = createDesignSpecHandler();
export const runtime = "nodejs";

// app/layout.tsx — tree-shaken from production
const DesignSpecOverlay =
  process.env.NODE_ENV !== "production"
    ? dynamic(() => import("css-spec/client").then((m) => m.DesignSpecOverlay))
    : () => null;

// once, anywhere it loads in dev
import "css-spec/style.css";

Configuration is optional — css-spec auto-detects the stylesheet declaring the most :root tokens. Point it somewhere else with a designSpec key in package.json or a design-spec.config.json.