Truly Reusable Design Systems in Practice: Web Components by@ilyamkin

Truly Reusable Design Systems in Practice: Web Components

Read on Terminal Reader
react to story with heart
react to story with light
react to story with boat
react to story with money
Airbnb, Apple, Uber, Spotify, Spotify have created a company-wide design system. StencilJS is a toolchain for creating reusable, scalable design systems built on top of Web Components. It provides a set of tools to start working on your design system right now and makes it easy to work with Web Components. It also features screenshot testing (apart from e2e and Jest integration) to the Rescue. The core component of any design system is a simple-yet-stateful component.
Ilya Lyamkin HackerNoon profile picture

Ilya Lyamkin

Senior Engineer @ Spotify

facebook social iconlinkedin social icontwitter social icongithub social icon

Companies like Airbnb, Apple, Uber, and GitHub have changed the ways they design digital products by incorporating their design language and organizing it into a system that can be used across all employees — and even outside of the company.

It quickly became popular in the whole industry: Just google the company’s name and the word “design” next to it, and you’d be surprised by how many companies have something similar. Airbnb DesignApple DesignUber Base WebGitHub Primer — these are the examples of good design systems.

We won't be talking today about the reasoning behind having a company-wide design system or the organizational challenges that come with it (though it’ll be definitely covered later, so stay tuned). Instead, we’ll focus on the technical choices and implementation details.

Traits of a Good Design System

A good design system is a collection of reusable components — guided by clear standards — that can be assembled together to build any number of applications. Let’s try to split this definition into actionable traits we want to prioritize and focus on from a technical perspective.

Reusable components

Generally speaking, the design system is a set of shared components that’ll be used by everyone.

Imagine you have several independent teams in the company, and some of them use vanilla JS. Another team uses React, and even another group is experimenting with Svelte. As a creator of a design system, you have to build components for these frameworks and think about flexibility in the feature, so you won’t lock other developers in a specific ecosystem.

Extensive documentation

To ensure the smooth adoption of your design system, you’ll have to provide thought-through, easy-to-use documentation with examples and best practices.

How do you do this? First, a website with all components and their descriptions would help. Second, it’d be amazing if you could provide guidance about possible arguments and use cases for your components directly in the developer’s IDE.


So you’re about to ask your fellow developers to add this design system as a dependency and probably replace something that’s already working, make sure to keep the number of dependencies as low as possible, preferably zero, so you won't bloat the package size of all projects.

Try to rely on a browser API or CSS and be closer to browser-native behavior because less custom JS code means faster components.

Maintain the highest quality

You also need to ensure your design system won’t break on a new release. Apart from doing code review and manual testing, I’d encourage everyone to look at automated tests. For presentational components, consider screenshot testing. For stateful ones, write integration and end-to-end tests.

StencilJS and Web Components to the Rescue

If you’re wondering how you’re going to cover everything from the list above without spending a month setting up the architecture, I have something to suggest.

StencilJS is a toolchain for creating reusable, scalable design systems built on top of Web Components. It provides a complete set of tools to start working on your design system right now and makes it easy to work with Web Components.

The components created with Stencil are fully compatible with browser standards and can be run in any framework, including just a plain HTML file. You can use output targets to add a custom website that’ll showcase your work. It also features screenshot testing (apart from e2e and Jest integration).

Let’s dive into it, and see how easy it is to build a simple-yet-stateful component.

Introducing the fetch button

The core component of any design system is a button. But since just a button would be too simple, we’ll make it powerful enough to also fetch data from any endpoint you specify in its attributes and return data via browser events.

To start, run the Stencil generator: 

npm init stencil
. It’ll ask you to pick a starter. Choose Component. That’ll generate a folder with a simple test component so you can start playing with it (
npm install && npm start

In the 

 folder, you’ll find the
 folder. Rename it to 
 — as well as the 
 files inside of it. The CSS file is responsible for the styling of our button, so let’s add some styles:

button {
    color: #24292e;
    background-image: linear-gradient(-180deg, #fafbfc 0%, #eff3f6 90%);
    padding: 6px 12px;
    font-size: 14px;
    font-weight: 600;
    line-height: 20px;
    cursor: pointer;
    border-radius: 0.25em;

Now go to the

 file. This is the actual component we need to build.

import { Component, Prop, h, Listen, State, Event, EventEmitter } from '@stencil/core';

  tag: 'fetch-button',
  styleUrl: 'fetch-button.css',
  shadow: true
export class MyComponent {
   * URL to fetch
  @Prop() url: string;

   * The query status
  @State() status: string;

  @Event() success: EventEmitter;
  @Event() error: EventEmitter;

  @Listen('click', { capture: true })
  handleClick() {
    this.status = 'pending';

    .then(response => response.json())
    .then((data) => {
      this.status = 'success'
    .catch((error) => {
      this.status = 'error'

  render() {
    return (
          <slot />
        <div>Status: {this.status}</div>

Before the component class, we need to add a decorator specifying the tag name, a path to the style file.

Then inside of the class, we need to define a 

. It’ll work as an HTML attribute and allow us to pass data to the component.

The next line creates a state variable: Every time we change it, the render function will rerun.


directive registers two events for us:

 helps us to listen to click events and execute the corresponding function. In our case, we’ll call the native fetch function and update the state and trigger events depending on the outcome.

Finally, the

 function defines the DOM that‘ll’ be created. The
<slot /> 
tag will be replaced by 

That’s it. Now let’s see how we can use it.

<!DOCTYPE html>
<html dir="ltr" lang="en">
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0">
  <title>Fetch Button Demo</title>

  <script type="module" src="/build/designsystem.esm.js"></script>
  <script nomodule src="/build/designsystem.js"></script>

  <script src="[email protected]/umd/react.development.js" crossorigin></script>
  <script src="[email protected]/umd/react-dom.development.js" crossorigin></script>
  <script src=""></script>

  <fetch-button url="">
    Fetch my data from vanilla JS
    const fetchButton = document.querySelector('fetch-button');
    fetchButton.addEventListener('success', console.log)

  <div id="root"></div>
  <script type="text/babel">
          ref={el => el.addEventListener('success', console.log)}
          Fetch data from React


Apart from the native HTML example, I’ve added integration with React. As you can see, it’s as easy as writing plain 


Known Complexities

Now, it’s time to talk about the downsides of using Web Components.

The most important one is the lack of good framework support. For example, in React, you can’t attach event listeners to your component.

As a workaround, you can attach a native event using the

 property — which is what I did in the example above. The Custom Elements Everywhere website shows the compatibility Web Components has with popular frameworks.


Before starting working on the design system, evaluate the values you want to focus on. Maybe you don’t need to have it at all and just properly organized shared components would be enough for you.

If you’ve decided to incorporate the system, Web Components perfectly solves challenges that stand before design systems and is a great technology to build your components upon.

StencilJS makes it easy to manage and deliver components for different targets. But with all that in mind, beware and explore the still-standing issues regarding framework support.

react to story with heart
react to story with light
react to story with boat
react to story with money

Related Stories

. . . comments & more!