| name | frontend-debugging |
| description | Use when debugging a CSS layouts, box-model mismatch, or DOM structure problem that keeps breaking under CSS tweaks. |
| license | CC-BY-NC-4.0 |
Structural CSS Debugging
Overview
Think in boxes, not classes. Most layout bugs are structural: the DOM is split wrong, a wrapper is redundant, or transient state is fighting normal flow.
Core principle: give the browser the correct DOM first; only then tune CSS.
When to Use
- A CSS layout bug keeps coming back after tweaks
- The DOM structure looks suspicious or over-wrapped
- You need to decide whether to change markup or styling first
- Visual inspection shows symptoms but not the root cause
Do not use this skill to keep retrying visual-only CSS changes.
Core Pattern
Before changing CSS, answer:
- What boxes does the browser think exist here?
- Which box boundary is causing the bug?
- Is this boundary necessary, or is it redundant?
- Should this content really be split into multiple elements at all?
The common failure modes are:
- an extra wrapper makes the browser create the wrong boxes
- two pieces that should flow together were split into separate elements
- transient UI state was left in normal document flow
- a utility-class pile is hiding the structural bug instead of fixing it
Prefer the smallest structural fix:
- remove a wrapper
- merge two nodes into one flow
- move overlays deeper
- let the semantic element own the interaction
If you are tempted to add nowrap, inline-flex, grid, or more wrappers, pause and re-check the DOM first.
Quick Reference
- Read the actual DOM, not just JSX.
- Check browser rules for inline flow, wrapping, sizing, and positioning.
- Change structure first, then simplify CSS.
- If stuck, ask for raw HTML and computed styles.
Useful browser concepts to search when needed:
- inline formatting context
- whitespace handling
- line breaking
- flex item sizing
- inline-block behavior
- absolute positioning
Common Mistakes
- Tweaking classes repeatedly to “try one more thing”
- Using stronger CSS to glue broken structure together
- Reaching for visual tools before checking the DOM
- Assuming the first layout theory is correct
- Focusing on the symptom instead of the box boundary that causes it
Implementation
- Inspect raw HTML, nesting, and text-node boundaries.
- Search official docs or MDN for the underlying layout model.
- If the issue remains unclear, ask for computed
display, white-space, and position values.
Look for a fix that changes structure before style:
- remove a wrapper
- merge siblings that should behave as one unit
- move overlays inside the element that owns the text
- move style responsibility to the element with the right semantics
Common Questions
- Which boundary is wrong?
- Does the whole unit fail to wrap, or do two parts split apart?
- What does the raw HTML look like?
- What are the computed
display, white-space, and position values?
When Stuck
If the issue persists after a few structural attempts, stop and gather evidence:
- Ask for raw HTML.
- Ask for computed styles.
- Ask which boundary is actually wrong.
- Search for a similar working pattern in the codebase.
Do not keep editing blindly once the DOM picture is unclear.