DEV Community: Cory LaViska

Web Components Are Not the Future — They’re the Present

Cory LaViska — Fri, 27 Sep 2024 17:45:47 +0000

It’s disappointing that some of the most outspoken individuals against Web Components are framework maintainers. These individuals are, after all, in some of the best positions to provide valuable feedback. They have a lot of great ideas!

Alas, there’s little incentive for them because standards evolve independently and don’t necessarily align with framework opinions. How could they? Opinions are one of the things that make frameworks unique.

And therein lies the problem. If you’re convinced that your way is the best and only way, it’s natural to feel disenchanted when a decision is made that you don’t fully agree with.

This is my open response to Ryan Carniato’s post from yesterday called “Web Components Are Not the Future.”

WTF is a component anyway?

The word component is a loaded term, but I like to think of it in relation to interoperability. If I write a component in Framework A, I would like to be able to use it in Framework B, C, and D without having to rewrite it or include its entire framework.

I don’t think many will disagree with that objective.

We’re not there yet, but the road has been paved and instead of learning to drive on it, frameworks are building…different roads.

Ryan states:

If the sheer number of JavaScript frameworks is any indicator we are nowhere near reaching a consensus on how one should author components on the web. And even if we were a bit closer today we were nowhere near there a decade ago.

The thing is, we don’t need to agree on how to write components, we just need to agree on the underlying implementation, then you can use classes, hooks, or whatever flavor you want to create them.

Turns out, we have a very well-known, ubiquitous technology that we’ve chosen to do this with: HTML.

But it also can have a negative effect. If too many assumptions are made it becomes harder to explore alternative space because everything gravitates around the establishment. What is more established than a web standard that can never change?

If the concern is premature standardization, well, it’s a bit late for that. So let’s figure out how to get from where we are now to where we want to be. The solution isn’t to start over at the specification level, it’s to rethink how front end frameworks engage with current and emerging standards and work to improve them.

Respectfully, it’s time to stop complaining, move on, and fix the things folks perceive as suboptimal.

The definition of component

That said, we also need to realize that Web Components aren’t a 1:1 replacement for framework components. They’re tangentially related things, and I think a lot of confusion stems from this. We should really fix the definition of component.

So the fundamental problem with Web Components is that they are built on Custom Elements. Elements !== Components. More specifically, Elements are a subset of Components. One could argue that every Element could be a Component but not all Components are Elements.

To be fair, I’ve never really liked the term “Web Components” because it competes with the concept of framework components, but that’s what caught on and that's what most people are familiar with these days.

Alas, there is a very important distinction here. Sure, a button and a text field can be components, but there are other types. For example, many frameworks support a concept of renderless components that exist in your code, but not in the final HTML. You can’t do that with Web Components, because every custom element results in an actual DOM element. (FWIW I don’t think this is a bad thing — but I digress…)

As to why Web components don’t do all the things framework components do, that’s because they’re a lower level implementation of an interoperable element. They’re not trying to do everything framework components do. That’s what frameworks are for.

It’s ok to be shiny

In fact, this is where frameworks excel. They let you go above and beyond what the platform can do on its own. I fully support this trial-and-error way of doing things.

After all, it’s fun to explore new ideas and live on the bleeding edge. We got a lot of cool stuff from doing that. We got document.querySelector() from jQuery. CSS Custom Properties were inspired by Sass. Tagged template literals were inspired by JSX. Soon we’re getting signals from Preact.

And from all the component-based frameworks that came before them, we got Web Components: custom HTML elements that can be authored in many different ways (because we know people like choices) and are fully interoperable (if frameworks and metaframeworks would continue to move towards the standard instead of protecting their own).

Frameworks are a testbed for new ideas that may or may not work out. We all need to be OK with that. Even framework authors. Especially framework authors. More importantly, we all need to stop being salty when our way isn’t what makes it into the browser.

There will always be a better way to do something, but none of us have the foresight to know what a perfect solution looks like right now. Hindsight is 20/20. As humans, we’re constantly striving to make things better. We’re really good at it, by the way. But we must have the discipline to reach various checkpoints to pause, reflect, and gather feedback before continuing.

Even the cheapest cars on the road today will outperform the Model T in every way. I’m sure Ford could have made the original Model T way better if they had spent another decade working on it, but do you know what made the next version even better than 10 more years? The feedback they got from actual users who bought them, sat in them, and drove them around on actual roads.

Web Standards offer a promise of stability and we need to move forward to improve them together. Using one’s influence to rally users against the very platform you’ve built your success on is damaging to both the platform and the community.

We need these incredible minds to be less divisive and more collaborative.

The right direction

