Observation Guide
DevTools for layout
| Where | Use |
|---|---|
| Elements → Layout pane | toggle grid/flex overlays; shows line numbers, areas, gaps |
| Grid overlay badges | the grid/flex badge next to an element in Elements |
| Performance → Layout blocks | duration and "Nodes That Need Layout: N of M" |
| Performance → red triangle | forced synchronous layout, with the causing stack |
| Rendering → Layout Shift Regions | what moved; the CLS diagnostic |
Elements → Computed → container | which ancestor a container query resolves against |
"Nodes That Need Layout: 12 of 40,000" remains the most useful single number. A high ratio for a local change means containment is missing (fe-05), not that the layout mode is wrong.
Debugging container queries
Three failures account for most container-query bugs:
- No container.
@containerwith no ancestor carryingcontainer-typenever matches. Check Computed →container-typeon ancestors. - Wrong container. Queries resolve against the nearest qualifying ancestor. A nested query
container silently intercepts. Name them (
container-name) and query by name in shared code. - Container sized by its contents.
container-type: inline-sizemeans the inline size may not depend on contents. Afit-contentor floated wrapper will change behaviour when it becomes a container — this reads as "addingcontainer-typebroke my layout", and it is the containment promise being enforced.
Debugging flex and grid
| Symptom | Cause |
|---|---|
| Flex item will not shrink below its content | min-width: auto → min-content. Fix: min-width: 0 |
| Grid item overflows its track | same, on min-width/min-height |
justify-content does nothing | items already fill the line; you probably want flex: 1 or justify-items |
| Gap ignored | not a flex/grid container, or using an old multicol context |
| Nested content will not align across cards | needs subgrid; the usual workaround is fixed heights, which breaks under long strings |
The min-width: auto default is the single most common flex/grid confusion and worth internalising:
flex and grid items refuse to shrink below their content by default.
What these measurements do not tell you
- No paint or compositing cost measured.
RecalcStyleDurationandLayoutDurationonly. - Headless is not headed for compositing; these numbers are style/layout, which are less affected, but do not extend them.
- Synthetic uniform content. Real layouts mix images, fonts, and nested components with their own intrinsic sizing, which changes the measurement burden.
- One viewport. Every result depends on available width.
- No layout thrash here. fe-01 measured 98× from interleaved reads and writes; that dominates everything in this module and is invisible to these experiments by construction.