Responsive bugs often hide between the breakpoints teams remember to test. The layout works at 375, 768, and 1440 pixels, then fails in a 520-pixel card rail or a 980-pixel split pane.
That is a sign the breakpoint may be attached to the wrong thing.
A viewport breakpoint describes the window. Most component failures happen inside something smaller and more specific: a sidebar, a modal, a dashboard panel, a marketing card, or a documentation column. If the component is reused across those contexts, it can have three different available widths at the same viewport size. Adding another global media query may hide the problem in one route and create a new exception in another.
The debugging goal is to identify the width that actually matters. Sometimes it is still the viewport because the whole page shell changes. Often it is the component’s containing block. Until you know which one owns the decision, every breakpoint is a guess.
Step 1: Resize slowly
Do not test only device presets. Drag the viewport or container slowly and watch where the layout first becomes awkward. Note the content width at the failure, not just the viewport width.
Look for the first failure, not the most dramatic failure. The first cramped label, awkward wrap, clipped badge, or squeezed control tells you which relationship broke. Once the layout is badly broken, many symptoms overlap and the fix becomes harder to reason about.
Record the component width if DevTools shows it. If a card starts to fail at 31rem, that is more useful than knowing the viewport was 900px. The same card may appear in a two-column layout, a three-column layout, or a sidebar. A component-level measurement travels with the component; a viewport measurement only travels with one page.
Step 2: Inspect the failing component width
A card inside a sidebar may have 280 pixels of inline space on a 1440-pixel desktop. A viewport media query cannot describe that local constraint.
If the component should change based on its own width, use a container query.
.rail-item {
container-type: inline-size;
}
@container (min-width: 28rem) {
.teaser {
grid-template-columns: 10rem minmax(0, 1fr);
}
}Step 3: Remove fixed assumptions
Look for fixed widths, unwrapped labels, and grid tracks that cannot shrink. A breakpoint may appear to fix the bug only because it moves the layout before the fixed assumption becomes visible.
Fixed assumptions are not always written as width: 320px. They can be a min-width on a child, a button group that never wraps, a heading that uses white-space: nowrap, a grid with three columns that never reduces, or a card image that has a fixed block size but an unconstrained caption. The component may be perfectly responsive until one nested item refuses to participate.
Before adding a query, ask whether the base layout can become more fluid. A grid track written as minmax(16rem, 1fr) may only need a lower minimum. A flex row may need flex-wrap: wrap. A text column may need min-inline-size: 0. If the base rule is too rigid, queries become a pile of rescue operations.
Step 4: Test real states
Responsive behavior must survive:
- Long headings.
- Optional badges.
- Empty states.
- Loading text.
- Validation errors.
- Translated labels.
If a breakpoint works only with perfect content, it is not a reliable breakpoint.
State matters as much as width. A search input may fit until the clear button appears. A product card may fit until the discount badge is present. A filter row may fit until a user selects several chips. Test the component with the combinations the product actually renders, not only the default storybook state or shortest editorial copy.
Reduced motion and zoom can expose related problems. At 200% zoom, a desktop viewport may behave like a narrow component layout. If controls rely on exact inline alignment, zoom will reveal whether they can reflow without overlap. This is not a separate accessibility chore; it is a direct test of whether the layout is tied to pixels or to content relationships.
Decide which query owns the change
Use viewport media queries for page-level structure: the primary navigation mode, whether the page has a sidebar, global spacing rhythm, print behavior, and large layout regions. Use container queries when a reusable component changes its internal layout based on the space it receives. Use no query at all when normal flow, wrapping, or intrinsic sizing can solve the problem.
That split keeps CSS easier to maintain. A product card should not need to know that the application has a lg breakpoint. A page shell should not need to know that a card’s media object becomes stacked below 28rem. Each rule belongs to the layer that owns the decision.
Use fewer, better breakpoints
Global breakpoints should describe page-level structure. Component breakpoints should describe component space. Mixing those responsibilities is how responsive CSS becomes a pile of exceptions.