npm package: @jonasjuhl/devtools
Description: Generic development overlay tools — grid inspector, typography inspector, spacing checker, accessibility scanner, z-index map
Latest version: 0.8.0

# @jonasjuhl/devtools

A comprehensive development overlay toolkit for React applications. 14 tools covering layout, typography, accessibility, performance, SEO, brand compliance, and more — all from a floating panel or keyboard shortcuts.

## Install

```bash
npm install @jonasjuhl/devtools
```

## Setup

Wrap your app with `DevToolsProvider`, then render `GridOverlay` and `DevTools`. No `"use client"` wrapper needed — the package handles it. Both components portal to `document.body`, so they work inside any overflow container.

```tsx
import { DevToolsProvider, GridOverlay, DevTools } from "@jonasjuhl/devtools";

export default function Layout({ children }) {
  return (
    <DevToolsProvider>
      {children}
      <GridOverlay />
      <DevTools />
    </DevToolsProvider>
  );
}
```

### Brand Audit Config (optional)

Pass a brand config to enable brand compliance checking:

```tsx
import { DevToolsProvider, type BrandAuditConfig } from "@jonasjuhl/devtools";

const brand: BrandAuditConfig = {
  colors: ["#141413", "#E2DEDC", "#8897ED"],
  fonts: ["jetbrains mono", "noto sans mono"],
  sizes: [8, 10, 12, 14, 16, 24, 32, 48, 64],
  weights: [200, 300, 400, 700, 800, 900],
  spacingBase: 8,
};

<DevToolsProvider brand={brand}>
```

Or auto-discover tokens from CSS custom properties:

```tsx
<DevToolsProvider brand={{ cssPrefix: "--brand" }}>
```

## Usage

Press **`` ` ``** (backtick / ½ / §) to enable devtools. A floating wrench button appears in the bottom-left corner.

### Tools

| Key | Tool | Description |
|-----|------|-------------|
| **G** | Grid | Visualizes CSS grid columns, margins, gutters from `--grid-*` custom properties |
| **C** | Containers | Highlights grid parents, max-width containers, grid children, media elements, semantic elements. Shows off-grid alignment when G+C are both active |
| **B** | Breakpoint | Shows current breakpoint name, viewport width, column count |
| **T** | Typography | Hover text to inspect font-family, size, weight, tracking, leading, color |
| **S** | Spacing | Hover elements to see margin (orange), padding (green), gap, display, flex/grid props |
| **A** | Accessibility | Scans text for WCAG contrast issues with ratio badges (AAA/AA/AA-LG/FAIL) |
| **Z** | Z-Index | Maps all positioned elements with their z-index values |
| **F** | Performance | FPS graph, frame time, memory, DOM nodes, CLS, long tasks, network transfer. Tracks session min/max/avg FPS |
| **R** | Brand Audit | Flags colors, fonts, sizes, weights, spacing that don't match brand tokens |
| **P** | Paint Flasher | Flashes elements that mutate (DOM changes, style/class mutations). Tracks mutation count |
| **I** | Image Audit | Flags missing alt, over/under-scaled images, missing lazy loading, missing width/height. Also audits videos for missing poster, autoplay+muted, missing captions |
| **X** | Focus Order | Numbered badges showing keyboard tab order. Red flags for tabindex > 0 |
| **N** | Render Count | Heatmap of most-mutated DOM elements with mutation count badges |
| **M** | Scroll Depth | Fold lines at current viewport, iPhone SE, iPhone Pro Max, iPad heights |
| **L** | Light/Dark Diff | Flags elements where color+background don't change when switching data-theme |
| **E** | SEO Audit | Meta tags, heading hierarchy, link issues, structured data, content signals, LCP candidate |
| **D** | Dump to Console | Logs structured JSON snapshot of all active tools to console |

### AI Agent Integration

Press **D** to dump a structured JSON snapshot to the browser console, prefixed with `[DevTools Snapshot]`. Designed for AI agents to read via browser automation:

1. Press `` ` `` to activate devtools
2. Press tool keys to enable desired tools (e.g., `F` + `A` + `E` + `R`)
3. Wait a few seconds for data collection
4. Press `D` to dump
5. Read console with pattern `[DevTools Snapshot]`

The dump includes session-tracked performance data (min/max/avg FPS, peak frame time) so the agent captures the full story even if the page is static when reading.

### CSS Custom Properties

The grid overlay reads these (define them in your design system):

- `--grid-columns` — number of columns (e.g. 12)
- `--grid-margin` — page margin (e.g. 40px)
- `--grid-gutter` — column gap (e.g. 24px)
- `--grid-max-width` — max container width (e.g. 1920px)

## Zero dependencies

All styling is inline — no Tailwind or external CSS required. Both overlay components portal to `document.body` via `createPortal`. The only peer dependency is React 18+.