Layout inspector
NewAn analytics page that turns into a wireframe and measures itself: grid, padding and alignment, live from the page, pink where it breaks.
layout-inspector/layout-inspector.tsxInspect to see the wireframe and its measurements.
The live component, numbered part by part. Every measurement is read from it as it is drawn. Point at a row to outline its part, or at a part to find its row.
The choices it offers, each value drawn live and the default marked, with how to pick one.
When to use
- Reviewing a screen’s layout with a team: the wireframe takes colour and words out of the way, and the marks say where the spacing and the alignment break.
- A design review or a case study that shows an iteration: the draft’s flaws in pink, the revision’s fixes as check marks, measured on the same page.
- Teaching a spacing system: every padding, gap and size on the page is labelled, blue on the 4-px grid and pink off it.
- A dense data page, a table with a sidebar and a toolbar, where off-by-a-few-pixels problems are real and hard to see by eye.
When not to use
- Inspecting your own app in development: the browser’s developer tools measure any page; this one inspects the page it ships with.
- A page people use to get work done. The inspector is a review surface; the finished dashboard works on its own without it.
- Pixel-perfect comparison with a design file. It checks the page against rules (the grid, alignment), not against a picture.
- Small screens as the main place it is read: on a phone the page lays out at phone width and the marks get dense; zoom in with the tour.
Reading the marks
- Blue is a measurement on the 4-px grid, or two edges that meet: a check mark where they do.
- Pink is off the grid, or a gap between edges that should meet, with its width in px.
- Green, under the pointer or the focus, is an element’s padding; the blue box and its badge are its size.
- Tags on the rulers give each guide’s position in the page’s px, whatever the zoom.
The four layers
- Regions: the sidebar’s width and padding, the top bar’s height, and the search box’s place in the bar, checked against its middle.
- Rows: each visible row’s padding, the thumbnail’s inset and gap, and whether the thumbnail ends where its text does.
- Columns: each column’s width, a guide on its header’s aligned edge, and the gap from that guide to every value in view.
- Controls: the header tools’ heights against the one most of them share, and the gaps between them.
Each one drawn with the component itself, used well or badly.
The words are the layer names, the step names of the tour, and the report’s issues.
- Layer names are nouns:
Regions,Rows,Columns,Controls. - Issues say what and how much, in px: “Row padding is 14 px, off the 4-px grid”, “Thumbnails end 16 px above their text”.
- Numbers are measured, rounded to one decimal; nothing on the marks is typed by hand.
You can add this component with the shadcn CLI or by hand:
Into components/layout-inspector of any React project, with no setup:
npx shadcn@latest add https://brunodelorence.com/r/layout-inspector.json- Copy the component files
Copy these files into one folder of your project, keeping their relative imports together, or download them as a ZIP:
layout-inspector/layout-inspector.tsxlayout-inspector/layout-inspector.module.csslayout-inspector/dashboard.tsxlayout-inspector/measure.tslayout-inspector/overlay.tsxlayout-inspector/data.tslayout-inspector/art.tsxlayout-inspector/glyphs.tsxlayout-inspector/demo-pointer.tsxlayout-inspector/use-autoplay.ts
- Import it
As shown under Usage, below.
Either way it needs React 19.2 and a bundler that supports CSS Modules, such as Next.js or Vite. It has a dark colour scheme: it follows your page’s color-scheme, light unless the page sets one, or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
Usage
import { LayoutInspector } from './layout-inspector';export function LayoutReview() { return <LayoutInspector defaultLayers={['rows']} autoplay={false} />;}Each state below is a live instance, locked so you can study it.
The pieces it is built from, each with its measurements read live.
A “Post performance” report for a small ceramics studio: a sidebar of reports, a top bar with search, a header with its tools and a table of twelve posts under a row of totals. Press Inspect and it strips down to a grey wireframe on a canvas with rulers, and layers of measurements draw over it, read from the live page: the regions, each row’s padding and its thumbnail’s alignment, the columns’ widths and edges, the header’s controls. Blue is on the 4-px grid or aligned; pink is off it, with the gap in px. Switch the draft to its revision and the marks follow the page as it moves, turning into check marks. Hover or focus anything to measure it, or let the tour walk the whole review.
- Nothing on the marks is typed: each layer finds its pieces by data-m names and reads their client rects and computed padding, divided by the camera’s scale, so every value is in the page’s own CSS px at any zoom. Values print to one decimal.
- Two rules colour a mark. A size or a spacing is blue when it is a multiple of 4 px (within half a pixel) and pink when not; an alignment, a thumbnail’s foot against its text’s, a value’s edge against its header’s, a search box’s middle against the bar’s, is a check mark when the two meet and a pink gap with its width when they don’t.
- The draft and the revision are the same markup: custom properties on the page set the spacing (sidebar 234 → 240 px, row padding 14 → 16, thumbnails 40 → 56, tools 28 → 32 px tall and 6 → 8 apart) and move on 0.45 s ease transitions. For 700 ms after a change the marks are read again every frame, so they follow the page as it moves.
- The wireframe is a class on every piece of text: its background is a gradient bar of a registered colour (@property), 0.74 em tall, cloned on each line with box-decoration-break, that fades in over 0.4 s as the words turn transparent. Icons become squares and thumbnails grey tiles the same way.
- A desktop page is laid out at 1240 px or wider and scaled to the canvas; a phone-width canvas lays it out at its own width, where the sidebar and breadcrumbs go and the table scrolls in its own box. The table keeps its head sticky, and its marks are cut to the box’s visible part.
- A camera zooms on the part a layer is about, up to 3×, in one transform over page and marks, eased in log space over 1 s (cubic in-out). Lines and borders divide their width by the zoom and badges are scaled back by it, so they keep their screen size; the canvas rulers redraw each frame with ticks 56 px or more apart and a tag per guide.
- The tour is twelve steps: the draft, its wireframe, each layer’s flaws then its fix, the zoomed-out wireframe, and the rebuilt page with colour thumbnails and post types as chips. While on screen and untouched, a demo pointer plays it in about 27 s, with a hover over a thumbnail and a title; any input from the reader stops it.
- Every colour is a token on the root, light-dark() where the two schemes differ. The rulers read theirs from real properties of their canvases, and a 1 ms colour transition on them tells the script when the scheme changed, wherever the change came from.
| Prop | Type | Default | Description |
|---|---|---|---|
defaultRevision | 'draft' | 'revised' | 'draft' | The page it starts with: the draft, with a flaw in each layer, or the revision that fixes them. |
defaultLayers | ('regions' | 'rows' | 'columns' | 'controls')[] | [] | The layers drawn at the start; any layer also starts in the wireframe and turns the demo off. |
defaultInspect | boolean | false | Starts in the wireframe; it turns the demo off. |
autoplay | boolean | true | While on screen and untouched, a demo pointer plays the tour; any input from the reader stops it. |
colorScheme | 'light' | 'dark' | 'system' | — | Light or dark colours, or the reader’s; without it, the page’s color-scheme. |
className | string | — | A class for the root. |
Keyboard
- Tab reaches Inspect, each layer, the revision and the tour. Enter or Space presses them; the arrows move the revision.
- With Inspect on, focusing anything in the page measures it, as a hover does; Escape turns Inspect off.
- The table’s scroll box is a focusable region, so the arrows scroll it.
Screen readers
- Inspect and the layers are toggle buttons with
aria-pressed; a layer’s name carries its count (“Rows, 2 issues”). - The marks and the rulers are hidden from screen readers; the report under the canvas says the same in words, in a polite live region.
- The page under inspection is real markup: a banner, a navigation, a main region and a table with header cells.
Colour and motion
Pink and blue are never the only cue: an issue has a number and a check mark has its glyph, and the report says each one in words. With reduced motion, the camera jumps, the wireframe and the fixes change at once, and the demo does not play.
In this build
- The inspector’s controls are a toolbar: Inspect and the four layers are toggle buttons with aria-pressed, each layer named with its count (“Rows, 2 issues”); the revision is a radio group the arrows move; the tour is two buttons around the step’s name.
- With Inspect on, focusing an element of the page measures it as a hover does, and Escape turns Inspect off. The table’s scroll box is a focusable region the arrows scroll.
- The marks and the rulers are hidden from screen readers; the line under the canvas says what the drawn layers found, in words, in a polite live region (quiet while the demo plays).
- No mark relies on colour alone: an issue carries its number, an alignment its check glyph, and the report names each one.
- Every control shows a focus ring on keyboard focus. With reduced motion the camera jumps, the wireframe and the fixes change at once, and the demo does not play.
The complete source behind this demo. Open source under the MIT license, © 2026 Bruno Delorence: copy it, change it, ship it.
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useEffectEvent, useLayoutEffect, useRef, useState, type CSSProperties, type FocusEvent as ReactFocusEvent, type PointerEvent as ReactPointerEvent,} from 'react';import { Dashboard } from './dashboard';import { DemoPointer, runDemo, type Point } from './demo-pointer';import { Icon, type Glyph } from './glyphs';import { LAYERS, measureElement, measureLayer, type Layer, type Mark,/* Copyright (c) 2026 Bruno Delorence. MIT License. *//* Layout inspector (layout-inspector.tsx): an inspector's toolbar over a grey canvas with rulers, the "Post performance" page on it, and a line under it that names what the measurements found. The page is drawn at 1240 px or wider and scaled to the canvas (a phone-width canvas lays it out at its own width instead); a camera zooms on it with a transform the script writes, along with --inv, one over the zoom, which the marks use to keep their lines one screen px thick and their badges one size. The draft and the revision differ by the custom properties set under .frame below: each data-fix-* attribute changes one area's spacing, and the measurements follow the layout as it moves (0.45 s, ease). Colours are the tokens below, light-dark(light, dark) where the two differ: the component takes the color-scheme it inherits from the page, or the one its colorScheme prop sets. *//* The wireframe's bars fade in and out: a registered colour can transition inside a gradient. */@property --li-bar { syntax: '<color>'; inherits: false; initial-value: transparent;}// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useState, type ReactNode, type Ref } from 'react';import { Thumb } from './art';import { BRAND, METRICS, NAV, POSTS, formatValue } from './data';import { Icon, Mark, type Glyph } from './glyphs';import styles from './layout-inspector.module.css';/* * The page under inspection: a "Post performance" report with a sidebar of reports, a top bar * with a centred search, a header with its tools, filters, and a table of twelve posts under a * row of totals. It is an ordinary responsive page: the inspector only reads it. Every piece * of text sits in a span of class .t, which is what turns into a grey bar in the wireframe, and * the pieces the measurements look for carry a data-m name. * * Its spacing comes from custom properties that the draft and the revision set differently * (data-fix-* on the page, in the stylesheet), so a fix is a real change of layout that the * inspector measures again, not a different picture. */const SIDE_ICONS: Glyph[] = ['home', 'star', 'network', 'people', 'coin', 'rocket', 'palette'];// Copyright (c) 2026 Bruno Delorence. MIT License./* * The measurements, read from the live page every time they are drawn: nothing here is a typed * number. Each layer looks up its pieces by their data-m names, reads their boxes and computed * styles, and returns marks in page px (the page's own CSS px, whatever the camera's zoom), plus * the issues it found, in words. * * Two rules decide the colour of a mark. A spacing or a size is blue on the 4-px grid and pink * off it. An alignment (a thumbnail's foot and its text's, a value's edge and its header's, a * search box's middle and the bar's) is a check mark when the two meet and a pink gap, with its * width, when they don't. */export type Layer = 'regions' | 'rows' | 'columns' | 'controls';export const LAYERS: { id: Layer; label: string }[] = [ { id: 'regions', label: 'Regions' }, { id: 'rows', label: 'Rows' }, { id: 'columns', label: 'Columns' }, { id: 'controls', label: 'Controls' },];export type Rect = { x: number; y: number; w: number; h: number };export type Tone = 'blue' | 'pink' | 'pad';// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties } from 'react';import { Icon } from './glyphs';import { print, type Group, type Mark } from './measure';import styles from './layout-inspector.module.css';/* * The marks, drawn over the page in its own px: they sit in the same zoomed layer as the page, * so the camera moves them together. Lines and borders divide their width by the zoom (--inv) * and badges are scaled back by it, so at any zoom a line stays one screen pixel and a badge * stays the same size, as an inspector draws them. A group with a clip is cut to it: the marks * of the table stop at the edges of its scroll box, under its sticky head and first column. */function MarkView({ mark, dx, dy }: { mark: Mark; dx: number; dy: number }) { if (mark.kind === 'box') { return ( <span className={styles.mBox} data-tone={mark.tone} data-soft={mark.soft || undefined}// Copyright (c) 2026 Bruno Delorence. MIT License./* * What the dashboard shows: a month of posts from a small ceramics studio, with their reach and * engagement. Plain data, so the page and the docs read the same numbers. */export type Art = 'glaze' | 'kiln' | 'bowls' | 'wheel' | 'shelf' | 'vase' | 'text' | 'link';export type Post = { id: string; title: string; author: string; kind: 'Reel' | 'Article' | 'Post' | 'Reply' | 'Carousel' | 'Video' | 'Photo'; boosted?: boolean; art: Art; date: string; time: string; /** In the order of METRICS; null when the network doesn't report it. */ values: (number | null)[];};export type Metric = { id: string;// Copyright (c) 2026 Bruno Delorence. MIT License.import type { ReactNode } from 'react';import type { Art } from './data';/* * The posts' thumbnails, drawn: a few flat studio scenes (a glazed mug, the kiln, a stack of * bowls, the wheel, a shelf, a vase) and two plain tiles for posts with no picture (a text post * and a link). Each is a 40-unit square that fills its box; the stylesheet greys them in the * draft and in the wireframe. */const SCENES: Record<Art, ReactNode> = { glaze: ( <> <rect width="40" height="40" fill="#2f4a5c" /> <rect y="28" width="40" height="12" fill="#5c4434" /> <path d="M12 13h14v13a5 5 0 0 1-5 5h-4a5 5 0 0 1-5-5z" fill="#7fc3c9" /> <path d="M12 13h14v5c-2 2-4-1-7 1s-5 0-7-1z" fill="#d9efe9" /> <path d="M26 16h2a3 3 0 0 1 0 6h-2" fill="none" stroke="#7fc3c9" strokeWidth="2" /> <ellipse cx="19" cy="13" rx="7" ry="1.6" fill="#a6dbd9" /> </> ), kiln: (// Copyright (c) 2026 Bruno Delorence. MIT License./* * The dashboard's icons and the inspector's, drawn by hand on a 16-unit grid with a 1.4-unit * stroke in currentColor. Each is decorative: the control it sits in carries the name. */const PATHS = { home: 'M2.8 7.2 8 3l5.2 4.2V13H9.6V9.8H6.4V13H2.8z', star: 'M8 2.6l1.7 3.5 3.8.5-2.8 2.6.7 3.8L8 11.2 4.6 13l.7-3.8-2.8-2.6 3.8-.5z', network: 'M4.5 5.5a2 2 0 1 0 0-.01M11.5 5.5a2 2 0 1 0 0-.01M8 12.5a2 2 0 1 0 0-.01M5.6 7.2 7 10.6M10.4 7.2 9 10.6', people: 'M6 7.4a2.2 2.2 0 1 0 0-4.4 2.2 2.2 0 0 0 0 4.4zM2.4 13c0-2.2 1.6-3.6 3.6-3.6s3.6 1.4 3.6 3.6M10.6 7a1.8 1.8 0 1 0 0-3.6M11.4 9.5c1.3.3 2.2 1.5 2.2 3.5', coin: 'M8 13.4A5.4 5.4 0 1 0 8 2.6a5.4 5.4 0 0 0 0 10.8zM9.8 6.2C9.4 5.6 8.8 5.4 8 5.4c-1 0-1.8.5-1.8 1.3 0 1.9 3.8.9 3.8 2.8 0 .8-.9 1.3-2 1.3-.8 0-1.5-.3-1.9-.9M8 4.4v7.2', rocket: 'M9.6 3.2c2-.8 3.2-.6 3.2-.6s.2 1.2-.6 3.2L8.4 9.6 6.4 7.6zM6.4 7.6 4 7.4l1.6-1.8h2.2M8.4 9.6l.2 2.4 1.8-1.6V8.2M4.6 11.4 3 13', palette: 'M8 2.6a5.4 5.4 0 0 0 0 10.8c.8 0 1.2-.5 1.2-1.1 0-.8-.6-1-.6-1.7 0-.6.5-1 1.1-1h1.5c1.5 0 2.4-1.2 2.4-2.6 0-2.4-2.5-4.4-5.6-4.4zM5.2 7.4h.01M7 5h.01M10 5.2h.01', chevronRight: 'M6.5 4.5 10 8l-3.5 3.5', chevronDown: 'M4.5 6.5 8 10l3.5-3.5', bell: 'M4.2 11V7.4a3.8 3.8 0 0 1 7.6 0V11l1 1.2H3.2zM6.6 13.6a1.5 1.5 0 0 0 2.8 0', help: 'M8 13.4A5.4 5.4 0 1 0 8 2.6a5.4 5.4 0 0 0 0 10.8zM6.4 6.6a1.7 1.7 0 0 1 3.3.4c0 1.2-1.7 1.4-1.7 2.6M8 11.3h.01', pen: 'M10.4 3.4l2.2 2.2-6.8 6.8-2.8.6.6-2.8zM9.2 4.6l2.2 2.2',// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties, Ref } from 'react';/* * The demo's pointer, and the steps that move it. A demo is a script of awaited steps: wait, or * glide the pointer somewhere. Stopping the demo (the reader takes over, or it scrolls away) ends * the step in progress at once: its promise rejects, which ends the script right there, and the * pointer fades out. * * Each glide is a curved flight played by the Web Animations API, so nothing runs frame by frame. * The points of the flight are handed to whoever wants to move along with it (nothing here uses * them yet). The arrow and the hand are HTML boxes * that swap by their visibility: a change of style inside an SVG would lay the SVG out again. */export type Point = { x: number; y: number };/** A glide's path and timing, for an animation that plays along with it. */export type Flight = { points: Point[]; timing: KeyframeAnimationOptions };export type Demo = {// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useRef, useState } from 'react';/* * When a demo may play on its own: while part of it is on screen and the tab is visible, never * under reduced motion, and never again once the reader has used it: `take()` hands it to the * reader for good (until the component mounts again), so it can't come back on its own. */export function useAutoplay<T extends HTMLElement>() { const ref = useRef<T>(null); const [visible, setVisible] = useState(false); const [reduced, setReduced] = useState(true); const [taken, setTaken] = useState(false); useEffect(() => { const element = ref.current; if (!element) return; let onScreen = false; const update = () => setVisible(onScreen && !document.hidden); const observer = new IntersectionObserver( ([entry]) => {