CSS is hard no matter how good you are at it

Let us start by saying that CSS is hard. It seems that no matter how skilled you get, you will still run into situations that completely baffle you. Sometimes you can hack around the situation, but other times you really need to figure it out. When you need to dig in, having a helpful team and bringing things down to first principles are the order of the day.

I ran into this situation when refreshing pivot reports at Aha! to include aesthetically pleasing user avatar pills instead of plain text.

This is what we started with:

And this is what we wanted to build:

We had just updated the product value score to use pills in a similar manner, so I figured this change would go smoothly. This was my initial result:

As you can see, the user pill does not vertically align with the rest of the content on the row. Vertical alignment can be annoying — I get it. I figured this was just some rogue styling getting in the way of what should have otherwise been a simple alignment. I banged my head against this for quite a while before admitting I had no idea what was going on. Normally after that level of frustration, I would have just added margin-top: 1px to the new user avatar pill and called it a day. This component was being built for use in our design system, so it had to work in all situations. A hacky margin fix would cause issues in other situations.

I work with a team that has accumulated a lot of CSS experience. Generally I don't think there is anything they cannot handle. So I jumped on a couple calls to work through the issue. They were just as confused as I was. The page in question had a lot of moving parts. We have a lot of stylesheets, a design system, an old design system, and a rather deep DOM structure — all affecting this one location. We needed to step out of this complex environment.

The best way forward was to create a sandbox and start paring this problem down to the simplest use case possible. We were quickly able to get it working with various different methods, but none of those were compatible with the exact use case in the application. Whenever we reproduced the most basic example of how we were going to use it, we had the issue.

What really baffled me was that the Aha! product value score pills worked fine and they were basically the same thing. So I recreated the product value score situation and it worked.

The major difference between the two is that the product value score uses an icon while the avatar pill uses an image. I replaced the "icon" span and replaced it with an img tag. The problem occurred.

I knew I was close at that point. So then I pared the HTML down to just this:

<span class="pill"> Pill 1 </span>

<span class="pill">
  <span class="wrapper">
    <span></span>
    <span>Pill 2</span>
  </span>
</span>

After some more fiddling, I determined that an empty first child of a flex container will cause that flex container to vertically misalign with its other flex container siblings. In my user avatar pill case, the first child is an image that technically has no content. The person I was pairing with had the idea to add a zero width space with a CSS rule, something that would be simple and unobtrusive:

.wrapper::before {
  content: '\200B';
}

That fixed the problem!

I tested this on all major browsers and they all had the same issue. Needless to say, I was pretty confused by this outcome. I could have pored over the w3 documentation to try and figure out why this was occurring, but it was not worth the extra effort given the problem had a simple solution that worked well.

I think this story is a good example of how CSS can be hard, and no matter how experienced your team is, you will still run into really difficult situations. You should be able to solve your problem if you approach it in a methodically structured way using the following tools:

1. Set a time box to ensure you do not waste too much time fighting the problem at any step in your problem-solving. When you hit the time box, switch approaches.
2. Grab a partner. Sometimes a more experienced CSS developer can help you solve the problem. Sometimes all you need is a fresh set of eyes. Often pulling in one partner will help you get past one hurdle, and then you have to pull in another to get even further.
3. Create a sandbox example. Build up the most basic use case you can. Then iterate on it until you have the final solution that you can slot into your actual use case.

Other developers at Aha! have run into this same situation elsewhere in our app. We have a simple solution that works, but still do not fully understand why browsers would choose this behavior. If you know the reason or have a different solution, we would love to hear from you. Apply for a position and tell us all about it.