When something breaks, this is your one-stop page. Start with the workflow to identify the type of problem, then jump to the relevant section for specific fixes.
What is broken?
→ structure?
→ spacing?
→ alignment?
→ image?
→ responsive layout?
Where is it broken?
→ one section?
→ whole page?
When is it broken?
→ desktop?
→ tablet?
→ mobile?
Check the parent container first
Check direction before alignment
Check container size before blaming the content
1. Identify the problem
2. Inspect the element
3. Check the parent
4. Check the box model
5. Check width / height
6. Check layout method
7. Check breakpoint
8. Re-test
Do not guess randomly
Change one thing
Observe it
Then decide the next move
DevTools shows what the browser is actually doing. Use it to inspect the box model, element size, and parent-child relationship.
Before rewriting layout rules, check whether headings, paragraphs, or lists have default margin or padding.
Do not assume the media query is wrong. The base layout may already be too demanding before the breakpoint.
DevTools allow you to inspect elements, test CSS changes, view console errors, and monitor network requests. They are essential for debugging any website.
DevTools = what the browser is actually doing
Check:
HTML
CSS rules
Box model
Computed values
Screen size
| Panel | Description | Use Case |
|---|---|---|
| Elements | Shows the HTML structure and applied CSS. | Inspect layout issues or missing tags. |
| Styles | Displays CSS rules and allows live editing. | Test CSS changes instantly. |
| Console | Shows errors, warnings, and logs. | Identify JavaScript or loading errors. |
| Network | Monitors file requests and load times. | Check for missing files or slow assets. |
| Device Toolbar | Simulates different screen sizes. | Test responsive layouts. |
HTML errors often cause layout problems, broken links, or missing content. These issues are usually easy to spot with DevTools.
HTML first
If structure is wrong
CSS cannot fix it properly
| Issue | Description | Fix |
|---|---|---|
| Missing closing tags | Unclosed elements break layout structure. | Ensure all tags are properly closed. |
| Incorrect nesting | Elements placed inside invalid parents. | Follow proper HTML hierarchy. |
| Broken links | Incorrect file paths or missing files. | Check relative paths and filenames. |
| Missing alt text | Images lack accessibility descriptions. | Add descriptive alt attributes. |
Check:
- correct element?
- correct parent?
- correct class?
- correct closing tag?
CSS bugs often relate to layout, spacing, or unexpected behaviour caused by specificity or inheritance.
CSS debugging order
1. Is the rule applied?
2. Is it overridden?
3. Is the selector correct?
4. Is the parent controlling this?
5. Is the size causing the issue?
| Issue | Description | Fix |
|---|---|---|
| Specificity conflicts | Styles overridden by more specific selectors. | Use DevTools to check applied rules. |
| Unexpected margins | Margin collapse or inherited spacing. | Inspect box model in DevTools. |
| Overflow issues | Content spills outside containers. | Use overflow: hidden or adjust width. |
| Incorrect units | Using px instead of %, rem, or vw. | Use responsive units where appropriate. |
If the CSS "does nothing"
→ wrong selector
→ overridden rule
→ wrong element
→ wrong parent
ROW:
[ item ][ item ][ item ]
main axis → left ↔ right
cross axis → top ↕ bottom
COLUMN:
[ item ]
[ item ]
[ item ]
main axis → top ↕ bottom
cross axis → left ↔ right
Cause: Wrong flex-direction.
Fix: Check direction first, then alignment.
Wrong:
child has flex
[parent]
[child]
Right:
parent has flex
[parent flex]
[child][child]
Cause: Flex applied to the wrong element.
Fix: Flexbox controls direct children, so apply it to the parent.
Wanted: Getting:
[ item ] [ item ][ item ][ item ]
[ item ]
[ item ]
Cause: Still using row.
Fix: Switch to column.
Bad: item + margin hacks + uneven spacing
Better: parent uses gap
Fix:
Use
gap
for flex items.
+-------------------------+
| margin |
| +-------------------+ |
| | padding | |
| | +-------------+ | |
| | | content | | |
| | +-------------+ | |
| +-------------------+ |
+-------------------------+
padding = inside
margin = outside
Fix: Add margin between sections, not random margins on many children.
Fix: Add padding to the container.
parent
|
child margin-top
Sometimes margins collapse
Fix: Use padding on the parent if needed.
Wrong: Result:
width forced image distorts
height forced
Cause: Width and height both forced.
Fix: Control one dimension and let the other adjust.
background-size: cover;
background-position: center;
background-repeat: no-repeat;
Fix: Use all three together for most decorative backgrounds.
Check:
- container size
- crop area
- aspect ratio
Cause: Often the container shape, not the image file.
Fix: Check the container first.
Container: Overflow:
+------------------+ +------------------+
| content content | | content content |
| content content | | content content |---->
+------------------+ +------------------+
Common causes:
- fixed width too large
- image too wide
- long unbroken text
- child wider than parent
Fix: Check widths first.
Page width = screen width
But one child is wider
So page scrolls sideways
Fix: Find the element wider than the viewport.
Ask:
- is the parent too small?
- is the child too wide?
- is width fixed when it should be flexible?
Fix: Adjust the container/child relationship instead of hiding the issue first.
Normal flow: Absolute:
[ header ] element removed from flow
[ section ]
[ footer ]
Cause: Absolute positioning used for layout.
Fix: Use flexbox or grid for layout. Use absolute for decoration or special UI cases.
absolute element
looks for nearest positioned ancestor
Fix: Check which parent is positioned.
z-index alone ≠ enough
position usually needed first
Fix: Check whether the element is positioned.
Fix: Use small, meaningful stacking levels instead of huge random numbers.
Responsive issues occur when layouts break at certain screen sizes. DevTools make it easier to test breakpoints and inspect how elements behave across devices.
Desktop works
Tablet awkward
Mobile broken
This usually means:
the middle size needs a layout decision
| Problem | Description | Fix |
|---|---|---|
| Broken at breakpoint | Styles not applying correctly at a screen size. | Check media query syntax and screen width. |
| Content overflow | Items too wide for the screen. | Use flexible widths and wrapping. |
| Text too small/large | Typography does not scale well. | Use rem, clamp(), or viewport-based units. |
| Images break layout | Images don't resize correctly. | Set max-width: 100% and height: auto. |
Desktop: [ card ][ card ][ card ]
Tablet: [ card ][ card ]
Mobile: [ card ]
Decide what should stack, wrap, or shrink at each size.
When debugging: check the exact width where it breaks,
not just "desktop vs mobile".
Check whether the element is already a full-width block element. If it fills the row, centring the box may show no visible change.
text-align: center;
Check default browser styles before changing layout rules.
Use
align-self
on that child. This overrides the parent's cross-axis alignment for one
item only.
A wrapper can limit the available space, but the image still needs its own sizing rule. Use the wrapper to control the block width, and the image rule to make the image respect the wrapper.
The real breakpoint is where the layout actually stops fitting, not the number you guessed first.
One container should not do two jobs. If a section contains a heading and repeated cards, place the cards inside their own wrapper and apply the row layout to that wrapper.
If it looks wrong:
→ inspect it in DevTools
If it won't move:
→ check the parent
Layout looks wrong?
→ Are items side by side or stacked?
→ If wrong → check direction
Spacing feels wrong?
→ check margin / padding / gap
Something won't move?
→ Flex must be on the parent
Image looks wrong?
→ Check the container first
Content breaking layout?
→ Something is too wide
Page scrolling sideways?
→ One element is wider than the screen
If it breaks on resize:
→ check the exact breakpoint width
If CSS does nothing:
→ check selector, specificity, and rule order
Nothing makes sense?
→ structure first → CSS second → parent → direction → size