CSS layout bugs are infuriating because the browser is rarely wrong — you are. The box model, margin collapsing, flexbox sizing, and grid auto-placement all have specific rules that, when misapplied, produce layouts that look "random." I've spent hours chasing a 1px gap that turned out to be a rogue `display: inline-block` whitespace node.
This article isn't a CSS reference. It's a mental model and a set of tools you can apply when something doesn't sit where you expect. I'll walk through the most common layout failure modes and the exact steps I use to isolate them.
The First Tool: Visualize the Box Model
Open DevTools, right-click the misbehaving element, and Inspect. Look at the Computed panel. Is the `width` what you expected? The `height`? Often the issue is that the element is wider than its container because of padding or border being added to the width (if `box-sizing` is `content-box`, the default).
I always start by adding this CSS to the page temporarily:
`* { box-sizing: border-box; }`
This switches to the intuitive box model where width includes padding and border. It doesn't fix everything, but it eliminates a huge class of layout bugs instantly.
* {
box-sizing: border-box;
}
.debug-outline {
outline: 2px solid red;
}Use `outline` instead of `border` for debugging — it doesn't affect layout size. I keep a `.debug-outline` class in my DevTools snippets.
Margin Collapsing: The Silent Layout Breaker
Margin collapsing is one of the most confusing behaviors in CSS. When two block elements are stacked vertically, their margins collapse into a single margin equal to the larger of the two. This is by design, but it often causes unexpected gaps or missing spacing.
I once had a product card grid where the bottom margin of each card disappeared. The parent was a `<section>` with no border or padding, so the card's bottom margin collapsed with the section's bottom margin, effectively vanishing into the section's parent.
The Vanishing Margin
- 14:00Design review shows cards have inconsistent spacing at the bottom of the grid.
- 14:05Inspect card: `margin-bottom: 24px` is computed but not visible in the layout.
- 14:10Check parent `<section>` — no border/padding, so margin collapses with section's margin.
- 14:12Fix: add `display: flow-root` to the parent to stop collapsing.
Lesson
Margin collapsing can make margins disappear entirely. Use `display: flow-root` or `overflow: hidden` on the parent to contain child margins.
When a margin seems to vanish, check if the parent has `border`, `padding`, or an `overflow` value other than `visible`. If not, collapsing is happening.
How to Spot Collapsing in DevTools
In the Elements panel, hover over the parent element. The margin area is shown in orange. If you see the child's margin extending into the parent's margin area, collapsing is active. The fix: add `display: flow-root` or `overflow: hidden` to the parent. Or give the parent a `padding-top: 1px` (then adjust).
Overflow: The Root of All Evil
Horizontal scrollbars appearing when they shouldn't. Elements disappearing off the edge. Text overflowing into margins. The cause is almost always an element that is wider than its parent.
The fastest way to find the culprit: open DevTools, go to the Console, and paste this one-liner:
document.querySelectorAll('*').forEach(el => {
if (el.scrollWidth > el.clientWidth) {
console.log(el, el.scrollWidth - el.clientWidth + 'px overflow');
}
});Resist the urge to add `overflow: hidden` to the body. It hides the symptom, not the cause. The overflow will still clip content on smaller screens.
Flexbox Sizing: The `min-width` Trap
Flexbox is powerful, but its default `min-width: auto` on flex items often surprises developers. This means a flex item cannot shrink below its content size (e.g., the width of the longest word). This is why a flex item with long text may refuse to shrink and cause overflow.
Solution: set `min-width: 0` on the flex item (or `overflow: hidden`). This allows the item to shrink below its content size. Similarly, for column direction, use `min-height: 0`.
.flex-container {
display: flex;
}
.flex-item {
min-width: 0; /* allow shrinking */
}Flexbox Gap vs. Margin
Use `gap` instead of margins on flex items. Margins on flex items can behave unexpectedly when wrapping, creating extra space or collapsing. `gap` is supported in all modern browsers and is consistent.
of CSS layout bugs in flexbox are related to min-width or missing explicit widths.
Grid: Unexpected Track Sizes
CSS Grid is generally more predictable than flexbox, but it has its own pitfalls. The most common is relying on `auto` tracks without understanding that they size to content. If you have a grid with `grid-template-columns: 1fr 1fr`, but the content in one cell is wider than the other, the `fr` units distribute the remaining space after content — so the columns may not be equal.
To force equal columns regardless of content, use `minmax(0, 1fr)` instead of `1fr`. This sets the minimum track size to 0, so the `fr` unit can shrink content.
.grid {
display: grid;
grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
}The `height: 100%` Problem
Percentage heights only work if the parent has an explicit height. If the parent's height is `auto` (the default), the child's `height: 100%` resolves to `auto` — effectively doing nothing. This is a common issue when trying to make a child fill a container that itself depends on its content.
The fix: give the parent an explicit height, use `min-height` with `height: 100%`, or use flexbox/grid with `align-items: stretch`.
If `height: 100%` isn't working, check the parent's computed height. If it says `auto`, you have your culprit.
Wrapping Up: A Debug Checklist
- arrow_right1. Inspect the element's computed box model — is width/height what you expect?
- arrow_right2. Add `outline: 2px solid red` to all elements to see boundaries.
- arrow_right3. Check for overflow with the console script above.
- arrow_right4. Look at parent containers — do they have an explicit height or width?
- arrow_right5. Is margin collapsing happening? Check parent's border/padding.
- arrow_right6. For flex items, check if `min-width: auto` is preventing shrinking.
- arrow_right7. For grid, check if `auto` tracks are sizing based on content.
- arrow_right8. Remove `overflow: hidden` to see if it was masking a real issue.
Layout debugging is a skill that improves with practice and a systematic approach. The next time you see a broken layout, resist the urge to randomly tweak CSS. Use the DevTools, isolate the problem, and apply the specific fix. Your future self will thank you.
Frequently asked questions
Why is my flex item not shrinking below its content size?
By default, flex items have `min-width: auto` (or `min-height: auto` in column direction). This prevents them from shrinking below their content size. Set `min-width: 0` (or `min-height: 0`) on the item to allow shrinking.
How do I find the element causing horizontal scroll?
Open DevTools, select the `<body>` or `<html>` element, and look for elements that exceed the viewport width. Use the 'Overlay' (hover over elements) or run `document.querySelectorAll('*').forEach(el => { if (el.scrollWidth > el.clientWidth) console.log(el) })` in the console.
What is margin collapsing and how do I stop it?
Margin collapsing happens when vertical margins of adjacent block elements combine into a single margin. To prevent it, use `display: flex` or `display: grid` on the parent, or add a `padding` or `border` to the parent.
Why is my percentage height not working?
Percentage height requires the parent to have an explicit height. If the parent's height is `auto` (the default), the child's percentage height resolves to `auto`. Set a height on the parent or use `min-height` with `height: 100%`.