The Term "Headless Component" is a Misnomer

You've likely heard the term "headless component" tossed around. The idea is you get solid, accessible components without any styles. A clean slate to style from scratch! But the structure (bones) and logic (head) are there. You're mostly adding styles.

They should be called "skinless components."

And the thing about headless components is that, in my experience, people actually don't want to start from scratch. It's much, much easier to start with sensible base styles and customize from there.

This is exactly what CSS was designed to do.

Libraries such as Shoelace makes this easy for you. Its default theme has opinions for the sake of ease and consistency, but you can override them at a high level (design tokens) and/or at a low level (components) to achieve the look you want without having to write all the styles yourself.

Even HTML elements aren't headless #

User agents ship a default stylesheet that controls the appearance of most elements. We sometimes "reset" them, which is another misnomer because we're usually just normalizing the defaults that vary between browsers.

But I digress…

I'm really happy that we're paying more attention to how things work and not just how they look. As web devs, we've come a long way, especially in terms of accessibility and performance, but we seem to go from one extreme to another.

It's OK when off the shelf components have opinions because it results in a lot less work!

But what's important is that those opinions can be easily changed to work for your needs, preferably through a common and familiar syntax like CSS.

Take it from someone who's built hundreds of components over the years. You rarely want to style third-party components 100% from scratch. There's too much room for error. There are too many details and edge cases you're not going to get right.

Default styles gives you a safety net #

Despite all that, headless components aren't bad! Any time you can avoid reinventing the wheel, you should. But if you want to spend more time building things and less time styling UI primitives, choose something that already has styles and sprinkle in your own customizations.

One thing I will caution you to look out for is what I call "Bootstrap syndrome." This occurs when you use a library's default styles with little to no customizations whatsoever. Your site ends up looking like every other site that uses Bootstrap as-is.

This phenomenon started when devs would pull in bootstrap.min.css from a CDN only to realize it wasn't easy to customize without Sass and a build step or a lot of CSS. So they didn't.

That problem has mostly been solved with CSS vars, but you still need to do the design work.

Another consideration is, when you're not doing things from scratch, you can start building right away and incrementally improve the design as you go. That sounds like a huge win to me.

Making a choice #

So you're left with:

  1. Roll components & styles from scratch (bespoke)
  2. Roll styles from scratch (headless)*
  3. Only customize the things you need (e.g. Shoelace)

There's an element of design involved no matter what, but only one option lets you start building right now.

*But Cory, [headless lib] has themes I can pick from! If you're going to go headless, this is how you should start. Pick a theme, preferably one that's very comprehensive, and start there. But keep in mind that third-party themes may be buggy or incomplete too!

This post was originally a Twitter thread.