A Practical Guide to CSS Container Queries

For a long time I treated container queries as something to worry about later. Then a small change to our Storybook setup turned into a week of debugging, and "later" arrived all at once.

When we finally measured, the numbers were worse than anyone guessed. Around 33% of the time spent on a typical change went into working around container queries rather than building anything.

How we got here

The setup was ordinary: Storybook at the edges, Playwright doing most of the heavy lifting, and a handful of scripts nobody wanted to own. It worked well until usage roughly doubled over a single quarter.

We had good intentions. We even had a document describing how container queries should work. The trouble was that the document and the code had quietly gone their separate ways.

The fix

We started by writing down the one rule we actually cared about, then deleted every bit of code that didn't serve it. It's not glamorous, but it works.

Here's a trimmed-down version of what we ended up with:

.card-list {
  container-type: inline-size;
}

@container (min-width: 36rem) {
  .card {
    display: grid;
    grid-template-columns: 12rem 1fr;
    gap: 1.5rem;
  }
}

It's tempting to generalize this into a library. Resist that urge until you've needed it in at least three places.

A few things that helped along the way:

• Measure before and after, even if it's just a rough number in a spreadsheet.
• Agree on what "done" means before the first pull request.
• Keep the old path around until the new one has survived a real incident.

Where this breaks down

We still haven't solved accessibility. That's a post for another day, and honestly, I'm not sure we'll get it right the first time either.

There are cases where this falls apart. If your team is very small or your traffic is very spiky, the extra moving parts may not pay for themselves.

Wrapping up

I don't think there's a universal answer here, but I hope this gives you a few ideas to try on your own project. If you do, I'd love to hear how it goes.