Web Components (Part 5): Puzzle Shell

mm
Mathis Hofer
27. Dezember 2023

In the previous article of this blog post series, we looked at the Lit library through the eyes of an Angular developer. Now, in this fifth and final article, we want to present a concrete project that we’ve built with Web Components and Lit: the Puzzle Shell is a component library we use to build the responsive base layout and design of internal applications consistently.

The birth of the Puzzle Shell

At Puzzle we have various applications that are used by our members internally, such as the time tracking software, the documentation platform or our services index. Some of them have been developed by us, others are free software projects with a customized theme.

We realized, that all those applications have been dabbling to implement the Puzzle identity somehow for their UIs, but not all of them where prolific attempts. Even though all these applications use common elements such as a header, a responsive (hamburger-)navigation, user settings and logout links or a footer, the results have been vastly diverse:

A screenshot of headers, as they have been implemented by the various applications, all looking differently.

That was the moment when we recognized the potential for a component library that provides all necessary building blocks to implement the „shell“ of an application. This would achieve a uniform and consistent presentation with recognizability among all our internal tools and solutions. Additionally, such a library would tremendously facilitate the customization of an existing theme. So we came up with the Puzzle Shell project – a standard design for Puzzle tools as a set of Web Components – which is available on GitHub as free software and published as @puzzleitc/puzzle-shell NPM package:

https://github.com/puzzle/puzzle-shell

Why Web Components and Lit?

While you can totally build whole applications using Web Components (and many do, including us), they certainly have a sweet spot when it comes to building reusable, framework-agnostic UI components.

That is exactly what we wanted to do. We wanted to build a component library that integrates well with a variety of technologies, as our tools range from Angular or Elm single-page applications, to classic server-rendered Rails or Java applications, to statically generated sites using Hugo, Jekyll or Antora. The library should also come with as little overhead as possible and not interfere with other libraries or frameworks.

Hello then, Web Components with Lit, the solution that fits all these requirements like a glove. It has a small footprint, since large portions of it are already part of the browsers and it just works with anything that supports HTML.

The concept

First, we developed a limited design system for our „shell“. We introduced a logo system, a color scheme and header concept using tangram elements – all based on the Puzzle identity & corporate design.

Second, we identifed the elements common to the various applications and outlined a mapping of a few application’s layouts to a new version using the building blocks of the Puzzle Shell library. Some of them had to be adjusted more than others, but it lead to a pleasant consistency, which improved the orientation in the different applications.

Last, we determined three scenarios for which we wanted to build an example layout:

  • A content-heavy site with search (e.g. documentation platform or Wiki)
  • A web application with navigation (e.g. time tracking app)
  • A welcome page with search

Building UI components in isolation

To build and document the components and to implement the scenarios, we relied heavily on Storybook. Storybook is an ideal tool for building and testing different variants of components in isolation. Thanks to MDX it also allows the documentation of general concepts and ideas. You can find the Puzzle Shell Storybook here:

https://puzzle.github.io/puzzle-shell/

A screenshot of the Puzzle Shell Storybook

Setting up Storybook for your Vite/Lit project is a piece of cake: Storybook has a Web Component renderer which is auto-detected, when running npx storybook@latest init in your existing project.

Conclusion

We have already successfully migrated a few tools with completely different technology stacks to the Puzzle Shell component library. A few new applications were also added to the collection, using Puzzle Shell from the beginning. It was nice to see how much HTML and CSS could be removed (or avoided) thanks to the reusable components. And it’s gratifying that once the responsive components are implemented in the library, they can be used effortlessly without having to be a frontend specialist. A nice proof of this is the fact that our apprentices use the Puzzle Shell in their own projects.

The end

This is the end of our five-part blog post series on Web Components and Lit. We hope you enjoyed reading and gained some fascinating insights. We are big fans of the current frontend trend to get closer to the web standards again. As you will have noticed, we have definitely been „lit“ on fire for the topic and are excited to see what further developments the web platform will bring us in the future.

All articles of the series:

Kommentare sind geschlossen.