Building a modern design system in layers
NOTE: This was originally posted on my own corner of the Internet.
So often, when building a design system, we end up building something rigid that we will struggle with as time goes by. When this is done, we can try to evolve it well, and to make it so good that developers are somewhat happy with it even if they don’t like the rigid choices that were made.
This happens in all eras. Most recently, you will find many design systems that are React design systems vs. Web design systems that offer idiomatic React as an awesome option. As soon as you have made that choice you have locked in an audience and a lot of option value is taken off of the table.
Let’s consider that you are building a design system at a company that is on the path to becoming a 100 year company where you aspire to think long term. I contend that it makes sense to build your design system in layers that:
- Have the wiggle room to move independently
- A layer can even be replaced
- Developers can swap out layers, especially those higher up in the stack
If I were holding a React design system today, and I was offered the opportunity to go back in time, I would swap it out for a layered Web design system.
What would this look like?
Let’s quickly talk about these layers.
Design foundational layer
Modern CSS can do so much these days. Start building out as much of the design system as possible with HTML and CSS. Components that used to be complex nested can not be a with some sprinkles. If you want some inspiration, check out the fine work of folks such as: Adam Argyle, Una, Jhey, and Josh W. Comeau.
Here you create your helpful guardrails via design tokens, your low level primitives, and your higher level components. I would consider using something like Adam’s Open Props as a strong foundation.
With some exploration, you will probably find that this layer gets you quite far these days, and with a nice story book playground developers will love to tinker as they learn it.
Interactivity layer
Next up you can loosely wire up the pieces via custom elements. This should be a relatively thin layer that brings to full life. You can choose a helpful tool such as Lit or Stencil to make it even easier.
These components run on top of the Web Platform, and are thus incredibly future proof.
Framework layer
Some developers will happily take the custom elements and use them directly, but most will probably want to use some bindings that feel idiomatic in the framework of their choice. There is no need for a holy war of “Framework vs Web Components!” They can happily work together these days. In fact, tools such as Lit have wrapper tools to make it easier to take your components and vend them as idiomatic framework components such as React.
Reach, Value and Future Proofing
With this approach you have set yourself on a solid long term path. Your work can now reach web developers that are choosing a variety of frameworks. If there is one thing we know about the web, it’s that there is healthy innovation and evolution on this layer. We can’t predict the future, but we both know that there will be new frameworks with significant developer share AND there will be a ton of apps running React and jQuery and … for some time. Both are true, so why not support both?
Now, you may be thinking: “We aren’t resourced to support all of the items in the framework later!” This is often true, however you don’t have to support them all, you can choose levels of support, such as:
- First class / Well lit path: you make sure yourself that everything fully works end to end using code that you write and maintain.
- Community support: with a well lit path or two out there, the community can take a look at the end to end solution, along with the layer below that it relies on, and create their own idiomatic bindings. The more you document the first class stack, the easier it will be for the community to take high quality code, with tests, and a spec of sorts and build something of high quality themselves. Make sure to elevate the work and effort that they put into it!
- Individual usage: if there isn’t a library itself, a developer using their framework of choice can just use the custom elements to build on. Chances are one of these will jump up to the level of community support… especially if you incentivize and foster this.
I don’t know about you, but it feels like we are in a frothy time for the Web framework space. React has an army of developers, but there is some confusion on which direction to go. Will RSC fully pan out? When should you use Next.js or Remix?
This shines through when you see videos showing up putting forth points of view such as always bet on react! and I don’t hate react, i’m just moving on. It’s a time of change, right when there are amazing non-React options such as Solid, Svelte, Vue, Preact, and more. This is healthy, and having written web applications with more different frameworks than hot dinners that I have consumed, they can all help you deliver something great for users. So, it’s kinda win win.
It does make you think about…
Learn in Layers
Some wanna-be-gatekeepers have poo poo’d developers who come in and learn React first, and often skim some of the knowledge of the Web platform. There’s no need for the gate keeping, and this can be a great starting point.
That being said, I have always been a believer in Glen Vanderburg’s philosophy that it’s very much worth your time to understand one layer of abstraction below and potentially above you.
This means that you should have a solid understanding of the Web Platform APIs, as well as the core technology of JavaScript, CSS, and HTML. Often this naturally bleeds through, and although we are sometimes taught that a good abstraction doesn’t leak, some of the best abstractions are known as onion skin APIs when ”leaking” becomes a feature, an escape hatch.
ActiveRecord is a great example, where SQL isn’t hidden from you. Git has long built layers where you have porcelain and plumbing.
My good friend Dimitri has recently written about porcelains in the context of how we changed the API of Polymath with respect to talking to OpenAI. Instead of abstracting all of the fetch calls, we embrace the fact that developers probably know fetch well, and may want to use advanced features. We instead vend an API that understands the service via a request and response, so you end up with something such as:
While there has been a lot written in the form of “Web Components vs. $FRAMEWORK”, you find that this is totally the wrong frame. There are a variety of Web Platform APIs in the umbrella of Web Components, such as Custom Elements and Shadow DOM. If you take the time to learn this layer, you may find reason to use it with your web framework of choice. And if you do so, this knowledge will be durable no matter what other frameworks you use now and in the future. The browser moves slowly, and these APIs are here ~forever.
I recently worked with a team that deliver a high quality design system that is tied to React. If I could go back in time I would switch to this layered system in a second. It pained me to talk to developers that used the platform that the design system was used for but hadn’t chosen React. They want to deliver the same look and feel for users, so what do they end up doing? Many would view source and copy HTML and CSS and add interactivity. That’s a LOT of toil, and they have to keep up with changes in a painful manner with lots of diffing. If they could grab the lowest level, or maybe the custom elements with it, they would be off to the races in a sustainable manner.
Others felt they had to use React for these pieces, and hired consultants to do that work. This ate into their profits, and in dire situations could change the entire ROI of their solution (for small apps with a one or two person team).
I believe this design system will iterate and change over the lifetime of this company, that aims to be a 100 year one. You could argue that they are big enough to always make sure the React version is solid and updated and that developers have resources to keep with it.
Or, the evolution could happen at each level of the stack. Long time developers would understand the lower levels, and as they changed the highest framework level, they would be able to reuse that knowledge, use a community layer, or maybe the company has changed the first class framework and can use that solution.
If you have a modern design system, learn from my mistakes, and build it in layers.
That way a developer that chooses a different graph of tools from the subset of the options as Kent shows here, versus your exact path (which you will change too in the future), can play too.
/fin
