@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

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.

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:

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:

<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+.