Imagine if we applied the same arguments against HTML early on. What if we never standardized it at all? Would the Web be a better place if every site required a specific browser? (Narrator: it wasn't.) Would it be better if every site was Flash or a Java applet? (Remember Silverlight? lol)

Sure, there are often better alternatives for every use case, but we have to pick something that works for the majority, then we can iterate on it. Web Components are a huge step in the direction of standardization and we should all be excited about that.

But the Web Component implementation isn’t compatible with existing frameworks, and therein lies an existential problem.

Web Components are a threat to the peaceful, proprietary way of life for frameworks that have amassed millions of users — the majority of web developers. Because opinions vary so wildly, when a new standard emerges frameworks can’t often adapt to them without breaking changes. And breaking changes can be detrimental to a user base.

Have you spotted the issue? You can’t possibly champion Web Standards when you’ve built a non-standard thing that will break if you align with the emerging standard. It’s easier to oppose the threat than to adapt to it.

And of course Web Components don’t do everything a framework does. How can the platform possibly add all the features every framework added last week? That would be absolutely reckless.

And no, the platform doesn’t move as fast as your framework and that’s sometimes painful. But it’s by design. This process is what gives us APIs that continue to work for decades.

As users, we need to get over this hurdle and start thinking about how frameworks can adapt to current standards and how to evolve them as new ones emerge. Let’s identify shortcomings in the spec and work together to improve the ecosystem instead of arguing about who’s shit smells worse.

Reinventing the wheel isn’t the answer. Lock-in isn’t the answer.

This is why I believe that the next generation of frameworks will converge on custom elements as an interoperable component model, enhance that model by sprinkling in awesome features of their own, and focus more on flavors (class-based, functional, signals, etc.) and higher level functionality. As for today's frameworks? How they adapt will determine how relevant they remain.

Living dangerously

Ryan concludes:

So in a sense there are nothing wrong with Web Components as they are only able to be what they are. It's the promise that they are something that they aren't which is so dangerous. The way their existence warps everything around them that puts the whole web at risk. It's a price everyone has to pay.

So Web Components aren’t the specific vision you had for components. That's fine. But that's how it is.

They're not Solid components. They’re not React components. They’re not Svelte components. They’re not Vue components. They’re standards-based Web Components that work in all of the above. And they could work even better in all of the above if all of the above were interested in advancing the platform instead of locking users in.

I’m not a conspiracy theorist, but I find interesting the number of people who are and have been sponsored and/or hired by for-profit companies whose platforms rely heavily on said frameworks. Do you think it’s in their best interest to follow Web Standards if that means making their service less relevant and less lucrative? Of course not.

If you’ve built an empire on top of something, there’s absolutely zero incentive to tear it down for the betterment of humanity. That’s not how capitalism works. It’s far more profitable to lock users in and keep them paying. But you know what…?

Web Standards don't give a fuck about monetization.

Longevity supersedes ingenuity

The last thing I’d like to talk about is this line here.

Web Components possibly pose the biggest risk to the future of the web that I can see.

Of course, this is from the perspective of a framework author, not from the people actually shipping and maintaining software built using these frameworks. And the people actually shipping software are the majority, but that’s not prestigious so they rarely get the high follower counts.

The people actually shipping software are tired of framework churn. They're tired of shit they wrote last month being outdated already. They want stability. They want to know that the stuff they build today will work tomorrow.

As history has proven, no framework can promise that.

You know what framework I want to use? I want a framework that aligns with the platform, not one that replaces it. I want a framework that values incremental innovation over user lock-in. I want a framework that says it's OK to break things if it means making the Web a better place for everyone. Yes, that comes at a cost, but almost every good investment does, and I would argue that cost will be less expensive than learning a new framework and rebuilding buttons for the umpteenth time.

The Web platform may not be perfect, but it continuously gets better. I don’t think frameworks are bad but, as a community, we need to recognize that a fundamental piece of the platform has changed and it's time to embrace the interoperable component model that Web Component APIs have given us…even if that means breaking things to get there.

The component war is over.

How to File a Bug Report

Cory LaViska — Tue, 21 Nov 2023 16:15:30 +0000

They say there's no such thing as bug-free code. When problems arise, creating a minimal reproduction will give you the best chance of a speedy resolution.

When a potential bug is discovered, many developers' first reaction is to file an issue. That's great, but please exercise due diligence before posting! Have you reviewed the docs to confirm the behavior in question? Are you able to reproduce the bug outside of your app? Have you removed all unrelated code to make sure nothing else is causing the problem?

I get it — creating a reproduction takes time! Why should that be on you if the bug is upstream? The thing is, the process of creating a minimal reproduction will often uncover the problem and, in many cases, the problem will be in your own code. I know that sounds arrogant but, as an open source maintainer, I see it happen quite frequently.

Help Us Help You

That's not to say our libraries don't have bugs…they totally do! We're just asking you to help diagnose the problem before we spend hours diving into your code only to realize it's not something we can fix in our code.

If you're using our software, we've already provided some kind of value to you. It's not fair to ask us to troubleshoot your app. Maintainers generally want to eliminate bugs from their software, but triaging issues can be a painstaking task, especially in larger projects.

Even if your bug report is completely valid, an issue that lacks sufficient information — or has too much of the wrong information — can easily fly under the radar for many reasons.

Think of it from a maintainer's perspective. You wake up in the morning to three new bug reports:

Bug #1 – doesn't have enough information, just a screenshot of the suspected problem and a line of text that vaguely describes it.
Bug #2 – has multiple screenshots of CI output and VS Code windows, but nothing else.
Bug #3 – has a clear description of the problem and a minimal reproduction. The submitter has thoughtfully included all relevant information pertaining to the issue.

Which one would you be most willing to resolve first?

Better Bug Reports

Here are some tips to help you get results faster. Investing a bit of time up front will usually lead to a more positive result. After all, there's nothing worse than watching your issue collect dust.*

Do

Be courteous and responsive
Search for existing issues
Provide all the information necessary to reproduce the problem
Provide a minimal reproduction when it makes sense
Taper your expectations — many maintainers do this for free!

Don't

Include information that doesn't pertain to the bug
Include multiple bug reports in the same issue
Be rude to maintainers or anyone else involved
Spam the maintainers with follow ups
Point fingers or blame others — it's just not productive

Just for Fun

In case you were wondering, here's how maintainers tend to feel when various bug reports are filed. 🤣

*Unfortunately, some maintainers are simply unresponsive. In my experience, the majority of open source authors care about their projects and want to be good stewards. Sometimes it can help to offer a bounty or, better yet, a PR. Alas, I've seen really good PRs collect dust too. In that case, you might need to consider forking the project or finding an alternative.

Custom Event Names and the Bubbling Problem

Cory LaViska — Mon, 12 Dec 2022 22:07:18 +0000

The topic of custom element event names comes up every now and then, especially from Shoelace users who get confused when events of the same name are emitted from different components.

Take <sl-details>, <sl-dialog>, and <sl-dropdown>, for example. They all emit sl-show and sl-hide events, allowing you to hook into their lifecycle as they open and close. Occasionally, someone will nest a component inside another, listen for an event such as sl-hide, and wonder why the callback executes at the "wrong time."

In this example, you can see that we have an <sl-dropdown> inside of an <sl-dialog>. Both of these components emit sl-show and sl-hide events.

<sl-dialog label="Dialog">
  <!-- Note how the dropdown is nested inside the dialog -->
  <sl-dropdown>
    <sl-button slot="trigger" caret>Open and close me</sl-button>
    <sl-menu>
      <sl-menu-item>Option 1</sl-menu-item>
      <sl-menu-item>Option 2</sl-menu-item>
      <sl-menu-item>Option 3</sl-menu-item>
    </sl-menu>
  </sl-dropdown>
</sl-dialog>

<sl-button id="open">Open Dialog</sl-button>

<script>
  const dialog = document.querySelector('sl-dialog');
  const openButton = document.getElementById('open');

  // Show the dialog when the button is clicked
  openButton.addEventListener('click', () => dialog.show());

  // Listen for the sl-show event
  dialog.addEventListener('sl-show', event => {
    console.log('The dialog has opened…or has it?')
  });

  // Listen for the sl-hide event
  dialog.addEventListener('sl-hide', event => {
    console.log('The dialog has closed…or has it?')
  });
</script>

Try it on CodePen

The logic above is faulty because it runs when the dialog or any of the dialog's children emit the sl-show or sl-hide event. This occurs due to event bubbling, which is an incredibly useful feature of the platform. When events bubble up, listeners on ancestor elements will execute. This enables an extremely useful feature called event delegation.

Alas, this is also a source of confusion.

Fortunately, there are a couple easy ways to work around it.

Checking the Target

Events are emitted with a target property that you can inspect to determine which element emitted it. Thus, we can modify the handlers from the previous example to ensure the target is the same dialog we attached the listener to.

// Listen for the sl-show event
dialog.addEventListener('sl-show', event => {
  if (event.target === dialog) {
    console.log('The dialog has opened')
  }
});

// Listen for the sl-hide event
dialog.addEventListener('sl-hide', event => {
  if (event.target === dialog) {
    console.log('The dialog has closed')
  }
});

Try it on CodePen

Checking the Current Target

Another way is to compare Event.currentTarget, which effectively does the same thing.

// Listen for the sl-show event
dialog.addEventListener('sl-show', event => {
  if (event.target === event.currentTarget) {
    console.log('The dialog has opened')
  }
});

// Listen for the sl-hide event
dialog.addEventListener('sl-hide', event => {
  if (event.target === event.currentTarget) {
    console.log('The dialog has closed')
  }
});

Try it on CodePen

Checking the Event Phase

Here's another way to ensure the event was emitted by the expected element. It's a bit more verbose, but it doesn't require a reference. Instead, we can inspect Event.eventPhase to determine which phase the event is in. In this example, the listener is attached directly to the dialog, so we're interested in the AT_TARGET phase.

// Listen for the sl-show event
dialog.addEventListener('sl-show', event => {
  if (event.eventPhase === Event.AT_TARGET) {
    console.log('The dialog has opened')
  }
});

// Listen for the sl-hide event
dialog.addEventListener('sl-hide', event => {
  if (event.eventPhase === Event.AT_TARGET) {
    console.log('The dialog has closed')
  }
});

Try it on CodePen

Why Not Use Unique Event Names?

It has been proposed numerous times that custom elements should emit events with unique names to avoid such confusion. For example, instead of emitting sl-show for multiple components, event names might named be based on their tag, e.g. sl-dialog-show and sl-dropdown-show.

I appreciate the idea, but this just isn't how events works. If you click a <button> you get a click event, not a button-click event. If you set focus to an <input>, you get a focus event, not an input-focus event.

For the sake of consistency with the platform, I consider this suggestion an anti-pattern that should be avoided in custom elements. Instead, developers must understand that many events bubble — including native ones — and they should be doing these checks any time elements are nested to avoid unexpected behaviors.

This problem isn't exclusive to custom elements.

A Web Component Story

Cory LaViska — Fri, 30 Sep 2022 12:23:01 +0000

Gather 'round, it's story time.

A number of years ago, I was hired by a company to rebuild a component library for their design system. The one they were replacing was built with AngularJS, but AngularJS was old and rickety and nobody wanted to use it anymore. Plus, many teams had moved on to other frameworks and one team even preferred doing everything with vanilla JS.

But the company couldn't hire for AngularJS. There was no talent available. Devs had moved on. Nobody wanted to work with a "legacy framework."

So they had to build something new to get out of that ecosystem. They talked about building a new component library in modern Angular. Or maybe React. A handful of engineers wanted Vue.

But they knew that whatever framework they chose, they would be locking teams into it or forcing them to build their own components. This would mean duplicating effort and risking stylistic and behavioral deviations — an inevitable side effect of competing libraries.

They also knew that they'd be doing this again in a few years if they picked any of today's popular frameworks, so they decided to give Web Components a try.

So that's what we built, and that's what they still use to this day. It no longer matters if their teams want to build with React, Vue, Svelte, Solid, or whatever tomorrow brings.

Nobody is forced to use a specific framework
Nobody needs to reinvent UI primitives
Upgrading or switching frameworks is much easier
No duplicate efforts

At this point, you might be thinking "we only use React, so who cares?" And you can get away with that for awhile, especially if you're a single team or a small shop. I get it. React feels good and it's sticky. But all frameworks eventually fizzle out.

Thanks to Web Components, large companies are realizing you don't need to rebuild buttons and other UI primitives every few years. Teams don't need to argue about frameworks anymore. You can have your cake and eat it too!

It's already happening on a large scale at some of the largest companies in the world, but the impact isn't limited to big players — everyone can benefit from Web Components today.

To be clear, I'm not suggesting you throw out your framework and go all in on Web Components...Web Components are complementary to frameworks! In 2022, I strongly suggest building your design system with them. Knock out the UI primitives and patterns that all teams use and give devs the freedom to build with whatever framework(s) they want!

Any org that goes all in on a single framework will eventually find themselves swimming upstream to hire talent to maintain legacy code and avoid framework rot. But you can reduce this burden (and the associated costs) by using Web Components in your design system.

Remember that design systems aren't cheap. It takes a lot of time to redesign and rebuild dozens of components, so why keep doing it every few years? It costs too much and it prevents you from shipping faster.

Here's a quick case study from an open source UI library called Element UI. This is a very popular Vue 2 library, but breaking changes in Vue 3 meant the library no longer worked! They had to build and maintain a completely different version of the library, and now they maintain two separate versions — one for Vue 2 users and one for Vue 3 users. 🤦🏻‍♂️

This is what happens when you go all in on a framework for UI primitives. Imagine having to maintain multiple versions of your component library for each framework — and each major version — you want to support.

Thanks to Web Components, this it totally avoidable!

A common criticism I hear is that Web Components aren't perfect, to which I'll agree. No, they're not perfect. But they're pretty damn good, they're part of the standard, and we can collectively work to improve any shortcomings they might have.

I'll take platform-based interoperable components over framework churn any day of the week. ✌🏻

Shameless plug: you should take a look at Shoelace if you're looking for an awesome library of web components.

This post was originally a Twitter thread.

Buttons and Cursors

Cory LaViska — Wed, 27 Jul 2022 16:37:00 +0000

There's a post from 2016 entitled Buttons shouldn't have a hand cursor that's been making its way around social media this week. While the author is correct in his statement that operating system buttons don't have hand cursors, the pattern has become ubiquitous and somewhat expected on the Web.

Some of his points include:

When a button has the hand cursor, it subtly suggests that the user is interacting with a link when they’re not.

The hand cursor is reserved for links. This is because they are unique in their behaviour.

Links have always been handled this way since the web came along — this is the convention of the web that you need not innovate on.

Admittedly, most of my designs as of late do include cursor: pointer for buttons as well as other clickable, non-link controls. And while I don't have a strong opinion either way, revisiting that post triggered a thought about the psychology behind user interfaces.

Learned Behaviors

As a computer user, you undoubtedly know what radio buttons are and how they work. But how do you know that? Do you remember the very first time you used one? Probably not, but it's likely that your first experience created a pathway in your brain that said "I can only pick one of these" and that knowledge has been engrained ever since.

These are learned behaviors. A child who has never seen a radio button before might try to click on one to make a choice. Then they might click on another one to select a second choice. Quickly, the child will realize the limitations of a radio button: "I can only pick one."

That lesson remains with them until something challenges the pattern, and when such change occurs, they will dislike it because it doesn't feel correct to them. It's suddenly "unintuitive" because they've learned to expect certain behaviors, and anything unfamiliar will be called out as "poor design."

This is why radio buttons are almost always round and checkboxes are almost always square. Swapping something as simple as the shape of these controls will confuse users because it contradicts their learned behaviors.

How We Got Here

If users develop such intrinsic expectations for consistent UIs, then how did the proliferation of hand cursors on buttons even occur? A theory I have dates back to the "Web 2.0" trend where buttons got bigger, more colorful, and eventually a lot flatter. When buttons stopped looking like buttons, designers threw in a subtle way to more easily distinguish them by changing the cursor.

Plenty of users complained about flat design, but I believe the trend is directly related to why almost every button on the Web today has a "link cursor." It was a subtle enough change — an improvement, if you will — that made flatter controls more tolerable. Web designers slipped the pattern in and, while everyone was busy complaining about the lack of skeuomorphism and increasingly harder-to-identify buttons, nobody really noticed.

Now that nearly every clickable thing on the web seems to have a hand cursor, I'd argue that not doing it is the new anti-pattern, largely due to user expectations. The Web isn't an operating system and, despite the obvious inconsistency between operating system and Web interfaces, nobody seems to care.*

In some ways, I wonder if this hurts the web. Those of us who would love to see Web-based technologies compete more with native apps could easily argue that Web apps should behave the same way to make them as indistinguishable as possible, but I seldom hear about this particular inconsistency in the wild.

I wonder if anyone would even notice if we suddenly removed the hand cursor from all of our buttons. My guess is that few would, especially now that touch devices are more prominent for consumers. The handful of people who would notice are those that aren't browsing on iPhones and iPads, but "regular" computer users who, arguably, aren't so regular anymore.

*Admittedly, I don't have a strong preference here. I rarely think about it, although the thought does cross my mind from time to time. I tend to side with my users' expectations and, given the ubiquity of hand cursors on the Web, I'll continue to change the cursor on buttons until there's a good reason to stop.

Design Systems Aren't Cheap

Cory LaViska — Mon, 21 Mar 2022 14:54:00 +0000

Buttons are one of my favorite components. On the surface they seem simple, but in practice, they tend to be much more involved. In a post by Nathan Curtis entitled And you thought buttons were easy?, he demonstrates how costs can quickly skyrocket to $1,000,000 when one arm of the organization isn't aware of what the other is doing.

This is easy to brush off as an extreme example that only applies to really large companies. But how much does a design system actually cost?

A Real Life Example

Before joining Microsoft, I did a short stint at a company with more than 10,000 employees. I was on a dedicated design system team that included five engineers, four designers, and two design technologists. Over the course of 12 months, they had built about 30 components for their design system.

Many of those positions paid six figure salaries, and that doesn't account for benefits and HR costs. Let's pretend the average salary for each position was only $100K USD. That's 11 FTEs working for a year, totaling $1.1M in salaries. Again, this doesn't include stock grants, health insurance, and additional benefits.

All that to build buttons, dialogs, form controls, tabs — nothing proprietary. Just every day components that have been built many, many times before.

The Cost of Frameworks

I forgot to mention that the components they were building were for React, which means that only React teams can use them. As a result, either the entire company must agree to use React or non-React teams will have to duplicate effort by building the same thing in their framework, running the price up even higher.

In large orgs, these costs tend to fly under the radar, but they're tangible expenses if you know where to look.

Many design system teams I've spoken with are rebuilding or preparing to rebuild "legacy" design systems. The story usually goes something like "we're phasing out Angular 1.x" or "we're evolving from a Bootstrap-like design system."

And a lot of them want to build in React.

This leads to more costs that aren't being realized. Just like jQuery dominated the front end yesterday, React dominates it today. There will be something new that dominates it tomorrow. Your design system team will continue doing the same work and incurring more and more costs to keep up with framework churn. And let's not forget the cost of updating tomorrow's legacy apps, who are consumers of your soon to be legacy design system.

The Platform Outlives Frameworks

A modern design system's component library — the foundational elements from which all your apps are built — are excellent candidates for Web Components: a standard technology that's built into all modern browsers. Web components are used by some of the world's largest companies, including Adobe, Amazon, Apple, Ford, GM, Google, Microsoft, NASA, Salesforce, SpaceX, Visa, and many, many more.*

If you care about longevity and cost, the platform is simply a more logical choice because browsers have committed to supporting Web Components for a long time.

It's astonishing to me that so many engineers fail to see that doing the same work over and over again isn't productive nor cost effective. How many times do you have to rebuild a button before you think "maybe this isn't the best way forward?" Imagine how much more productive an organization could be if those design and engineering hours were spent elsewhere.

Now imagine if you didn't have to build all those portable UI primitives yourself. What if you could just apply some of your own styles and start building patterns and apps? 🤔

Jump Starting Your Design System

Every design system is different, but how much would you save if you could kick things off with a solid set of accessible, well-tested components? Imagine not spending $1,000,000 on buttons. Imagine jumping right in and building more useful components for your organization. Imagine telling your engineers to use whatever framework they want because it will work just fine with your design system.

That's one of the reasons I built Shoelace, an open source web component library that serves as a design system starter kit.**

Shoelace solves real world problems by offering accessible, intuitive, and interoperable components that save teams and individuals tens of thousands of dollars or more. It's totally free, by the way, although sponsorships are always welcome.

There's no need to roll your own buttons anymore.

*There's a longstanding misconception that Web Components aren't ready for mainstream consumption. This is a stale argument that held more water many years ago when the standards were less mature. These days, companies such as Adobe are embracing Web Standards by migrating flagship products to web components. Web components aren't just ready for mainstream — they are mainstream.

**One of my followers told me they didn't want to use a third-party library as a basis for their design system. I suggested they fork the project if they want to have complete control of it. Their reply was something like, "but then I have to maintain it myself!" That argument wasn't well thought out, because you'll still be maintaining it yourself if you build it from scratch!

CSS Parts Inspired by BEM

Cory LaViska — Thu, 10 Mar 2022 16:48:00 +0000

In a previous post, I explored valid names for CSS parts and discovered that there are very few restrictions in what you can call them. The purpose of that deep dive was to help identify a pattern for naming parts that lets me expose states and subparts, or parts exported as a result of composition.

Using inspiration from BEM, I've settled on a familiar and intuitive pattern that I'd like to share.

Blocks → Parts

In BEM terms, a block "encapsulates a standalone entity that is meaningful on its own." Block names consist only of Latin letters, numbers, and dashes. This translates well to CSS parts.

Consider the following custom element template. It's contrived, as its only purpose is to render an image.

<template>
  <!-- shadow root -->
  <img part="image" src="..." alt="...">
</template>

If we wanted to make a more descriptive name, we could have called the part user-provided-image or something, as long as we stick to letters, numbers, and dashes.

Elements → Subparts

In BEM, elements are "parts of a block [that] have no standalone meaning. Any element is semantically tied to its block." An example looks like this.

<div class="block">
  ...
  <span class="block__elem"></span>
</div>

Note the two underscores separating the block from the element. You might be wondering how this ties into CSS parts. Since parts are unique to the shadow root, we don't need to namespace them to prevent collisions. Two different custom elements can have two different parts with the same name and that's totally fine.

However, when a custom element is nested inside another custom element, it's often desirable to expose the nested element and its parts, otherwise, consumers won't be able to target it fully with ::part().* This means we need to expose the nested element with the part attribute and its parts with the exportparts attribute.

Let's evolve our example so it contains a nested a custom element called <my-image>, and let's assume that <my-image> has two parts called photo and caption.

<template>
  <!-- shadow root -->
  <my-image
    part="image"
    exportparts="
      photo:image__photo,
      caption:image__caption
    "
    src="..."
    alt="..."
  >
    ...
  <my-image>
</template>

You can see that I've exposed the host element for styling with part="image", which follows the "block" naming convention. Now take a look at the exportparts attribute. Conveniently, we can rename subparts when we export them. This lets us avoid collisions (e.g. what if the host element and the nested element have parts of the same name?).

In this example, the host element is exposed through the image part, and its photo and caption subparts are exposed as image__photo and image__caption, respectively. Notice how everything is scoped to the image block now?

End users can now use a very familiar syntax for targeting the nested element and all its parts in their CSS.

::part(image) {
  /* matches the nested <my-image> element */
}

::part(image__photo) {
  /* matches the subpart named photo in <my-image> */
}

::part(image__caption) {
  /* matches the subpart named caption in <my-image> */
}

It's not uncommon for custom element authors to neglect to export parts. At the time of this writing, exportparts seems to be one of the lesser known features of web components, but it's well-supported and incredibly powerful.

Anyways, this is feeling pretty good so far!

Modifiers → States

Element state is a pretty simple concept. If you have a button, it can have a hover state, a focus state, an active state, etc. Normally, we can target such states with CSS using pseudo selectors.

button:hover {
  /* targets the button's hover state */
}

This also works with parts, too.

::part(image):hover {
  /* targets the image part's hover state */
}

But not all states are available to target with pseudo selectors, and what if you want to add custom states? More often than not, custom element authors lean on host element attributes for this.

my-image[loaded] {
  /* targets the host element when the image has loaded successfully */
}

my-image[error] {
  /* targets the host element when the image fails to load */
}

While this works, mapping stateful parts to attributes on the host element isn't an elegant solution. Let's see how we can improve our example using stateful parts and a BEM-like syntax. In BEM, a modifier is used "to change appearance, behavior or state" and is delimited by two dashes.

Fortunately, parts are designed to work a lot like classes. In fact, they use the same DOMTokenList API as classList. This means elements can have more than one part, and part names can be reused throughout the custom element's template!

Evolving our example further, we can add modifier parts to indicate various states. Let's imagine the image in our example has loaded successfully. We can indicate this by adding the image--loaded part.

<template>
  <!-- shadow root -->
  <my-image
    part="image image--loaded"
    exportparts="..."
    src="..."
    alt="..."
  >
    ...
  <my-image>
</template>

Now we can target the loaded state using ::part()!

::part(image--loaded) {
  /* targets the image once it has loaded */
}

There's no limit to the number of parts an element can have. You can add many additional states if you think they'll be useful.

<template>
  <!-- shadow root -->
  <my-image
    part="
      image
      image--loaded
      image--square
      image--large
      image--jpeg
    "
    exportparts="..."
    src="..."
    alt="..."
  >
    ...
  <my-image>
</template>

Why BEM?

While the examples herein are contrived, I'm hoping you can see the value in using the BEM convention for naming CSS parts. I chose it because it's familiar and it easily represents everything we need: parts, subparts, and states.

Another big win for BEM-inspired part names is that consumers don't have to escape anything in their CSS. It's perfectly valid to name a part image:loaded, for example.

<div part="image image:loaded">

But your users will need to escape the colon in their stylesheet, otherwise the selector won't match.

::part(image\:loaded) {
  /* this works, but requires a backslash before the colon */
}

This may not seem like a big deal but, in the world of CSS, escaping isn't something users typically do and they're probably going to forget. Imagine how frustrating it will be for a user to see a part called image:loaded in your documentation and, when they try to implement it, it doesn't work and they don't know why.

Since dashes and underscores don't need to be escaped, they're a more foolproof choice for naming parts.

*The ::part() selector is intentionally limited by the spec so you can only target elements the custom element author explicitly exposes.

Valid Names for CSS Parts

Cory LaViska — Sun, 20 Feb 2022 20:46:00 +0000

CSS Shadow Parts, colloquially known as CSS Parts, are used to expose elements inside a web component's shadow root so they can be styled by consumers with CSS. But what are we allowed to call these parts? What characters comprise a valid CSS part name? To find out, I had to dive into the spec!

The part attribute is parsed as a space-separated list of tokens representing the part names of this element.

OK, but what exactly is a "token?" It's not really clear from this page, but we get a hint if we look at the spec for the ::part() pseudo selector:

::part() = ::part( <ident> )

It expects an <ident>, whatever that is. Fortunately, there's a link to it that takes us to a page that defines it.

CSS identifiers, generically denoted by <ident>, consist of a sequence of characters conforming to the <ident-token> grammar.

Perfect! So part names must conform to the <ident-token> grammar, but what's that mean? Let's follow the link to <ident-token> in the spec.

From that page:

<ident-token> [...] have a value composed of zero or more code points. Additionally, hash tokens have a type flag set to either "id" or "unrestricted". The type flag defaults to "unrestricted" if not otherwise set.

That's not, uh, super helpful. There's a link around "code points," so let's see if that makes it more clear. The link goes to this page:

A code point is a Unicode code point and is represented as "U+" followed by four-to-six ASCII upper hex digits, in the range U+0000 to U+10FFFF, inclusive. A code point’s value is its underlying number.

That seems to be a pretty wide range, though. According to Wikipedia:

The last code point in Unicode is the last code point in plane 16, U+10FFFF.

So does this mean we can use any Unicode character as a CSS part name? I'm no Unicode expert, so it still isn't clear.

Experimenting with Various Characters

Let's experiment and see what actually works in the browser. I created a sample custom element with the following parts, then tried styling them with ::part() to see what actually worked.

✅ part="a"
✅ part="a-b"
✅ part="a_b"
❌ part="a,b"
❌ part="a.b"
❌ part="a$b"
❌ part="a+b"
❌ part="a@b"
❌ part="a?b"

Clearly we can't use any character for part names. The browser doesn't like symbols, which feels intuitive to be honest.

Let's try some more characters.

✅ part="á"
✅ part="ñ"
✅ part="ę"
✅ part="Ф"
✅ part="平"
✅ part="λ"
✅ part="ה"
✅ part="字"

It seems to be OK with non-punctuation. What about emojis?!

✅ part="🥕"
✅ part="🐛"
✅ part="🐓"
✅ part="💩"
✅ part="🤨"

Totally fine. So it seems like any character except punctuation is good. Let's check out that lower Unicode range the spec referred to: U+0000

Here's a document with the lower end character points. It lists a number of the symbols we tried earlier in this range. 🥲

Clearly this range doesn't reflect valid CSS part names. Maybe we overlooked something in the spec, or maybe the CSS spec defines the argument too generically. Surely the HTML spec will explain it better.

Whoops...there's no mention of the part attribute at all. 😭

Let's see if this MDN page can help us clear things up.

A space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element.

OK, but what is a valid part name?!

MDN To The Rescue

I'm still not sure what's correct per the spec. Let's take a look at the ::part() docs in MDN now. I found this, which looks a lot like what we saw in the spec!

::part( `<ident>+` )

There's a link around <ident> that goes to this page, which says:

Thus far, MDN has provided the most human-readable explanation of what a valid ident is, and therefore what a valid CSS part name is. Here's the rundown of valid characters:

A-Z, a-z
0-9
hyphens
underscores
escaped chars
unicode chars in hex format

This explains why my punctuation examples didn't work. Here's something interesting, though:

an escaped character (preceded by a backslash, )

So can we use any character? Let's try one of those parts with punctuation that didn't work again:

<div part="a.b">

Now let's target it with CSS:

::part(a\.b) {
  ...
}

It works! So the spec is technically correct in that any character can be used, it just wasn't clear in that some of them need to be escaped.

Check this out:

<div part="a.b{c}|d">

And with CSS:

::part(a\.b\{c\}\|d) {
  ...
}

This works too!

Using Parts To Target State

Until now, I've primary used a single part for each element I wanted to expose. However, per the spec, parts should be used more like classes:

Part names act similarly to classes: multiple elements can have the same part name, and a single element can have multiple part names.

I guess I should change the way I use parts. I used to think of them as an identifier, but thinking of them more like classes as the spec suggests can help fill a gap!

Now that I know underscores are valid, I may explore them as a convention for hover/focus/active states since we never got the ::state selector. For example, we can give parts a synthetic focus state or even "hoist" a natural focus state to another element in the component.

<div part="control control_focus">

With this convention, perhaps we don't need a ::state selector after all!

Just Because You Can, Doesn't Mean You Should

So there you have it. You can name CSS parts anything you want — just remember to escape special characters! Using the previous example, we can even remove all of the letters and make a part name with only symbols!

<div part=".{}|">

The selector gets a bit crazy, though.

::part(\.\{\}\|) {
  /* 😎 */
}

I've tested this in all modern browsers and it appears to work consistently. Of course, this isn't very practical. Out of respect for your users, I would advise against naming your CSS parts like this! 🙈

I'm torn on whether or not special characters are useful here. Perhaps for an internal pattern, but I don't think I'd expose it as part of a public API. Users will definitely forget to escape those characters in their stylesheets. For my parts, I'll probably continue using a-z and dashes most of the time.

A Web Components Primer

Cory LaViska — Fri, 04 Feb 2022 15:51:00 +0000

On the eve of February, I was inspired to tweet about web components. What started as a simple thought quickly turned into a series of tweets that folks seem to find useful. I've adapted the thread and I'm posting it here for prosperity.

Overview

Shadow DOM? Light DOM? Slots? If you've heard of these but aren't sure what they are, maybe this will clear things up!

Custom elements are a feature that's baked into modern web browsers. You can build portable, reusable elements and use them in any HTML page. The collection of browser APIs that make this possible is known as web components.

Custom elements are written in JavaScript and must be registered at runtime. A custom element's tag name must start with a-z and contain at least one dash, e.g. <my-button>.

Shadow DOM

One of the best (and least understood) features of web components is the ability to encapsulate styles so nothing leaks in and nothing leaks out. This is done by attaching a hidden, separate DOM to the custom element.

This hidden DOM is called a "shadow DOM" or "shadow root."

The shadow root lets you use simple class names and ids without worrying if other elements on the page are using the same ones. (No more BEM!)

You can attach styles and scripts to a shadow root, too. It's kinda like a mini webpage within a webpage…minus the <iframe>. 😂

The Host Element

When you attach a shadow root to a custom element, the custom element acts as the host. Thus, we call it the "host element." Within a shadow root, you can target the host element in CSS using the :host() selector. (OK, it's technically a function.)

The host element is just another HTML element, but you control its API. You control what attributes it can have, what properties it uses, and what it renders.

You can even control the content that gets "slotted in."

Slots

Within a shadow root, you can create placeholders called slots. Slots let you control where child elements will be rendered in the template. The default slot looks like this in the custom element's template:

<slot></slot>

Additional slots can be added, but must be named. In the template, that looks like this.

<slot name="header"></slot>

Given the following custom element, the default slot will be populated with the paragraph and the header slot will be populated with the <h2>.

<my-element>
  <h2 slot="header">Named Slot Example</h2>
  <p>Lorem ipsum</p>
</my-element>

Everything you see here above is rendered in what we call the "light DOM."

Light DOM

You can style things in the light DOM as you'd expect using simple CSS selectors. What you don't see is the internal HTML structure of the custom element. That stuff exists in the shadow DOM and isn't exposed for styling. This is what seems to confuse and frustrate people.

By default, you can't style anything other than a few inherited font properties. That doesn't sound useful at first, but the browser gives us ways to "poke through" the shadow root and apply styles.

That's right. As a custom element author, you can tell users what they can and can't change in the shadow root — and enforce it!

There are two primary tools we lean on for styling custom elements.

CSS Custom Properties

Unlike regular CSS properties, CSS Custom Properties, or "CSS variables," cascade through shadow roots. They look kinda funny because they always start with two dashes.

:root {
  --brand-color: blue;
}

Tip: the :root selector above targets the <html> element.

To reference a CSS variable in a stylesheet, we use the var() function.

:host {
  color: var(--brand-color);
}

CSS variables get interpolated, so the above will be interpreted by the browser as:

:host {
  color: blue;
}

But unlike Sass, nothing gets compiled! Thus, if the variable changes at runtime, the browser happily updates everything using it. Did I mention that CSS variables cascade? You can redefine CSS variables in any selector, including pseudos such as :hover and :focus.

Of course, since we can't tap into the shadow DOM to style things, the custom element will need to "expose" which CSS variables it accepts as part of its API. This is a bummer, because the custom element author will need to expose a CSS variable for every property and state you might want to target.

If only we could style specific parts inside the shadow DOM. 🤔

CSS Parts

Well, we can! A custom element can expose "parts" which are aptly called CSS Parts. Parts are also defined in the custom element's template, this time through the part attribute.

<div part="container">
  ...
</div>

This exposes a part in the shadow root called container that consumers can target with CSS.

my-element::part(container) {
  background: blue:
  color: white;
}

Now you can style any property you want on that part, including states such as :hover and :focus!

my-element::part(container):hover {
  /* ... */
}

my-element::part(container):focus {
  /* ... */
}

To recap: a CSS variable allows users to customize a single property and a CSS part allows them to customize all properties on the exposed part. When authoring custom elements, it's not always clear which one to use and when. The rule of thumb I follow is:

When a single value gets reused throughout a component's styles, a CSS custom property is usually fine
When you need to expose more than a handful of properties on a single element, a CSS part is usually better

"Why can't I just style things like normal?"

That's a great question. I'm glad you asked…

Custom elements give us a way to build complex components with strong API contracts. Component authors can freely refactor internals without changing the public API. That wouldn't be possible if everything was exposed by default. Most things would be a breaking change. 😭

Style and logic encapsulation has been the holy grail of web development for a long time. Many solutions have been implemented to fake it, but elements have always been susceptible to leaks. The platform has finally given us a tool to solve this problem, so it's worth taking the time to learn and understand it. Once you do, I'm certain you'll embrace it!

"Web components sound kinda complicated!"

Perhaps at first, but if you know HTML you're halfway there! Plus, these are standard browser features and, unlike framework knowledge, learning this stuff will last you a long, long time.

Think of all the frameworks you've learned over the years and no longer use because their popularity declined. The nice thing about web components is that browsers have committed to supporting them for a long time!

The spec will surely evolve, but the rug won't be pulled out from under you.

"How do you write web components?"

You can write them with plain ol' JavaScript. Or you can use one of the many great component authoring libraries such as Google's Lit. React users might like Haunted for its hook-like syntax. Functional programmers might prefer Hybrids. There's also Microsoft's FAST Element and many others.

It's worth mentioning that both Svelte and Vue let you generate custom elements too!

Each library/framework has its own philosophy, but they all generate web components that work in any framework — and in plain ol' HTML pages.

The beautiful thing about this is you're not forced into a specific flavor. You can write web components the way you want to write them without sacrificing interoperability!

"Does anyone even use web components?"

Yes. A lot of big companies are using them and they're becoming ubiquitous. Recently, over 18% of pages loaded in Chrome registered at least one web component.

Fun fact: Adobe is using web components for the web-based version of Photoshop and other apps that used to be desktop-first are transitioning.

"But I like my React/Vue/Angular!"

That's cool! I like frameworks too, but I'm tired of rebuilding the same components every couple years. Most frameworks play nicely with web components, so you can have your cake and eat it too!

While most web components work perfectly fine as-is inside various frameworks, there is one notable exception.

React is super popular but it kinda doesn't get web components. What can we do?! No worries, React has added experimental support for custom elements behind a flag. A lot of progress has been made here recently!

In the meantime, you can wrap any custom element for React with a simple function call. This will generate a real React component that wires things up to the underlying custom element. It's like magic! (Tip: the utility has Lit in the name, but it works with all custom elements.)

How to Get Started

Hopefully you learned something about web components and shadow DOM in this thread! If you haven't experimented with them yet, why not? It's worth your time to better understand them. Even if you're not developing them yet, you'll likely be using them soon.

One great way to jump in is by using a library. I happen to be the author of Shoelace, an open source web component library featuring more than 50 useful components.

This is a great way to get started with custom elements and, because it's open source, you can dive into the code and start learning how they're made too!

Have questions? Want to learn more about web components? Follow me on Twitter for more tips, resources, and other web dev stuff!

Flash of Undefined Custom Elements (FOUCE)

Cory LaViska — Wed, 29 Dec 2021 17:15:00 +0000

Web components are defined and registered with JavaScript. Depending on how and when you load the scripts that perform registration, you may see a brief flash of unstyled HTML where your custom elements should be when the page loads. This is not dissimilar to FOUC, which occurs when HTML is displayed before the stylesheet has loaded.

For reference, here's an exaggerated example of three custom elements loading at different intervals.

Since the world needs more acronyms, and since one doesn't seem to exist yet, I'm calling this phenomenon FOUCE (rhymes with "spouse"), which stands for Flash of Undefined Custom Elements.

Fortunately, the browser gives us some tools to mitigate it.

The `:defined` selector

One option is to use the :defined CSS pseudo-class to "hide" custom elements that haven't been registered yet. You can scope it to specific tags or you can hide all undefined custom elements as shown below.

:not(:defined) {
  visibility: hidden;
}

As soon as a custom element is registered, it will immediately appear with all of its styles, effectively eliminating FOUCE. Note the use of visibility: hidden instead of display: none to reduce shifting as elements are registered.

The drawback to this approach is that custom elements can potentially appear one by one instead of all at the same time.

That's certainly a lot better, but can we take things a bit further?

Awaiting `customElements.whenDefined()`

Another option is to use customElements.whenDefined(), which returns a promise that resolves when the specified element gets registered. You'll probably want to use it with Promise.allSettled() in case an element fails to load for some reason (thanks, Westbrook!).

A clever way to use this method is to hide the <body> with opacity: 0 and add a class that fades it in as soon as all your custom elements are defined.

<style>
  body {
    opacity: 0;
  }

  body.ready {
    opacity: 1;
    transition: .25s opacity;
  }
</style>

<script type="module">
  await Promise.allSettled([
    customElements.whenDefined('my-button'),
    customElements.whenDefined('my-card'),
    customElements.whenDefined('my-rating')
  ]);

  // Button, card, and rating are registered now! Add
  // the `ready` class so the UI fades in.
  document.body.classList.add('ready');
</script>

In my opinion, this is the better approach because it subtly fades in the entire page as soon as all your custom elements are registered. After all, what's the point of showing the page before it's ready?

The drawback, of course, is that you need to keep track of which elements you're using and add them to the list. But this can also be an advantage if your initial UI only requires a handful of custom elements. For example, you can load only the ones you need upfront and let the rest of them load asynchronously to make your page load faster.

Have you used either of these methods to prevent FOUCE? Have you thought of a better way? Let me know on Twitter!

December 30, 2021: The original version of this article mentioned script placement in the <head> as a method of eliminating FOUCE, but that doesn't work if you're using ES modules. While the approach works for non-modules, I've removed it because it leads to poor page load times and because of the growing ubiquity of ES modules on the Web.

Bulletproof Components

Cory LaViska — Wed, 08 Dec 2021 22:16:00 +0000

Somewhere buried in my dusty basement lives a signed copy of Dan Cederholm's classic book Bulletproof Web Design. I purchased it during my first trip to An Event Apart in 2007. This book meant a lot to me back then, and almost 15 years later, many of its concepts still hold true.

The premise of the book is that designs should be "bulletproof" to accommodate the many ways they can be used.

I'm using the term bulletproof partly to describe flexibility—in other words, designs for the web that can easily accommodate various text sizes and amounts of content, designs that expand or contract along with whatever is placed within them.

I've been a software engineer for many years. More recently, my focus has been on building design systems. Although a lot has changed on the World Wide Web over the last decade, it's easy to recognize that many of the principles in Dan's book also apply to component development.

But what does a bulletproof component entail? Before jumping in, let's take a look at why we break down websites and applications into components in the first place.

Why do we build components?

Perhaps the most obvious benefit of the component pattern is reusability. Nobody wants to write the same code over and over again. If you end up doing that, have fun finding and updating all of the instances — and variations thereof — that make their way into the wild. This doesn't scale well in small orgs and it falls flat on its face in large ones.

Components are a vehicle for reusability. Their very nature leads to visual and behavioral consistency. By encapsulating structure, style, and logic into neat little packages, components become powerful tools in your users' arsenal — tools that are convenient to use and a bit harder to misuse.

When you break a design down into reusable bits, you can assemble, or compose, those bits to recreate the original design. Better yet, you can create entirely new designs with a lot less effort than building them without composition. Components are the building blocks of your application's foundation.

It's no secret that I'm a fan of web components (and I'm in good company), but I'm not here to sell you on web components today. What I will say is that more and more large organizations are leaning on web standards to build and rebuild their design systems in a technology agnostic way. Interoperability falls under the umbrella of reusability, but I think it's an important technical detail to point out.

What makes a component bulletproof?

The term bulletproof might be misleading, so let's consider this passage from Dan's book before we continue:

Out in the nonvirtual world, a bulletproof vest never guarantees complete, 100% protection, but rather being bulletproof is something that's constantly strived for. You're far better off wearing a bulletproof vest than if you weren't.

What we're aiming for with bulletproof components isn't perfection. We're aiming for components that are as intuitive, flexible, and resilient as possible.

Here are some of the key features that comprise a bulletproof component.

Ease of Use

Every component has an API that serves as its primary interface for users. As a component author, many of your users are probably developers which means good DX is critical. Offering consistent, predictable APIs is vital to good DX and therefore a fundamental feature of bulletproof components.

If you have a library, for example, don't make the size property accept small|medium|large in one component and sm|md|lg in another. As a user, if I've used one or two of your components, I should be able to get the hang of things pretty quickly based on prior experience. Let me build on that knowledge as I go.

Similarly, I should be able to glance at any component and have a pretty good idea what it does. I know you've documented it, but when I see a component in the wild, I don't want to open the docs unless I absolutely have to.

It's easy to overload a component with too many features. Oftentimes, that's a sign you should break it down further. Components that take on too much responsibility aren't only harder to use, they're harder to maintain too.

Versatility

Components are designed to be reused, so you never know where they'll end up in an application. Plan for this. Expect that users will drop your component into a 100×100 container, a 1200×1200 container, and everything in between. It's not that they're trying to break things, it's that edge cases happen a lot and it's better to be prepared than to be caught off guard.

As component developers, we can't predict every possible use case, but we can offer resilience by asking the right questions during development.

Does it break when I place it in common locations?
Does it grow and shrink as the user will expect it to?
How does it render on a mobile device? A tablet? An extra large screen?
Is it accessible in all places it's likely to be used in?
Does it work equally well on touch devices as it does with a mouse?
Does it work properly as part of a composition?

Sometimes it doesn't make sense to test for one thing or another. Use your best judgment and consider the intent. Nobody understands your users better than you, so adapt your questions accordingly.

Interoperability

As building blocks, components must work across a variety of applications. Unless your organization has a technical mandate, this usually means you need to support a variety of frameworks such as React, Vue, Angular, etc. Interoperability doesn't mean building the same component for every framework you need to support. It means using the same exact components in every framework.

This might sound like a web component plug but, realistically speaking, why wouldn't you want your components to work everywhere? Interop is important because there's a lot of upfront costs, maintenance burdens, and technical debt that comes with building the same thing multiple times.

Smaller orgs can get away with using a single framework for awhile, but it will eventually catch up to them. Which brings me to the next feature of bulletproof components…

Longevity

Congratulations! You've built a component library using your favorite framework. Your users are happy and everything is great. They love the shiny new buttons you gave them!

[a year or two later]

Oh look, your favorite framework has evolved. Version 2 is out and that means breaking changes! Quite possibly lots of them. No worries though, version 1 is still, uh, kinda supported. You can probably keep using that for awhile. Wait, what's that? You say a number of teams in the company have already upgraded to version 2?

Now you have two component libraries to build and maintain! Or maybe you can endure the challenge of getting everyone in the org to upgrade their old apps. Neither situation is ideal for you, your users, or your organization. Web components can help mitigate this.

Documentation

As a component author, I can tell you without question that most developers don't like to read documentation. Nevertheless, good documentation is a necessity for bulletproof components. But what exactly is "good documentation?"

Good documentation isn't necessarily comprehensive documentation. While it's certainly important to include all the relevant details of a component's usage, producing superfluous amounts of content is a disservice to your users. People aren't reading your documentation during their coffee break. They have work to do and they want to get it done efficiently. Make it easy for them to find what they need.

Your component's documentation should be scannable. Tell me what it does. Tell me how to import it. Tell me what props are available. Fill the page with relevant examples and order them from most common to least common, leaving the edge cases for last. Call out important tips and gotchas in context so they're prominent, but not distracting.

Don't let your content become stale. Nothing is more frustrating than docs that aren't aligned with a component's implementation. Avoid decoupling things that are likely to be forgotten over time.

Code analyzers can help keep important things such as props, events, and more up to date by bringing the documentation closer to the to code. Remember how I said developers don't like to read? Most don't like to document things, either. Make it harder for them to not document their changes.

Get Inspired

Building components is an art, and this post certainly isn't definitive nor comprehensive. My intent is to document, through experience and observations, the characteristics that make up bulletproof components.

Consider this an ode to Dan's vision of Bulletproof Web Design — an extension of a great idea adapted for component development.

I'm particularly proud of the work I've done on Shoelace, a library of components that I purposefully maintain with longevity in mind. This project demonstrates all of the principles I've described herein, and I encourage you to use it as inspiration in your own projects. I also encourage you to contribute to the paradigm of bulletproof components through discussion or demonstration via Twitter.

I can't wait to see what you're working on!

Empowering Design System Users

Cory LaViska — Mon, 01 Nov 2021 21:21:00 +0000

The question of whether or not component APIs should be locked down at the code level comes up quite a bit. For example, if a button spec only calls for primary, secondary, and tertiary variants, should we still expose parts and custom properties so users can make further customization as needed?

In my experience, the answer is "yes."

The arguments for locking things down seem to stem from designers who want pixel-perfect results. That's understandable — after all, engineers aren't usually known for their creative skills — but restraints have consequences.

As design system engineers, we have to face the hard fact that, at some point, users are going to do things that are wrong. It's not our job to prevent them from doing those things. It's our job to give them tools that make it as easy as possible to do things that are right.

This may seem counterintuitive, but requirements change and designs evolve. The best way to experiment with new ideas is to customize what's already there. Neutering a component's API for the sake of design purity means it can no longer be used as a building block for new ideas.

When your API is too rigid, users will do crazy things to work around it. I've seen developers poke through the shadow root with JavaScript to add custom styles to encapsulated components. In another instance, a consumer built their own version of a component because we didn't expose any CSS parts. All the functionality was there — they just needed different styles.

You might think you're doing your organization a favor by enforcing standards. I mean, the whole purpose of a design system is to encourage consistency, isn't it?!

Absolutely, and you can do that with well-designed components and copy + paste examples that demonstrate their correct usage. Assuming developers want to do the wrong thing is a fallacy. Most of them want to do the right thing and, given the tools, will seldom venture outside the walled garden that is your design system.

But when users do need to color outside the lines, taking away their crayons won't stop them. They'll just grab the closest Sharpie and do it anyway.

Empower your users and you'll save everyone a lot of time and frustration.

Take advantage of design reviews to understand how consumers are using your components. What customizations have they made? What pain points did they have implementing them? Use this feedback to improve your offering, but know when to draw the line.

DEV Community: Cory LaViska

Web Components Are Not the Future — They’re the Present

WTF is a component anyway?

The definition of component

It’s ok to be shiny

The right direction

Living dangerously

Longevity supersedes ingenuity

How to File a Bug Report

Help Us Help You

Better Bug Reports

Do

Don't

Just for Fun

Custom Event Names and the Bubbling Problem

Checking the Target

Checking the Current Target

Checking the Event Phase

Why Not Use Unique Event Names?

A Web Component Story

Buttons and Cursors

Learned Behaviors

How We Got Here

Design Systems Aren't Cheap

A Real Life Example

The Cost of Frameworks

The Platform Outlives Frameworks

Jump Starting Your Design System

CSS Parts Inspired by BEM

Blocks → Parts

Elements → Subparts

Modifiers → States

Why BEM?

Valid Names for CSS Parts

Experimenting with Various Characters

MDN To The Rescue

Using Parts To Target State

Just Because You Can, Doesn't Mean You Should

A Web Components Primer

Overview

Shadow DOM

The Host Element

Slots

Light DOM

CSS Custom Properties

CSS Parts

"Why can't I just style things like normal?"

"Web components sound kinda complicated!"

"How do you write web components?"

"Does anyone even use web components?"

"But I like my React/Vue/Angular!"

How to Get Started

Flash of Undefined Custom Elements (FOUCE)

The :defined selector

Awaiting customElements.whenDefined()

Bulletproof Components

Why do we build components?

What makes a component bulletproof?

Ease of Use

Versatility

Interoperability

Longevity

Documentation

Get Inspired

Empowering Design System Users

The `:defined` selector

Awaiting `customElements.whenDefined()`