Debugging CSS

Practices and techniques for debugging traditional programming languages, like C or JavaScript, have developed and matured over the last half century or more.

But CSS, as any developer who’s even moderately familiar with the language will know, is very different from such languages.

Even spotting, let alone tracking down the cause of incorrectly styled content can be maddening. And managing the interaction of potentially numerous rules spread throughout a style sheet, or across multiple style sheets, or the cascade and inheritance of a property and its impact on an element’s style causes frustration even for very experienced CSS developers.

In this presentation designer and developer Ahmad Shaheed asks why hasn’t a systematic body of debugging practice emerged for CSS? And what might that look like?

Debugging CSS

Ahmad Shadeed, UX Designer • Front End Developer

Software developers spend 35-50% of their time validating and debugging software… which costs about $100b each year!

So what is debugging? The process of finding and solving issues in software, that are preventing the user from doing something.

How has CSS debugging changed over time? In 1998: Style Master appeared, letting us debug the CSS on a website; and in 2006 the Firebug extension arrived which was a huge milestone.

In 2020 we have lots of tooling options, but we also have a huge amount of devices to test and web projects can be huge.

Why teach debugging?

Debugging reduces the time devs spend on issues, but the fast development of browser DevTools can be overwhelming for newcomers.

Learning resources can make it less confusing.

How to define a CSS bug? This is when the developer has made an error in their CSS, not a browser bug. It could be a mis-alinged element, horizontal scrollbar or clipped padding… things like that.

There are lots of ways to test web pages:

  • Browser devtools
  • Mobile devices
  • Emulators
  • Virtual machiens
  • Online


  • We trigger this with the contextual Inspect menu
  • Device modes to emulate mobiles, tablets, etc – but it’s not 100% reliable
  • Scroll into view feature is very useful for testing small screens

Media queries can be particularly tricky to debug. Their order is important (their effect can be overridden by selectors further along) but this may not be obvious in the dev tools – try setting a background colour. It’s an old trick, but it checks out!

Also classic fixes like clearing cache and checking links still apply.

Beware of the double breakpoint bug, where two media queries set to the same value try to hide content. At that exact pixel value, neither will be visible, so offset your value by 1px.

To debug an element that is being added and removed by JavaScript is helped by watching where the DevTools flash (to show changes). You can also use the contextual Break on menu to pause JS execution when the DOM mutates.

Debugging common CSS issues…

  • Vertical padding won’t work with inline elements (fix by setting them to inline-block)
  • Space below images can be removed by setting images to display:block
  • Beware of inline CSS overriding the intended styles
  • Margin collapse catches a lot of people out – this is where the larger of two margins between elements ‘wins’ and both collapse to that size
  • Just In Case Margin – this is where you set a margin even when your test case didn’t need it, but larger content would cause content to collide
  • Don’t rely on min-width alone, add horizontal padding as well
  • Elements floating above siblings – check for z-index
  • Transparent keyword can show a dark colour in gradients – set the colour you actually want instead
  • `background` size must be included immediately after position
  • Amend transforms if setting multiple effects, to avoid overriding the earlier effects

Horizontal scrolling is a section to itself…

  • Use the Firefox ‘scroll’ label to debug this
  • Check for absolutely positioned elements with large negative values
  • Ensure all wide layout like grid containers is set behind media queries
  • Use overflow-wrap:break-word on small screens to stop long words and URLs triggering scrollbars
  • Beware the difference between overflow:scroll and overflow:auto
  • Don’t forget to use flex-wrap:wrap
  • Don’t depend on space-between for the spacing between columns

There are lots of ways you can break a layout with CSS

  • Revealing more content or switching languages
  • Forgetting the in-between sizes while resizing windows
  • Developing with ideal placeholder images that mask things like contrast problems