Layout Debug Mode

Reveal the container, grid, and scroll structure behind a layout that is misbehaving.

simple Developer Experience

What it adds

A toggleable mode that visualises layout containers, grid and flex tracks, scroll regions, and stacking contexts in the running interface.

What your agent is told to do

1
Identify the structures that actually cause layout bugs — grid tracks, flex containers and their direction, scroll containers, positioned ancestors, and overflow clipping — and visualise those specifically rather than outlining every element indiscriminately.
2
Label each visualised region with what it is and, where the app's components are identifiable, which component owns it, so a developer can go from a wrong-looking box to the file that produced it.
3
Let the reviewer filter what is shown, by structure type or by component, because a page with four hundred boxes lit up at once is less legible than the page was without the tool.
4
Draw everything with outlines or overlaid layers that occupy no space in the flow, and confirm by comparison that toggling the mode changes no element's measured position or size.
5
Do not confuse this with CSS Debug Outlines, which owns the blunt everything-gets-a-border switch applied from a single stylesheet. This feature owns the structural, labelled, filterable view; keep one toggle for each and do not have both on by default.

Edge cases it handles

Adding borders shifts every box on the page and invents the bug you were hunting. Use outlines or a separate overlay layer so no dimension changes when the mode is on.
Nested containers three or four deep become an unreadable pile of rectangles; vary treatment by depth and place labels so an inner region's label does not obscure its parent's boundary.
Filtering by component depends on components being identifiable in the DOM; if the app strips that information in production-like builds, the mode must degrade to structural labels rather than showing nothing.
The mode must be restricted to development builds or explicitly authorised internal users. A customer who finds the toggle sees the app's internal component names and structure.
Scroll containers and clipping ancestors are the point of the exercise — mark which element is actually scrolling and which is clipping, because those are rarely the ones people assume.
The mode must survive navigation within the app rather than switching itself off on every route change.
Elements rendered outside the main tree, such as portalled dialogs and floating menus, must be visualised too, or the mode is blind to exactly the components that most often break.

Definition of done

Grid tracks, flex containers, scroll regions, and clipping ancestors are each visualised distinctly.
Toggling the mode changes no element's measured position or size.
Regions are labelled with their structure type and, where available, their owning component.
The visualisation can be filtered by structure type or component.
The mode is unavailable to unauthorised users and absent from production builds.
Portalled and floating content is visualised alongside in-tree content.
The mode persists across in-app navigation.
The feature matches the existing design system.
No existing functionality is broken.

Related features

AI Cost Budgets

Multi-Model Routing

SEO Setup

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.