But while Design Systems should move slow and be intentional about every external change, there's also room for internal innovation. Internal innovation can happen much faster than shipping features, as the feedback loop is much tighter–it's immediately affecting your internal Design System team. Internal innovation in a Design System is a great way to prove out ideas before deciding to ship them more broadly.

We're system thinkers. We're good at generalizing things and thinking about how to make something general-purpose. So this type of work fits really well with Design System folks' skillsets, in my opinion.

What exactly do I mean by "internal innovation"? Anything that would speed up your Design System team to ship features. Or something that'd help improve the system, increase accessibility, or raise/ensure the quality bar. And bonus points if it's helpful and could be generalized for teams outside of your group. You may also find that opening the door for this leads to benefits to your users as well.

Glide Core is archived on GitHub, but you can still view the code. We decided to create a @required decorator to enforce Web Component attributes (or properties) to be required. This is something that Lit doesn't provide out of the box (for good reason).

We wanted to ensure our form elements always have a label for accessibility reasons. Using the @required decorator allowed us to enforce that.

This is an example of something that starts in the Design System, but could be generally helpful for almost anyone using Lit. And once again–it's good for accessibility, which does impact users.

I recommend writing your own ESLint rules. There are a ton of advantages. These lint rules may begin in your Design System, but may be helpful generally to others as well. Just like the decorator above.

ESLint rules may help nit-picks on PRs. If a robot can automate opinions, it's less time spent in a PR review going back and forth on something.

The web development ecosystem changes quickly. New tools land. Some of them are great, others are noise–that's another topic. But say you want to switch to a different test runner internally that'll give some benefit to your team. Doing this internally is a great way to prove it out, without negative impact on your users.

For example, say you're on jest. Switching to Playwright would mean you could run your tests in a real browser. You could configure visual regression testing. You could make use of their accessibility testing. This type of change also has an impact on end users–they benefit from a more stable and reliable product. +1 to the "critical infrastructure" comment.

Additionally, making this switch may give you confidence to propose this change more broadly across the organization.

"Switching to Playwright meant we improved our quality by testing in real browsers and interacting with the elements in tests just like our users. We also took advantage of visual regression and accessibility testing.".

Sounds pretty cool to me.

Using a third-party package allows you to use something off the shelf and get going. But not every package solves your exact needs. Some may no longer be maintained. Ideally you can contribute to open source software to help make the world better for everyone. But if not, building internal tools that replace unnecessary dependencies means less external dependencies and less risk. Especially with the recent supply chain attacks on npm packages.

Lowering our dependence on third-party packages is a good thing, in my opinion. Browser features keep getting better. Just use the platform (where you can), bro, please.

Above are some examples that came immediately to mind. But hopefully you get the idea. How can you retain the quality and stability our customers expect with a Design System being critical infrastructure while also keeping up with the times and potentially making life better for your team? For your users? For other engineers in your organization? I think this is how. Embrace a model of internal innovation, while not negatively impacting the Design System externally.

Take a look at your Design System. How's your team doing? Do you feel like there are things the Design System could innovate on to improve processes for your team? Are there opportunities to improve design consistency or testing practices? Are there things currently private to the Design System that could be generally used and helpful to others?

Spending time on innovation keeps the train moving. It may also scratch the "I have an idea itch" for some of your engineers. While some of these things impact the Design System team only (which is still good!), it could lead to great benefits to your Design System consumers. And even your product's users. And that's cool.

My ideal scenario for product engineers is to be able to go into Figma and copy the frame URL for a piece of UI that was built in Figma using the Design System. They'd paste the URL into an AI tool. The AI tool would have all of the context of the Design System – it'll know about all of the components and how to use them, it'll know about the variables, have access to all of the documentation, etc. – from there, the tool will generate the provided UI for the engineer.

It obviously won't be all of the code – it'll handle the visual building blocks though, which saves a bunch of time. Then the product engineers can worry about the "glue code". They'll handle data fetching, conditionally rendering certain things, and other scenarios. But they'll have a great starting point to spring off from. My thinking is that this would help accelerate development velocity and expand the usage of the existing Design System.

The first thing that comes to mind is feeding Figma as much information as possible. I've written about Figma Dev Resources before - this allows you to associate links to Figma components that show up in Dev Mode. It's helpful because it gives developers additional information.

The next logical step is to use Figma's code syntax feature for variables. All of those Figma variables you have? Convert them to CSS variables. Then write them back into Figma so that they show up in Dev Mode as the actual CSS variables you've generated. This way, when a product engineer is viewing designs, they can see the exact CSS variable names rather than the Figma variable name – these are normally slightly different due to syntax difference.

Lastly, wire up Figma Code Connect. I'm working with Web Components. So my plan is to use the Custom Elements Manifest to automate this. But no matter how you get Code Connect wired up, having these snippets available will save product engineers time. They can literally copy and paste snippets right into their editor for the component(s) in the exact designed state.

So now you're probably wondering "now what?". Figma Dev Resources, leveraging code syntax for variables, and Code Connect are all great. But what did that do for us exactly? Not only does this help Dev Mode and provide resources for your product engineers, feeding Figma all of this information gave it a lot of context. If you've been working with AI lately, you know how important context is for LLMs.

The next logical step is using Figma's MCP server. It's currently in beta.

Now that you've provided Figma all of this context on your Design System, I think we're really close to making my ideal scenario a reality with the MCP server. Time will tell, but I hope it'll do well. In theory, it should have a big chunk of the information it needs. Now of course, it may not gracefully handle cases that aren't using your Design System. But if it can get folks 70-80% of the way there, that's a huge win. This could go a long way in helping designers and developers.

What else could we automate and leverage AI for?

I'm thinking you may be able to create your own MCP server with a distinctly different purpose from Figma's. The role of a new MCP server wouldn't be translating the designs to code, but rather focusing on component usage and best practices. Going back to the Custom Elements Manifest, it could read from it and have all of the information it needs on the component APIs. It would know the attributes, properties, methods, etc., that are available. If you're not using a Custom Elements Manifest, there are other ways to get this information about your components (especially with React + TypeScript).

Now add on your Design System documentation on top of that. Best practices, when to use one component over another. All of this is additional context that would help it make decisions and increase confidence.

Folks are already using tools like Claude Code to build UIs. With this MCP server, my thinking is you could promote usage of your Design System. Rather than have it generate custom components from scratch, use what is already available, following the patterns that have already been defined.

Additionally, my hope is that providing an MCP server with this information would cut down on support requests. Fielding Design System support questions is really important. As a Design System engineer, we want to ensure our consumers get correct answers in a timely manner. If you can ask your AI tool instead, it very well may save the Design System team some time. And by providing it as much context as possible, hopefully the answer would be more correct and it'd cut down on hallucinations.

I can see the benefits of feeding LLMs with as much context about your Design System as possible. Not only may it increase velocity, I hope it'll also improve consistency in applications built and cut down on Design System support.

Overall, this is all just me rambling and some general thoughts I've been thinking about all year. I have no idea in reality if it'll work at all! But to me, that's the fun part. It's time to go find out and report back.

"Davy and PJ discuss the challenges and strategies for design system training, especially when it comes to Figma. We explore the line between providing direct tool training and focusing on how the design system integrates with those tools."

While I was on a walk listening, I kept nodding along. All of it is so relatable. But in particular I can relate to the education piece falling onto the Design System team.

I, too, really enjoy recording videos for training. But as they mentioned, it's annoying how tools and features change in a short amount of time. After a few months, your content is suddenly outdated. What a bummer.

Then I got to thinking about the engineering side of this problem. One huge advantage of building your Design System with Web Components – and to be clear, I'm talking the built-in-the-browser Web Components – is that browsers don't have a lot of churn. Less frequent changes would mean not needing to re-record videos every few months. That sure sounds nice!

And while this Bluesky post from Dave Rupert was about a different topic, he uses a phrase I'll now use forever:

If you’ve heard me talk about #webcomponents, you’ve probably heard me talk about how improvements and changes are slow… slow like brisket. Low heat applied over a long time (in this case 9mo after issue identified) but now all boats float and the platform we all build on got better.

mmmmm brisket (literally took a brisket cooking class a month ago, still thinking about it).

Back on track – I do believe Web Components with Design Systems are a bit of an insurance policy overall. And when it comes to the education piece of Design Systems, it's even more insurance. Core browser technology is cooked low and slow, like a brisket. You're guaranteed a great amount of stability over time. And as the browsers get better, guess what? So does your stuff!

Compare that to the churn you get when you pick something like React. I'm not saying React is "bad", of course, it's just the reality. Frameworks move at a much faster pace, which is what some organizations want/need.

This article from Jim Nielsen is along similar lines, in my mind, to this topic.

Learn more about the platform and use it as much as you can. It'll make you a better developer. Not only is it great for your Design System, it's also good for your career.

So if your Design System is built on "the platform", your education content won't be outdated as quickly. Sure, there will be new ways to do things, but the core fundamentals will be the same. And that has a lot of advantages. I'll report back in another year or two, as I'm currently setting up education content for our Web Component Design System, Glide.

If you'd like to learn more about why I think Web Components are great for Design Systems, I have an article for you. Or if you want a quick intro to Web Components, I've got that too. And as always, if you want to chat about Design Systems or Web Components, Bluesky or LinkedIn is a great way to get a hold of me.

Anyway, that's all I've got. See ya next time!

The words "Design System" and "adoption" in a conversation with higher-ups are inevitable. It's important in organizations where you really have to sell the value of a Design System. It makes sense they care about metrics and adoption – they want to ensure their investment is paying off.

And while I do think tracking metrics is good, I don't think it tells the full story. In my personal opinion, it's better to measure adoption visually and realistically – by going through your product and explicitly calling out the components being used. A "large number" of usage is great, but what if those pages aren't used frequently? Or what if they're "internal" pages?

Maybe these cases still speed up design and development. But I want to ensure our Design System components are front and center with our customers. That the organization is getting the most bang for their buck. And this idea of highlighting all components on a page help you tell your story on why the investment is worth it.

Rather than tallying up usages, you can show something more tangible.

"See this page? All components highlighted with a red border are our Design System components. We estimate using our components saved $x.xx/hour, etc., etc.,"

Additionally, as a visual person, I'd rather see the usage in the UI rather than look at a raw number. It's more meaningful that way. And many others feel the same way, I imagine. So go highlight them!

(I use the word "highlighting", but you can really do whatever. I've used outline or border CSS properties to do this with success. There are probably other things you can do too!)

One improvement that comes to mind is turning this into a Chrome extension. Pull up a page, click the extension, and voila – see all of your components highlighted.

The advantages of this are that any non-technical person can use this tool to perform an audit. Normal coding methods require a developer. But not this! At least after it's "completed".

The disadvantage is similar to it being just a script or a development-only tool – it's time consuming. Someone has to know how to get to every single page. I'm a developer, I want to automate this!

Because Haley and I are married and both in Design Systems, we started brainstorming how we could take it one step further. Then we landed on something I quite like – tie this functionality into your existing end-to-end tests.

Most end-to-end tests are already navigating through your application. Maybe even going to very specific pages that may be difficult to reach, depending on the data or path to get there.

As you hit areas you care about, create a custom function that will:

• Highlight all Design System components on a page
• Take a screenshot
• Turn off the highlighting

Store all of these images in a directory. Then you can provide a "report" of sorts to anyone who wants to know about Design System usage.

By tying in to your existing end-to-end tests, it means you get this auditing almost "for free". I dig it.

After you get some of this tooling in place, you'll have a way to check which parts of the application(s) are using your Design System.

Designers won't have to guess if they see a component that looks like a Design System component, but isn't quite right. If it doesn't have a red border, it's hand-rolled! Go chat with the team about why.

You can reason about costs easier – "this non-Design System component is estimated to cost $x.xx in maintanence, but if we switch to the Design System component that goes away". And on the flip side, as mentioned above, you can estimate cost savings of building new features and applications.

It also opens the door to notice patterns in your applications. Just like going to every page manually is time consuming, it's also difficult to spot patterns by popping around the application yourself. If you have an image of every part of the application handy, although it's a lot to sort through, you could more easily recognize patterns by flipping through everything. This is probably better done in Figma using designs, but sometimes pages exist in code that don't in design. So this gives you the full view – code is the source of truth and what customers interact with at the end of the day, not your designs.

Overall, I think this goes a long way and could help teams track and measure adoption in a more meaningful way than "numbers should go up!". Let me know what you think!

I've noticed product developers rarely use Dev Mode to its full potential. Many don't read the docs, as they're more concerned with building their feature on a tight deadline. I feel for them! They may not know how to tell which UI Kit a Figma component comes from or how to go to the main instance of a component. Their skillset is writing code and most have only surface-level knowledge of how to use Figma. Once again, I totally feel for them and understand why that is.

These questions continue to come up, across multiple organizations and engineering levels:

"Where does this component come from?"

"Is this component already built?"

"Do I need to build this myself?"

"Is this a Design System component?"

"Is there documentation or links to where I can find/use these components in code?"

This is where I've been experimenting with Figma dev resources. They provide a great way to add supplemental links to your Figma components to help answer these questions. Not only are they useful on their own, but they also encourage developers to use Dev Mode, which can help them learn more about its features. Which in turn, will likely improve the design and developer process and communication — that's the goal, at least. Especially if your organization is already paying for Dev Mode seats. May as well put them to good use!

With dev resources in place, developers can view your designs in Dev Mode and click through the components. When they come across a component with available resources, they'll see the links in the Dev Mode panel. The panel gives them more information and resources around implementation. I find dev resources especially helpful for Design System components, showing how to assemble smaller building blocks together to build larger parts of the UI.

You can manually add dev resources to any component via Figma's UI, but I believe making code the source of truth and using their API is a slightly better process. Admittedly, both paths are laborious and time consuming, but once it's all in place, your consumers will appreciate them. And will hopefully be low maintenance after the initial investment.

But having them defined in code means that when changes are made to a component via a pull request, the developer can also update the dev resources that would be helpful to Design System consumers in the same PR. It means designers aren't manually adding resources to components without developers knowing and gives Design System developers more control and insight on how to best fulfill the needs of other developers using the system.

So how do we write these resources to Figma? Their API.

Figma has great documentation on their /dev-resources endpoint.

By keeping code as the source of truth, it means we can programmatically create, update, and delete resources. You can check out the code I wrote for this process.

But here's the gist:

• Fetch all existing resources from Figma's API.
• Keep a list of resources in code associating the Figma node ID to the links we want associated to that node/component.
  • We link to Storybook and the component's source code in GitHub.
• Using the local list of resources as our source of truth, compare against the ones returned from Figma's API. Bucket them into new resources, resources to update, and resources to delete.
• Hit Figma's endpoints (POST, PUT, DELETE) with these bucketed items.
  • Create (POST) and Update (PUT) allow for batching node IDs, but deleting does not. The link I have above has some delays to ensure you don't get rate limited. If this happens, you'll get a 429 response status code and have to wait a while before making more delete requests.

With dev resources in place, your consumers can use Dev Mode to get more information about the Design System components and how to use them in code via your documentation. It'll help ease the design to development handoff, by providing more information to your developers.

Wiring up Code Connect is up next for me. It's a bigger fish to fry. So sit tight and I'll share my experiences there as well!

Want to sync more things between Figma and code? Check out my syncing Figma variables to CSS variables article.

At the end of that article, I floated an idea Haley Ward and I had cooked up. A few days later she wrote some GitHub Actions to prove it out. I'm happy to report back that it's generally working as expected.

But I'm also here to write about another solution. One that my team adopted over in Glide Core, the Web Component Design System from CrowdStrike. All thanks to clintcs for working through all of this and implementing it, it's really nice!

As a quick recap, the main issue around Playwright's visual regression testing is cross-OS compatibility. For example, you're developing on a Mac, CI is in Linux. When you check in your images and let CI run, there will be a pixel diff leading to failing tests—even if there were no visual changes.

You could adjust the pixel diff threshold to account for this, but this could mean you're missing out on real changes you actually want to be notified about. When it comes to Design System work in particular, this is crucial. Feel free to read my other article for more information if you're curious.

Similar to Haley's solution, CI has to be the source of truth. You can still run the Playwright tests locally, but don't check in any of the images it generates. We push everything over to CI.

This process requires access to a storage mechanism for the images Playwright generates. AWS, Cloudflare, or any other provider will do. We use Cloudflare for open source projects, so I'll be using/saying R2 from here on out.

We also deploy Playwright's test report and add it as a comment on the PR. This helps with our review process. A reviewer of a PR will review the code, view the changes in Storybook, and review the visual test report.

From a high-level, here is how we solved the visual testing problems described in the other article:

• Store baseline images from Playwright in R2.
• On PR creation, fetch the baseline images before running your tests.
• Run your visual tests.
  • Because your baseline was established from R2, the PR opened will compare against the baseline on main.
  • We leverage sharding to speed up the process.
• Deploy the test report (optional).
• Approving the PR is approving the visual updates that come with that PR.
  • Rather than having an explicit "I approve of these visual updates" on top of approving the PR itself, Clint had the great thought that approving the PR means approving everything in that PR - the code, any visual updates, all of it. This greatly simplifies things.
• On PR merge to main, update the baseline images in R2 to reflect these changes.

We added a merge queue to prevent issues with multiple PRs going in at the same time. Without a merge queue, you could clobber the baseline images by mixing up the order of when PRs merge. A merge queue ensures only one PR is merged into main at a time. This allows for the baseline images to be fully updated before moving on to the next main merge.

If you'd rather read the code, check out our workflows here. The power of open source!

Hopefully this article helps save others time and effort when they want to add visual regression testing to their project.

I've been working on Glide since November 2023 at CrowdStrike. We've made a lot of progress and I'm excited to see where we'll be this time next year. There's a lot I could deep dive on, but I thought this article could start with a high-level overview of some of our decisions, values, and technology. I'm hoping to write more around the points listed below in the near future. Stay tuned!

I've already written about this pretty extensively, but Web Components are great due to interoperability. CrowdStrike is a large organization and supports many different tech stacks. Rather than having to write a Design System for each framework we use, we can leverage Web Components to write components once and use them everywhere.

We make heavy use of Design Tokens to allow consumers to set their own theme for components. By default, we ship with our product themes of light and dark modes. These are all driven by CSS custom properties, or CSS variables. These variables are considered part of the public API of each component.

To keep things in sync between code and design, we have a script that pulls all of our variables from Figma and generates CSS variables from them. You can read more about this process. Following this pattern allows us to update all tokens with a script and continue to bridge the gap between design and development. As design updates tokens on their end, we run a script to update the code side of things.

I'm actually in the process of migrating to new semantic tokens for all of our components that align with our reworked Glide Figma UI Kit. You can check out the linked PR and see how our work progresses over time. I'm looking forward to getting this in!

We do a lot to help push folks in the right direction around how our components should or should not be used. Consumers sometimes do crazy things in an attempt to get a component to work a particular way. Sometimes it's due to a design going off the known path. Other times it may be to meet a deadline. Sometimes folks just don't know what they don't know.

Our team has seen this so go wrong so many times. We started coming up with ideas on how to help prevent these types of scenarios. They're costly and create technical debt for everyone involved. The reason we care so much about preventing misuse is because we want to limit the amount of technical debt generated by misuse. It adds up quickly if you don't keep tabs on things!

Rather than folks hacking components together to meet a deadline or to fulfill an incorrect design, our guardrails turn these situations into conversations rather than non-scalable work arounds. Does this require more time? Yes. But it's our job to understand these snowflake use cases, determine if the existing Design System components can fulfill their requirements instead, and either adjust our components or provide guidance on how they can accomplish their goals outside of the Design System.

Why are they wanting a component to act that way? Can the existing component work for their use case? How frequently does this pattern show up through other parts of the products? Do we see this being a new pattern throughout?

We don't want to block product teams from building what they need, but we also don't want them to misuse our existing components and then be surprised-Pikachu-face when things break with an upgrade. We also don't want to put crap in the Design System.

It's a delicate balance. But we think we've found a sweet spot for it all. Here are some ways we prevent misuse.

Closed shadow roots seem to be somewhat controversial, but for a Design System I'm a big believer that it makes sense. Our components should be treated as black boxes - they receive inputs via attributes, properties, and methods and render DOM. We want our Input component to be treated like the native <input />. Folks shouldn't need to dip their hands into our cookie jar to get things to work — instead use the public API of the component, just like you do with native. If that's insufficient, then it could be a bug or an improvement on our end. Once again, rather than hacking around things, let's chat!

If you're interested in reading more about my ramblings on this topic, you can here. There are some issues with testing around closed shadow roots, especially when it comes to Playwright, but that's why we open up the shadow roots up in test environments. The key is that we don't want folks mucking with our internals in production code.

For components like Menu, we expect Menu Options. Those Menu Options should be either Menu Buttons or Menu Links. Nothing else. These components have design guidelines and UI/UX requirements established by our Design Architects.

Because we only expect a Menu Button or Menu Link as children of Menu Options, we can assert that's the case. If someone puts something random in the Menu Options slot that we don't support, we throw an error in development mode. This goes back to my point above — if someone needs something else, it turns into a conversation rather than random content that may not fit the designed vision.

Some folks ask "why throw instead of log"? Logs get ignored way too frequently. Components throwing during development are much more likely to draw attention to the problem. So that's what we do.

Lit doesn't expose a way to mark a reactive property as required and enforce it, so we wrote a decorator to do it for us. Use cases for this are mostly around accessibility — we want folks to be forced to provide things like labels. Of course, they can provide garbage, but we always assume the best intent.

We don't expose any CSS parts (except for a few internal uses) from our components. Instead, we rely on CSS variables as part of our public API. I wrote about this previously as well. We don't want folks to completely override the styling of our components, only what we expose via CSS variables so that the overall UI/UX is maintained. Folks are simply slapping a different coat of paint on things as needed.

Because all of our decisions come from Design, we can get away with this. So far it seems to be working out very well, mostly because we don't need a high level of customization with our components — we support the known cases we have, and that's it.

Our components use an @final decorator. This decorator prevents folks from extending our components (using extends). We don't want people extending them because although it may work, it could be a can of worms when it comes to support and upgrading. Instead, we prefer product teams to use our components as-is.

If that doesn't work for some reason, we chat with them one-on-one to learn more about their use cases. If we recognize this requires a snowflake component that is close to another one of ours, we work with them to get the shared functionality they need, decorate the component for tracking, and they're on their way.

Over time, we check in with these different groups that are making these kind-of-like-this-Design-System-component-but-not-quite and assess. Is this component being used frequently across the same or different products? Is it really a snowflake? Should this functionality go in the base Design System component?

This is all in the name of following Josh Clark's ship faster by building design systems slower. Developers these days are too obsessed with creating abstractions for everything way too early. Sometimes letting things grow organically, seeing where they go in a few months, and for the short-term copy/pasting some logic is worth the tradeoff over an unnecessary, unwieldy abstraction.

One of my favorite parts about popping into a repository is a consistent developer experience. I love not being able to tell who wrote which file. I like popping into one component file, reading it top to bottom, popping over to a second component, and seeing similar patterns throughout. This makes following the codebase and contributing to it a lot easier. I really enjoy things being uniform, following the same patterns, and being laid out as similarly as possible.

If you're a designer reading this section, you probably have similar feelings around how Figma files are structured.

Custom ESLint rules go a long way. We use Stylelint, Prettier, Stylistic, existing ESLint rules, and our own ESLint rules. Looking to write your own ESLint plugin? You guessed it — I wrote about this last year and here's the link. We automate as much as we can.

Our current documentation uses Storybook and focuses on Component APIs. We have larger plans in motion to build a more full fledged documentation site. Due to following native as closely as possible, our components shoud feel familiar to most folks already. I'm very impressed with Playbook by eBay and other documentation sites and hope we will get there one day.

We use Web Test Runner at the moment for all of our tests. We like that it tests the components in a browser, like a user would interact with them. We have considered switching over to vitest's browser mode, but we still think it could use some improvements. We also have over 1,000 tests to migrate. We'll continue to review for the next few months, but Web Test Runner is working well for us at the moment.

We have a 100% test coverage bar, which is maybe controversial to some. You can read my thoughts on it here. It seems to be working out well for us!

We're in the process of adding visual regression testing as well. There are some documented limitations with the current tools, but I'm excited to give some of those proposals a try. We will see how things develop! This is being actively worked on at the moment, and I'm sure it's something I'll write about once we land on something that works well for us.

I initially had this section at the top of the article, but figured maybe it'd be better towards the bottom. If you've stuck with me thus far, thank you! Let's dive into the principles that help us make decisions around the Design System.

• Design Architects drive our roadmap.
  • We have Design Architects that have all of the context of products being built with Glide. They understand the product flows and how our Design System building blocks should work on the micro and macro scale. We allow these Architects to drive requirements and our roadmap for building components. We have back and forth on features and functionality, but they own the UI/UX of all components and we build them to their specifications. Each Pull Request with visual or experience updates also goes through a Design Review Process before we merge the components into main.
  • Having folks in this role ensures that our components are being built to help speed up product development, while also ensuring the best experience for our users. It also allows for this group of designers to keep tabs on all of the designs currently being built to help identify patterns and room for improvement.
• Our users expect consistency in our components when it comes to UI (user interface), UX (user experience), and DX (developer experience) perspectives.
  • We rely on the Design Architects for the UI/UX consistency piece.
  • From an internal developer experience perspective, we enforce consistency with ESLint, Prettier, Styelint, and Stylistic when it comes to being internally consistent. I described this above in uniformity.
  • Externally, our customers/users expect attributes, properties, and methods to be consistent.
    • How we name attributes, properties, and methods should be identical if the ultimate action is the same across multiple components (e.g., a tooltip opening via an open attribute is the same as a Drawer, Modal, Dropdown, or Popover opening, so the attribute should be named the same across all of these components).
• We follow native as much as possible, where it makes sense, and document when and why we need to break from native behavior.
• We leverage the platform rather than using third-party libraries when we can. We are okay with progressive enhancements when browser support is lacking.
• We ensure our components are accessible and respect user motion preferences.
  • We've got quite a bit of animation in comparison to other Design Systems. If folks want reduced motion, we turn them off.
  • We have an accessibility engineer on our team to help with all-things-accessibility.
• We always "tend to the garden" and make things nicer than we last left them.
  • We're constantly updating the codebase to follow newly established patterns and apply learnings over time.
• We prefer consistency over flexibility.
  • Rather than being infinitely flexible for all sorts of use cases, our components are laser focused on the known use cases. By being more consistent, it makes decisions a lot easier. It also makes the components easier to reason about. By adding flexibility, it can lead to inconsistent experiences and misuse. Instead, we prefer locking things down as much as possible. We limit flexibility in favor of consistency.

These principles help us make decisions about our Design System. Like all things, we revisit them and decide if they're serving us well, need to be amended, or completely removed. As time goes on, we continue to improve the process.

That's all I've got for now. Go give Glide a spin and let us know what you think. Take a look at our source code. Feel free to ask me questions on Bluesky or LinkedIn. Until next time!

And it looks like they aren't letting off the accelerator. Interop 2025 is looking great. Their dashboard can be found here. I'm really excited about everything on the list, but in particular I'm most excited about anchor positioning and view transitions getting support across all browsers.

Anchor positioning will help me build tooltips and popovers without floating UI. View Transitions will help with animations and making the web feel more like native apps. This example is one of my favorites — this is the type of interaction you see on a mobile device. Same for this credit card example. Danny Moerkerke did such an excellent job with these and posted them on codepen (thank you!). These are SO GOOD! And exactly what I'm excited about with view transitions.

Another thing I'm interested in for this year is the Navigation API and how it might change the way we build web apps in the near future. It doesn't necessarily affect me much day to day in my current work, but I'm really interested to see how it develops and what changes come from it.

And these items are only from Interop! There is a ton of work going on that isn't on this list. With Custom Elements / Web Components in particular, I'm really excited for Scoped Custom Element Registries, cross shadow-root aria, and many other enhancements. Temporal is another thing I'm very excited about — dealing with dates, times, and timezones in JavaScript is such a pain, but Temporal is promised to be a huge improvement and is coming soon™. I'm super pumped for customizable Select as well.

I'm very thankful for everyone doing the work to make web tech better every year. Thank you all! And I can't wait to see where we're at with things this time next year.

Here are some things I've reflected on today around 2024.

In 2024, I became the lead of 7 full-time engineers working on a new Web Component based Design System using lit. My team and I threw ourselves into the deep end, learning Web Components in late 2023. I'm really proud of what we've built. I'm looking forward to open sourcing it in Q1 of 2025.

I also got promoted to Senior II this year at CrowdStrike (their ladder is: Eng I, Eng II, Eng III, Senior I, Senior II, Principal). This year I learned how important it is to take ownership of big problems. Even if you're wrong or make a mistake, the fact that you own a problem and are willing to iterate towards a solution goes a long way.

This is one piece of advice I'd give anyone looking to advance their career - if you hear of a problem at work that piques your interest, don't be afraid to sign yourself up to solve it. You'll learn a ton. Working with different stakeholders and being the "captain of a ship" provides a lot of risk/reward. It's not always sunshine and rainbows, but it definitely helps advance your career and widens your impact at an organization.

Now on to some personal stuff...

I wrote (here!) at least once a month since February. Check out my previous articles if you're interested! I really enjoy it. I hope to keep it up in 2025, but maybe not as frequently.

• Web Components 🤝 Design Systems
• Roaming Shapes for Empty States
• Productize Your Design System
• Improving
• Collecting Feedback & Measuring the Success of a Design System
• Driving Consistency with Custom ESLint Rules
• Web Components for Framework Developers
• Closed Shadow Roots for Design Systems
• Design System Code Coverage
• It's Time to Disrupt Visual Regression Testing
• Managing Releases with Changesets
• Syncing Figma Variables to CSS Variables

I started taking my health more seriously. I went to the doctor more often for longstanding issues or concerns I've had based on my family history. I'm getting older, and unfortunately I can begin feeling it.

Gaming kind of fell off for me in 2024. I played Final Fantasy VII Rebirth and really loved it, but no other games really pulled me in. I'm not sure if I'm getting older and less interested in them, or if it was just a slow year for gaming. I assume the latter. In the last month I have been playing Marvel Rivals though, and that's been great! I'm looking forward to Death Stranding 2, Intergalactic: The Heretic Prophet, and a new title from Sony Santa Monica.

Arcane season two was amazing. It is definitely one of my top 5 television shows of all time. I thought Fallout was excellent too. I loved the humor and vibe it had throughout. I watched Sonic 1, 2, and 3 this year and was blown away by how much I actually loved it. I think it's my favorite video game adaptation for a movie... ever? In 2025, I'm looking forward to Severance season two and The Last of Us to continue.

When it comes to music, I'm still listening to a lot of Sleep Token. I recently started listening to Bilmuri, despite hating country, but now I think I may like it. Here are my top artists according to Apple Music:

1. Bad Omens
2. Glass Animals
3. Sleep Token
4. Bilmuri
5. Falling in Reverse
6. Low Roar
7. Nobuo Uematsu
8. BABYMETAL
9. Disembodied Tyrant
10. Bluey (lol)

This year was awesome for music. So many great songs. It was next on the list, but holy shit, Arcane's season two album was SO GOOD! So many catchy tunes.

Disembodied Tyrant is probably one of my favorite bands now. Musician Mansion Season Two was great - I want more! I think I may start playing guitar again, but we'll see. I always talk myself out of it, but I think it'd be fun to get back into it again.

We took a vacation to Disney World earlier in 2024. We drove down to Nashville as well, which was fun. As a family, we've spent a lot of fun time together and really enjoyed each other's company. I'm looking forward to more family time in 2025, and hopefully some more vacations!

I dropped Twitter after Elon took over and haven't had Facebook since 2017. I've been pretty anti social-media for a while now, but Bluesky is feeling like old tech Twitter again. I'm having a great time. I hope it stays this way! You can find me here. I'm hopeful that Bluesky can remain awesome, but I'm also ready to drop it at any moment.

Now that my son is four years old and I have a bit more free time on my hands, I started fixing more things myself rather than paying someone. For example, fixing some drywall and painting, caulking, doing yard work, and the like. I've gotten more comfortable fixing things in our house, which has been great. It turns out a lot of it is pretty easy if you watch a few YouTube videos and have the right tools. It's funny to see the progression of "I have no idea what I'm doing" → "oh, I think I'm doing it" → "shit, I messed up" → "omg I did it!".

Am I a real dad now?

Overall, this year was great and I'm looking forward to 2025. I can't wait to see what our little family ends up doing next year. I'm looking forward to work and seeing how our Design System grows. I'm hoping to pick up a hobby (hopefully back to guitar) and gaming some more.

I'm hoping to spend more time with friends and family. Over the past four years, I learned a lot about prioritizing time with folks you care about as they won't be here for forever. It's also good to get face time with people, despite me becoming a bit reclusive the past few years.

Onward to 2025 🫡

This article originated from a post I did over on Bluesky. David Darnes suggested I write a blog post about it, so here we are (thank you for the suggestion!)!

Generating your CSS variables from Figma variables ensures you're always in sync with design. Once you have it in place, you can run it via a cron job, or as a manual script. It removes the manual, laborious process of poking around Figma's UI and copy/pasting the variables into your CSS. Instead, run a script and let the computer do it! There's definitely an open source opportunity here to do a lot of the "token processing" for you. But we'll get into that another time.

Maybe you're using primitive and semantic tokens? Or maybe it's a wild west with how your variables are defined? No matter how things are structured, we can still map your tokens to CSS variables.

Update March 16th, 2025: If you prefer looking at a PR instead, here is one I recently did.

Update Feb 20th, 2025: Turns out that Figma has a FigJam file outlining a lot of this process. I had no idea when writing this article! Their guidance doesn't handle recursive token lookups, but it's pretty darn close to what you probably want/need. You may be able to use most of this repository, or at a minimum, use it as a guide! If you'd like a bit of a deeper dive, please continue!

To get the variables out of Figma, you can hit their REST API directly. I've been using the local endpoint as described here to get all of the variables from a given file.

You can use the published variables instead if you like, and the response is slightly different. Local gives you both local variables and remote, so this normally works best for situations I've been in.

You can fetch the variables in node, but here's how you'd curl it if you want to see what the response looks like. You pull the file ID from the URL.

curl -X GET \
  https://api.figma.com/v1/files/YOUR_FILE_ID/variables/local\?scopes\=file_variables:read
  -H 'X-FIGMA-TOKEN: YOUR_FIGMA_TOKEN'

You'll get back a big ol' JSON blob to parse through that is in the following shape.

{
  "status": Number,
  "error": Boolean,
  "meta": {
    "variables": {
      [variableId: String]: {
        "id": String,
        "name": String,
        "key": String,
        "variableCollectionId": String,
        "resolvedType": 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR'
        "valuesByMode": {
          [modeId: String]: Boolean | Number | String | Color | VariableAlias,
        }
        "remote": Boolean,
        "description": String,
        "hiddenFromPublishing": Boolean,
        "scopes": VariableScope[],
        "codeSyntax": VariableCodeSyntax,
      }
    },
    "variableCollections": {
      [variableCollectionId: String]: {
        "id": String,
        "name": String,
        "key": String,
        "modes": [
          {
            "modeId": String,
            "name": String,
          }
        ],
        "defaultModeId": String,
        "remote": Boolean,
        "hiddenFromPublishing": Boolean,
        "variableIds": String[],
        "deletedButReferenced": Boolean,
        }
      }
    }
  }
}

Here is where you can put on your data processing / computer science hat. We need to associate the name of a variable with the raw CSS value by iterating through the keys in this large object.

variables in this response are pretty self explanatory. They are the raw variables from Figma. This houses all of the CSS values you'll need.

variableCollections on the other hand, you may not be familiar with as a developer.

A collection is a set of variables and modes. Collections can be used to organize related variables together. For example, use one collection to localize text in different languages, and another collection for spatial values.

— Figma's docs

The collection is specific to how your team organizes your variables. For example, maybe one collection is for colors related to data visualization, while another is for font sizes.

If you are using variable modes for light and dark themes, there will be a variable collection in here that will help you identify if a particular color in variables belongs to "light" versus "dark" mode. It also lists all of the variable IDs that have those modes under variableIds.

As you are parsing through this data, you'll want to keep track of what the name of the token is and the raw CSS value by iterating over these things. I like storing this information in a JavaScript object/JSON.

Here's a made up example of a variable collection from Figma's API supporting both light and dark modes.

"VariableCollection:some-long-id": {
  "modes": [
    { "modeId": "1", "name": "Dark" },
    { "modeId": "2", "name": "Light" }
  ],
  "variableIds": [
    "VariableID:1",
    "VariableID:2"
  ]
}

We've got two modes: one for "light" and one for "dark". You'll see there's also an array of variableIds.

If we pull up VariableID:1 from that array, you'll see something like the following. Here we have a background/primary semantic token that we'd like to export.

"VariableID:1": {
  "id": "VariableID:1",
  "name": "background/primary",
  "valuesByMode": {
    "1": { "type": "VARIABLE_ALIAS", "id": "VariableID:5" },
    "2": { "type": "VARIABLE_ALIAS", "id": "VariableID:6" }
  }
}

We can pull the name of the token from name, but to get the value we need to look into valuesByMode. Notice how it is "by mode" — yup, we've got two modes, a light and dark mode, so we have two valuesByMode defined here.

The valuesByMode["1"] key refers to the modeId above, which is DARK. The valuesByMode["2"] key refers LIGHT. So background/primary has two values, one for when in light mode and another for dark mode.

Oh no! A VARIABLE_ALIAS? What's that? It's a reference to yet another variable. Depending on how your designers have setup variables, you may have deeply nested references. In your data parsing, this complicates things slightly, as you don't have access directly to your color value. For this, you'll need to follow the VARIABLE_ALIAS trail.

If we follow VariableID:5, we get to our raw color value (in rgba). In this made up example, the Designer Tony has associated the gray-900 primitive token to background-primary in the dark mode.

"VariableID:5": {
  "id": "VariableID:5",
  "name": "gray-900",
  "valuesByMode": {
    "random-id": {
      "r": 15,
      "g": 23,
      "b": 42,
      "a": 1
    }
  }
}

And the Light Mode definition would be defined as well. Designer Tony has associated the gray-100 primitive token to background-primary in the light mode.

"VariableID:6": {
  "id": "VariableID:6",
  "name": "gray-100",
  "resolvedType": "COLOR",
  "valuesByMode": {
    "random-id": {
      "r": 241,
      "g": 245,
      "b": 249,
      "a": 1
    }
  }
}

So that's following the design token trail all the way down from a semantic token to an alias to a primitive token. You'll need to keep track of how these semantic tokens reference the primitive ones. Once again, I typicaly store it in a JavaScript object or write it to JSON for convenience.

Now repeat this process for every token! Ah, recursion and loops. Gotta love it!

After going through above, you'll have an object that looks something like the following.

{
  "light": {
    "background/primary": {
      "value": "gray-100",
      "type": "COLOR"
    }
  },
  "dark": {
    "background/primary": {
      "value": "gray-900",
      "type": "COLOR"
    }
  },
  "primitive": {
    "gray-100": {
      "value": "rgb(241 245 249)",
      "type": "COLOR"
    },
    "gray-900": {
      "value": "rgb(15 23 42)",
      "type": "COLOR"
    }
  }
}

Awesome! Now all of your Figma Variables are in a format you can use to generate your CSS variables from. Before doing that, let's discuss why you might want to adjust some of these values before pushing them over to CSS values.

You may notice that Figma provides rgba for color values. You may want to use hex or something else. With the power of JavaScript, you can do whatever you want here! For the rest of the article, for simplicity, I'll keep rolling with rgb(), but know that hex, oklch, or whatever you want to support is an option, you'll need to write the code to do these conversions.

When exporting non-color token values, the resolved type might be FLOAT. A lot of times these are for pixel values. I prefer converting these values from pixels to rems for most cases and accessibility.

For the names of each token, you likely want to follow the CSS Variable syntax. So rather than background/primary, you probably want --background-primary instead. Maybe you even want to add a prefix in there to differentiate between Design System tokens versus application level tokens (e.g., --ds-background-primary). This type of conversion can happen wherever you see fit. Either during the above process, or in the next step.

Now that you have all of your names and variables in a nice format, you can write them to CSS files directly.

Depending on how you want to structure your files, you could have separate primitive and semantic files.

/* primitive.css */
:root {
  --gray-100: rgb(241 245 249);
  --gray-900: rgb(15 23 42);
}

/* semantic-dark.css */
:root .dark {
  --background-primary: var(--gray-900);
}

/* semantic-light.css */
:root .light {
  --background-primary: var(--gray-100);
}

If you only want to expose your semantic tokens and not your primitive ones, you can skip over them completely by writing the raw primitive value instead.

/* light.css */
:root .light {
  /* Value is derived from `--gray-100` */
  --background-primary: rgb(241 245 249);
}

/* dark.css */
:root .dark {
  /* Value is derived from `--gray-900` */
  --background-primary: rgb(15 23 42);
}

With all of above in place, you've got all you need! Obviously I oversimplified a lot of this, but hopefully this gives you a starting point and a decent understanding to start diving in yourself.

Every use case is slightly different, so I mostly wanted to plant the seed that you can sync a lot of things from Figma and into code using their API. The Figma API is very powerful and probably underutilized with most teams.

Above I touched on an opportunity to handle some of this heavy lifting in open source by providing a package that'll fetch your variables and write them to a JSON object. Then you'd need to take that object and figure out how you'd want to structure your CSS files. I have nothing to share quite yet, but watch this space and something may pop up here soon™.

Overall, keeping Figma and code in sync can be a manual process. But it doesn't have to be! By keeping our Figma and CSS variables in sync, it ensures we continue to bridge the gap with our Design Systems between design and engineering. As always, thanks for reading. See you soon!

Want to sync more things between Figma and code? Check out my syncing Figma dev resources article.

Yonatan Kra over on Bluesky mentioned:

Have you thought of converting the figma output to a json and then using style dictionary to convert it to css? It has the added benefit of then being able to convert it to multiple formats (like native mobile stuff if your DS needs to support that) or multiple theme versions. WDYT?

Absolutely! I actually had written this in the initial article but ended up removing it to keep this scoped to CSS variables. You could write these Figma variables to Style Dictionary and then get multi-platform design tokens. This could be huge for some Design System teams.

More from David Darnes as well

I suppose vanilla js would be more performant, but Style Dictionary means you can leverage their well documented API. Plus as Tony said you can generate all distribution formats. In the past we've done that and wrapped it into a single npm package

Style Dictionary would also allow you to create a Tailwind config, so that you can use all of your tokens with TailwindCSS. Style Dictionary opens the door to a lot of great ideas if you want more than just CSS variables!

I've been using Changesets since 2022 and believe it's an excellent tool to help with all of the above questions. Let's dive in.

"A tool to manage versioning and changelogs with a focus on multi-package repositories".

Changesets allows you to follow semantic versioning and puts you in control of when to cut a release. When you're ready, it'll publish your package(s), update a changelog file, and update the releases section in GitHub with this information.

It's very straight forward to use — simply run pnpm changeset when your change is worth calling out for consumers of your package. Check in the markdown file it added, write some helpful information outlining the changes, and then put your pull request up for review like you would normally.

Let's quickly run through an example of a Changesets workflow. Say you're building a Design System that publishes to npm.

• You put up a PR to add a new Alert component.
• You run pnpm changeset.
• You select a minor version change, since we are adding new functionality.
• You'll be prompted for a summary of the changes. We'll write something nice about our new Alert component, how to import it, when to use it, and lastly how to use it.
• It'll then ask you for confirmation of the changeset.
• A changeset is added to your changes as a markdown file.
• You commit this markdown file and push it to your branch. Let it merge in with your PR.
• Your PR merges, but it's not yet released to consumers. It's simply in main.
• Changesets collects all open changes and creates a "Release Preview" PR (you can name this whatever you want).
• This PR keeps track of all changes that'll go out in the next release. It looks at the "largest change" to determine which versioning path it should take. So if you have 2 minor updates and one patch, the next release will be a minor update. If you have a major update and 500 patch changes, it'll bump it up to major.
• Merging the "Release Preview" PR versions your package(s), creates a tag, and publishes to npm. Using the changeset markdown files you created earlier, the changelog file is automatically updated with this information. If you're on GitHub, it creates a nice release log for you too using the same changeset files.

After this process, consumers can use your changes and have all of the information they may need about the release. Since you follow semantic versioning, their expectations are properly set with each version update.

If all above makes sense, you can probably stop here and go give it a try — otherwise, I'll ramble a bit longer about some of my favorite things with Changesets.

Semantic versioning is a key piece of building and maintaining a JavaScript package. It communicates to your consumer what happened in the release, whether it's a breaking change that may require some of their time to upgrade, a minor version update with new features they can leverage, or a patch change to fix some bugs.

Unfortunately, semantic versioning isn't always respected by library authors. This is frustrating. But for packages you own, you can ensure this is followed quite easily — especially when using Changesets. With each pnpm changeset command you run, Changesets explicitly asks you what type of change (major, minor, or patch) is in your pull request.

Follow semantic versioning. Your users will appreciate it! No one wants to be surprised with a breaking change in a minor or patch release.

Being able to decide when to release is huge. Sometimes you want to batch a bunch of changes together. Maybe you're drastically changing all of your design tokens. Or maybe you're going through a really large refactor that'll enable future features. Maybe you are rewriting a large component and you want to break the changes into separate PRs to make it easier to review, but you don't want to cut a release until you're completed. Rather than having to do feature branches, you can let everything merge into main without any worry of it being released to consumers too early.

Compare this to the semantic-release approach where it'll cut a release with every PR merge by default based on the commit message. Overall, I think Changesets is a bit simpler by collecting markdown files and tracking along with a Release Preview PR. Simply merge that PR when you're ready to release and be on your way.

Don't worry about when to merge. Instead always be shippin' / mergin'!

I really like the automated changelogs and release notes. As mentioned above, Changesets allow you to write descriptions of each change in markdown. I typically add code examples in my release notes, as it makes it easier for folks to "see" the changes.

Part of my job is to work with teams and communicate changes that go into our Design System. Putting detailed information in a changeset makes my life a bit easier, even when your documentation is really great. Now it's in the changelog, the release note, and the docs.

Want an example? Here you go - check this out.

Releases link directly to the pull request and commit(s) for each change as well. This makes it helpful for consumers to get more information and context. I dig it.

When you're in a monorepo setting, if a few of your packages are interdependent, it'll orchestrate the releases properly between all of them. This has been really nice. No more worrying about having to manually bump versions or ensure changes are in lock step with one another.

My favorite thing is that they aren't clever with how they work — there aren't any surprises if you modify their generated changeset markdown files. Things flat out work really well and it's pretty difficult to find yourself in a weird state. Accidently set something as a patch, but it should be a major? Go in and edit the markdown file and that's it. Once your changes are in main, it'll update your Release Preview. I really appreciate the simplicity with Changesets.

Using GitLab and private registries? Check out this step-by-step guide from Haley Ward.

Anyway, that's all I got! Big fan of Changesets. There are some other tools like release-plan that look really promising. I'll report back as I play with it. Thanks and see ya next time!

I think it's time the visual regression testing space was disrupted. I understand visual regression testing is an incredibly complex problem to solve, but I believe there's a clever solution somewhere on the horizon.

Update October 15, 2024: A few days after posting this, Haley wrote some GitHub Actions to implement our idea. It's a proof of concept and could use some tuning, but hey, progress!

Update April 12, 2025: I ended up writing about another solution we adopted on our open source Web Component Design System with links to GitHub Actions you can reference!

You're likely already writing unit and integration tests, maybe even with 100% code coverage, for your Design System components. How are you verifying your components visually as changes are made? This is where visual regression testing comes in.

It takes screenshots of your components with each pull request so you can be notified when something changes to a component's presentation. Did you update a CSS variable that now changes the Button's border to be red? Was that intentional? You'll get notified on your pull request and can make that decision. It's another automation tool that helps build better Design Systems.

As Design System authors, we care how things visually appear to the user. By testing only the functionality in our unit and integration tests, you're only covering one area of your work — the other area is the presentational piece. Does this component match the designs? Did you inadvertently break another component's visual presentation by making a change to shared styles?

Unit and integration testing tools don't allow for these types of assertions — they can only exercise the component. Without verifying how a component is presented, you're left with manual visual regression testing. And often times, visual bugs slip through the cracks — we are all human. We make mistakes! Why not let the robots help us cut down on those mistakes as much as possible?

What options are currently available in this space? I've listed some of the major players. There are quite a few more out there, but I didn't want this article to become massive. Let's dive in from a high level.

Chromatic is a great product. It is tightly integrated with Storybook. A personal drawback to me was being reliant on Storybook's play function to interact with a component, which sometimes leads to extra stories being written only for tests. The play function becomes massive if you rely on interactions to test different visual states.

The good news is that Chromatic now plays nicely with Playwright and allows you to do targeted snapshots. This looks pretty promising! It's especially appealing if you're already using Playwright.

It integrates well with CI. For the Standard plan, you get to test across all major browsers. Their UI looks really nice. The Enterprise option includes single sign on. There's a lot of great stuff here. Overall, Chromatic is a very solid choice, but has the drawback of being a paid service.

Percy has been around for quite some time and was bought by BrowserStack in 2020 (congrats 🎉!). I was using it back in 2017 with Toyota's Loom Design System. It has all of the advantages of Chromatic listed above. The thing I liked about it was how it met you where your tests were at.

You import their percySnapshot function. You call that function within your existing tests. You run their percy exec command to run your tests, but then that's it. It's very nice. Percy is also another solid choice, but like Chromatic, costs money.

Playwright's component testing is still experimental as of the time of this writing. Due to that, some organizations may not choose it for writing unit and integration tests, but it is great for end-to-end tests. There's no denying that!

Playwright offers visual comparisons out of the box. On the surface, this sounds great! But it has a major issue that is very well documented in GitHub issues and discussions ( 1, 2, 3 ).

Playwright and other tools have an issue with headless Chrome and an OS dependency. As an example, if you're developing on a Mac, you check in your visual regression baseline images for Chrome. Then CI runs in Linux, comparing against those baseline images taken in MacOS, and guess what? Your tests fail. Every time. What's the recommended solution?

"Your CI environment is different from local one, it's probably a linux box while your local machine is a mac. The rendering is very sensitive to the host environment (and even to whether your mac has power adapter plugged in or not), it may be that on the CI machine the page uses different fonts too. To make the visual tests reproducible we recommend generating expectations on the same machine where you run the tests. There is a also a bunch of options that allow make toHaveScreenshot less strict, you can toy with those."

— Playwright GitHub Issue

I'll chat more about this in a moment, but man, this was a bummer. At first, I was so impressed with Playwright's visual testing. Then I pushed things to CI and it all fell apart. I feel like I'm knocking on Playwright a bit too much here, but I really do appreciate everyone who works on the project and think it's really great solution! I wrote Selenium + WebDriverIO tests for many years back in 2012 and I really wish we had Playwright back then. But there's no denying the visual testing area could use some improvement, either via documentation or technical improvements.

To me, the problem with Percy and Chromatic is that it's from a third-party. Tinfoil-hat-thinking maybe, but these services take screenshots of your products, so there could be some hesitancy in working on a top-secret-soon-to-be-announced-feature, screenshotting it, and uploading it to a third-party service. Some organizations may, understandably, feel uneasy about that.

The other issue with these offerings are that even though I believe the pricing is very reasonable, it can sometimes be a no-go for approval within an organization. The manual labor involved to stop visual regressions is very costly. Engineering time, QA time, not catching a bug and letting your customer see it is embarrassing, and the list goes on. But quantifying this cost can be difficult when suggesting the org pays for a service. It's tough.

These are the two bottlenecks I've hit since 2017 when discussing visual regression testing. It's less of a technical problem and more of an organizational approval roadblock. Once again, totally understandable! Every organization operates a bit differently as far as approvals for this type of stuff goes as well.

How about Playwright? It's not uploading things to a third-party and all of the images are stored in the repository you're already working in. Well, as mentioned above, it ain't perfect either. You have to make some tradeoff decisions when it comes to developer experience.

Requiring the use of docker, as recommended in the GitHub comment above, to get around the browser/OS issue is a bummer. Docker adds complexity, especially for less experienced engineers. It can be a pain to use. You also need to ensure your local and CI images are in sync with one another.

For some, using docker may be a completely acceptable solution. Maybe you're already paying for it. That's totally fine! My issue with the docker approach is that we keep adding more technology tooling to solve a single testing problem. We keep throwing different technology onto the pile, adding new tools and complexities. It'd be nice to not have to do that in an ideal world. It'd be great if we could continue to use the existing tooling we are already familiar with.

Back to Playwright's OS issue. You could switch your CI over to MacOS boxes (macos-latest), or whatever OS everyone on your team uses, but that's not ideal for folks contributing that may not have access to that OS. For example, if your repository is a public library and your team develops solely on Mac, then a Linux user comes along, you'll hit issues when they go to check in their snapshot screenshot. There are ways around this, of course, but it's a process.

Another solution I've heard is to adjust Playwright's maxDiffPixels. Adjusting thresholds, in my opinion, is a no-go for Design Systems. We need to know when a 1-pixel border color changes. We can't adjust our fidelity bar, as it's extremely important for our work. If you're working outside of a Design System and at an app-level, adjusting the threshold may work just fine for you! But once again, in Design System land, I personally feel this is unacceptable.

Am I nitpicking? Maybe. But this has been my experience over the last 7 years.

New JavaScript frameworks pop up frequently. I'd love to see some disruption in the visual regression testing space. Maybe something out there already exists and I've missed it? Definitely let me know!

My ideal solution would be an open source (of course!), free offering that is completely self-managed. One that does not require a subscription or any payment. Although I know I'd throw some cash at an open source project if one came along!

A solution where images are not uploaded to a third-party. This completely removes the middle man situation outlined above where your top secret features are now being uploaded to some service. If you want to push your images or test reports somewhere, go for it, but you should be in control of where things will live.

A solution that doesn't require docker, or any other heavy dependencies. Adding the overhead of docker or any other containerization option isn't ideal.

A solution that meets users where their tests are at - if you've already got a bunch of tests in vitest, great. If you're using jest, awesome. Forcing folks to migrate to Playwright or Storybook testing is a big lift and an instant non-starter for many. Being test-framework agnostic would be great.

A solution that can run across all major browsers. Even across the major OSes if you'd like.

I have an idea I've been cooking up along with Haley Ward that is purely GitHub Actions based. By pushing the work solely to CI, you get around the cross-OS issues mentioned above. The thought is that you can use whatever testing framework and visual testing tool you want — Playwright, jest-image-snapshot, web-test-runner, whatever. As long as it generates some sort of report.

That report can then be optionally deployed somewhere via a GitHub Action or you can pull down the GitHub Asset yourself to view the diff. The images can be checked in to source control, or not, it's up to you. It'll rely on GitHub commments and reactions to approve or deny the visual changes. It'll block pull requests until the appropriate amount of visual approvals occur.

We'll see where we land. Maybe the above gif is me. It could be way more complex than we think and we could miss our mark. Oh well, at least we're trying! Stay tuned!

To wrap things up, visual regression testing plays a crucial role, particularly for Design Systems. It ensures visual bugs are caught early, before they reach users. Although visual regression tools can sometimes be avoided due to their cost and complexity, I'm hopeful that this field will evolve and become more accessible over time. As always, thanks for reading. See you soon!

Starting a new Design System with a focus on tests sets a strong foundation for quality and reliability. By ensuring that every piece of code is covered, teams can catch bugs early, prevent regressions in the future, and confidently refactor as the codebase evolves. This creates a culture of accountability, where developers are encouraged to write robust, meaningful tests, ultimately leading to a more maintainable and stable codebase. Just like Design Systems, it will take more time upfront, but the long-term benefits far outweigh the initial investment, resulting in fewer issues and smoother development.

For the rest of this article, I'll be honing in on Design Systems focusing on atoms and molecules. It's important to understand atoms and molecules when it comes to atomic design methodology. I'm talking about buttons, inputs, form elements, modals, dropdowns, etc., — nothing more complex than that! The higher you go up the hierarchy, and especially as you get into application code, squeaking out the last 10-20% of coverage may not be worth the time and investment. So let's focus on a micro-level for the rest of this article.

We all understand the importance of testing, but tracking code coverage has mixed opinions. I used to believe that focusing on coverage metrics could lead to writing tests simply to meet those numbers, without ensuring they were meaningful. My view at the time was that it was better to prioritize meaningful tests over coverage percentages.

However, the more I thought about this, the more I saw advantages to code coverage metrics for Design Systems specifically. As developers, writing meaningful tests is an inherent part of our job. It's entirely possible to create tests that are both meaningful and provide the coverage we need — these goals are not mutually exclusive, though they're often perceived that way. Given enough time, any developer would naturally write tests that are both meaningful and comprehensive, covering all necessary paths, because that's the right thing to do.

For Design Systems, the rationale is even more straightforward. When focusing on atoms and molecules, these components are inherently less complex than other areas of Software Development due to their hierarchy. Their code shouldn't involve extremely complex logic — if they do, you likely aren't following atomic design principles. Given this, I believe hitting a high code coverage metric is very attainable.

I thought it'd be important to touch on something before we progress further...

You may see that your team is writing crappy tests that get the coverage you are looking for, but the tests aren't doing anything meaningful like I described above. Unfortunately automation can't catch these types of problems. This is more of a cultural team issue, or maybe even an organizational culture issue. It could mean that not everyone understands the importance of tests or how to write meaningful tests. If you notice this happening, it's probably wise to pull your team together and come to some agreement on principles for testing that everyone can get behind.

For the rest of this article, I'm making the assumption that people on your team aren't writing tests only to make CI green. I'm assuming that folks care about writing tests to build better products and build confidence in the code y'all write. I'm assuming best intentions, even in a corporate environment where it may be difficult to spend the time to write tests. I'm assuming there are people who actually review the pull requests being put up to ensure a certain quality and consistency to help improve the codebase overall.

Lots of assumptions, but for folks who don't just punch the clock day in and day out and really want to build great products, this should all be pretty obvious. It's still worth noting this to frame my personal point of reference.

Alright, let's continue!

By committing to writing tests with some sort of coverage metric enabled, even when it takes more time, you're building a stronger Design System, stronger products using your building blocks, and becoming a more experienced developer. I'm not saying you should be spending all night writing tests, of course, but you should be making time throughout your regular business hours to write them. Tests lead to fewer bugs down the road. Additionaly, refactoring is a natural and necessary part of our jobs. With test coverage, developers can refactor confidently, knowing any regressions or unintended changes will likely be caught.

Let's look at an example component and how we might write some tests for it.

export interface ButtonProps extends React.ComponentPropsWithoutRef<'button'> {
  children?: React.ReactNode;
  icon?: React.ComponentType<React.SVGProps<SVGSVGElement>>;
  variant?: 'primary' | 'secondary' | 'tertiary';
}

// I'll be using clsx below.
// If you aren't familiar it's an easy way to combine multiple classes
// based on conditionals.
// https://github.com/lukeed/clsx#readme
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  (
    {
      children,
      className,
      icon: Icon,
      variant = 'primary',
      ...rootProps
    },
    ref
  ) => {
    return (
      <button
        ref={ref}
        className={clsx(
          classes.root,
          {
            [classes.primary]: variant === 'primary',
            [classes.secondary]: variant === 'secondary',
            [classes.tertiary]: variant === 'tertiary',
          },
          className
        )}
        {...rootProps}
      >
        {Boolean(Icon) && <Icon role="img" aria-hidden="true" className={classes.icon} />}
        {children}
      </button>
    );
  }

Above you have a simple Button component. What tests would you write given the code above? Take a moment to jot down some ideas and come back before continuing!

All done? Sweet! Here's what comes to mind for me:

• Verify the Button can render the children provided.
• Verify the Button can render a provided icon.
• Verify the Button applies the provided className.
• Verify the Button renders each variant ('primary' | 'secondary' | 'tertiary').
• Verify the Button can receive a ref and forwards it.
• Verify the Button spreads root properties.

To some, it may seems like a lot of tests for a simple Button. But you'd probably write most or all of these yourself anyway due to the component API provided. And guess what? You'll get 100% test coverage! So the meaningful tests you'd already be writing get you to a high code coverage metric naturally. Since we're dealing with an atom, there's not much logic, and it's mostly all markup and conditionally applying classes.

Button is one of the least complex cases, but even for more complex components, you'd want to write tests for given paths. For example, say you have a Dropdown component that relies on keyboard interaction. You'd want to write tests that verify those interactions work as expected, because if you don't, you won't be confident that your code works properly.

For UI tests, I've always looked at them as providing different inputs, receiving output, and then asserting if the output is what you'd expect. The inputs are attributes or properties, and the output is UI. Since we don't have to deal with data fetching, local storage, or complex state, it means less complexity in our test cases.

This is why I feel as though 100% test coverage for Design Systems focusing on this layer is very attainable. You care about what the output is. In application code, you may not care about the HTML that is ultimately rendered, but for Design System authors, you do. This is what we provide to our users directly, and we care about the markup we are providing, but consumers may not. So I look at Design System tests through a slightly different lens than if I were building a full application and writing tests for that.

Writing tests is a bit like brushing your teeth. We all know we should do it. But sometimes we're busy. Or maybe we'd rather be doing something else. Or maybe we're stressed out and have to take care of another thing. That's where using technology can help.

If your organization allows it, Generative AI can do a lot of the lifting here for you. For kicks, let's use our Button component above and see what tests ChatGPT would write for it.

Here was my prompt.

"Given the following React code, what would you test?"

For this Button component, you would want to test the following scenarios:

1. Rendering Tests Default Rendering: Ensure that the component renders properly without any children or icon. Children Rendering: Test that when children are passed, they are rendered inside the button. Icon Rendering: Ensure that if an icon is passed, the icon component is rendered.
2. Variant Prop Tests Primary Variant: Ensure the button applies the correct primary CSS class when the variant="primary" prop is passed (default behavior). Secondary Variant: Ensure the button applies the correct secondary CSS class when variant="secondary" is passed. Tertiary Variant: Ensure the button applies the correct tertiary CSS class when variant="tertiary" is passed.
3. Icon Prop Tests Icon Present: Test that the Icon component is rendered when an icon prop is provided. Icon Role and Accessibility: Ensure that the Icon has the correct role="img" and aria-hidden attributes for accessibility purposes.
4. ClassName Prop Custom ClassName: Test that a custom className passed to the button is correctly applied along with the default classes.
5. Forwarding Refs Forward Ref Test: Ensure that the ref is forwarded correctly to the underlying button element.
6. Root Props Spread Event Handlers and Attributes: Test that any extra props (like onClick, id, data-* attributes, etc.) passed through rootProps are spread to the underlying button element.
7. Snapshot Testing Create snapshots to ensure the component renders the correct structure and classes based on the props passed (e.g., for each variant, with or without icon). Example Test Cases

import { render, screen, fireEvent } from '@testing-library/react';
import '@testing-library/jest-dom';
import { Button } from './Button';

// Default rendering test
test('renders the button with default props', () => {
  render(<Button />);
  const button = screen.getByRole('button');
  expect(button).toBeInTheDocument();
  expect(button).toHaveClass('primary');
});

// Children rendering test
test('renders children inside the button', () => {
  render(<Button>Click Me</Button>);
  const button = screen.getByRole('button');
  expect(button).toHaveTextContent('Click Me');
});

// Icon rendering test
test('renders the icon when passed', () => {
  const Icon = () => <svg data-testid="icon" />;
  render(<Button icon={Icon}>Click Me</Button>);
  const icon = screen.getByTestId('icon');
  expect(icon).toBeInTheDocument();
  expect(icon).toHaveAttribute('role', 'img');
});

// Variant tests
test('applies the correct class for the primary variant', () => {
  render(<Button variant="primary">Primary</Button>);
  const button = screen.getByRole('button');
  expect(button).toHaveClass('primary');
});

// Forwarding ref test
test('forwards ref to the button element', () => {
  const ref = React.createRef<HTMLButtonElement>();
  render(<Button ref={ref}>Click Me</Button>);
  expect(ref.current).toBeInstanceOf(HTMLButtonElement);
});

These tests cover functionality, accessibility, and styling for the component.

Cool! I'd say those are some pretty decent tests. If nothing else, it gives you an excellent place to start.

Now I asked it how we'd get 100% test coverage.

Here was my prompt.

"Given the following React component, can you write me tests that will yield 100% code coverage?"

To achieve 100% code coverage for the Button component, the tests should cover: Rendering with default props: Check that the button renders with default variant (primary). Rendering with different variants: Ensure that the correct class is applied for primary, secondary, and tertiary. Rendering with an icon: Verify that the icon renders correctly when passed, and check accessibility attributes. Forwarding ref: Ensure that the ref is forwarded correctly. Passing arbitrary props: Test that additional props are spread to the button element. Rendering with className: Check that the className prop is correctly merged.

Here's how you can write tests using @testing-library/react and jest:

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Button, ButtonProps } from './Button';
import React from 'react';

// Mock the clsx and classes modules (assuming you have them)
jest.mock('clsx', () => (...args: string[]) => args.filter(Boolean).join(' '));
const classes = {
  root: 'root',
  primary: 'primary',
  secondary: 'secondary',
  tertiary: 'tertiary',
  icon: 'icon',
};

// Mock SVG icon component
const MockIcon = (props: React.SVGProps<SVGSVGElement>) => <svg {...props} />;

describe('Button component', () => {
  it('renders with default props', () => {
    render(<Button>Click Me</Button>);
    const button = screen.getByRole('button', { name: /click me/i });
    expect(button).toHaveClass('root primary');
  });

  it('renders with "secondary" and "tertiary" variants', () => {
    render(<Button variant="secondary">Secondary Button</Button>);
    const buttonSecondary = screen.getByRole('button', { name: /secondary button/i });
    expect(buttonSecondary).toHaveClass('root secondary');

    render(<Button variant="tertiary">Tertiary Button</Button>);
    const buttonTertiary = screen.getByRole('button', { name: /tertiary button/i });
    expect(buttonTertiary).toHaveClass('root tertiary');
  });

  it('renders with an icon', () => {
    render(<Button icon={MockIcon}>Icon Button</Button>);
    const button = screen.getByRole('button', { name: /icon button/i });
    const icon = screen.getByRole('img', { hidden: true });
    expect(icon).toBeInTheDocument();
    expect(icon).toHaveClass('icon');
  });

  it('does not render icon when icon prop is not provided', () => {
    render(<Button>No Icon</Button>);
    expect(screen.queryByRole('img')).not.toBeInTheDocument();
  });

  it('forwards ref to the button element', () => {
    const ref = React.createRef<HTMLButtonElement>();
    render(<Button ref={ref}>Ref Button</Button>);
    expect(ref.current).toBeInstanceOf(HTMLButtonElement);
  });

  it('spreads additional props onto the button element', () => {
    render(<Button data-testid="custom-prop">Custom Props Button</Button>);
    const button = screen.getByTestId('custom-prop');
    expect(button).toBeInTheDocument();
  });

  it('accepts and merges className prop', () => {
    render(<Button className="custom-class">Custom Class Button</Button>);
    const button = screen.getByRole('button', { name: /custom class button/i });
    expect(button).toHaveClass('root primary custom-class');
  });

  it('can handle click events', async () => {
    const onClick = jest.fn();
    render(<Button onClick={onClick}>Click Me</Button>);
    const button = screen.getByRole('button', { name: /click me/i });
    await userEvent.click(button);
    expect(onClick).toHaveBeenCalledTimes(1);
  });
});

Explanation: Default props test: Verifies that the Button renders with the primary variant by default. Variant tests: Verifies the correct classes for secondary and tertiary variants. Icon test: Ensures that the icon is rendered correctly with the appropriate class and accessibility attributes. No icon test: Ensures the absence of the icon if the prop isn't passed. Ref forwarding test: Checks if the ref is forwarded correctly to the button element. Props spreading test: Verifies that arbitrary props (like data-testid) are correctly passed to the button. className merging test: Ensures that the className prop is merged with internal classes. Click handler test: Simulates a user click and ensures that the onClick handler is called.

These tests should provide 100% coverage for the Button component.

So what's the missing piece our AI overlords were missing in the first prompt? Looks like testing the different variants, adding a className, and verifying one can spread properties onto it. Not 100% coverage out of the box, but not bad, ChatGPT, not bad.

And if you're really interested in maximizing the coverage, it seems totally capable of doing so by writing another prompt, as seen by directly above. And if you can't use GenAI, filling in these test gaps manually would take maybe 5-10 minutes.

"But this super edge case is so hard to test, why should I write a test for it?"

If it's an edge case you're worried about, that's exactly why testing it is so crucial. Without a test, it's far more likely to experience regressions. Additionally, without proper testing, it's easy to lose track of why a specific piece of code behaves the way it does. Writing a test provides that valuable context in a documenting way, while also ensuring we don't regress as changes are made.

With tools like sinon, you can simulate any state you need for your component, no matter how complex. If your tests are getting extremely complex, it may be a sign that your component API needs some work. Would composition help break things up into meaningful pieces? Maybe it takes a bit more time to get the last 10% of code coverage, but if you can cover all known flows, it will provide a confidence boost for your team as things change in the future.

From my experience, tests don't get written due to inexperience, lack of time, or a pressure to deliver features. It's easier to only write the code for the feature in the moment. It takes more time to write tests. But the tests are equally as important as the application code.

If you're finding you need to skip writing tests due to time or other pressures, it's important to bring it up with your manager. Increase the estimation of every task by adding complexity. Setup a strong testing culture within your team. Start tracking the number of bugs before and after having tests to present a case to management that testing is important. Bring up cases where tests saved your bacon. It's up to you and your team to uphold a strong testing culture, despite external pressures. You can do it! I believe in you!

If you're setting up a new codebase, it's important to start with a strong testing culture. Don't wait to get tests added until some future point. Right after you setup the repository, immediately setup a testing environment/framework. As time progresses, old code rarely sees tests written. It's too late at that point. By having a testing framework in place from the beginning and enforcing code coverage metrics, it'll set the standard from day one.

One argument on the internet against 100% test coverage is that the coverage metric doesn't mean your code is bug free. Of course it doesn't! We're all humans writing code — we make mistakes. Even AI makes mistakes writing code — just ask ChatGPT to write something pretty complex for you. It will likely make a few mistakes too, or not account for certain cases that are specific to your business needs.

I find this argument against the 100% coverage metric a bit silly. You obviously can still have logic bugs with 100% test coverage. You likely have a bug because you didn't account for a particular flow. When this happens, in my experience, it means you need to write more code in your component to handle this case, which guess what? Means you need to write more tests. So you'll fix the issue and write meaningful tests for this new path. And your tests will likely get you right back up to 100% coverage.

100% test coverage doesn't mean "full, complete coverage" — it means that every line of code is accounted for in some way. It's a metric. People value metrics differently. But once again, the real key to all of this is writing meaningful tests.

Teams rely on you and your Design System to sweat the details and provide high quality, well tested code. Let's not let them down!

While achieving high test coverage requires upfront investment in time and resources, the payoff in reliability, maintainability, and developer confidence makes it a worthwhile endeavor. You're likely already writing meaningful tests, and if your Design System focuses on atoms and molecules, achieving 100% test coverage is a lot more achievable than you might think! The next time you start a new Design System, try setting the coverage threshold to 100% for a few months and see what you think. Do you feel more confident in your codebase? If not, at least you gave it a try to see what it'd be like!

If you've made it this far, I thank you for sticking with me. Have a good one!

Let's talk a bit about the Shadow DOM and custom elements. Here's a great quote from MDN that describes the general philosophy of custom elements and Web Components.

"An important aspect of custom elements is encapsulation, because a custom element, by definition, is a piece of reusable functionality: it might be dropped into any web page and be expected to work. So it's important that code running in the page should not be able to accidentally break a custom element by modifying its internal implementation."

• MDN

This is what we want from Design System components as well. We want them to contain a reusable piece of functionality (HTML, JS, CSS) that can be placed anywhere and work without any external dependencies. We want to use our components in any JavaScript framework, or none at all, and ensure that application code does not negatively impact our components by breaking styling or behavior with JavaScript.

One of the big advantages of using Web Components for this is around encapsulation. Encapsulation is extremely important. It ensures that users don't get to mess with our components unless we provide knobs for doing so. Encapsulation promotes consistency. It also ensures less buggy code. MDN believes so as well.

"Without the encapsulation provided by shadow DOM, custom elements would be impossibly fragile. It would be too easy for a page to accidentally break a custom element's behavior or layout by running some page JavaScript or CSS. As a custom element developer, you'd never know whether the selectors applicable inside your custom element conflicted with those that applied in a page that chose to use your custom element."

• MDN

All of us who've worked on Design Systems for a reasonable amount of time know how important it is for changes to our components to be conversations/requests that turn into work on our end, rather than hacks on their end that immediately destroy the UI/UX or consistency of a product.

"A set of JavaScript APIs for attaching an encapsulated "shadow" DOM tree to an element — which is rendered separately from the main document DOM — and controlling associated functionality. In this way, you can keep an element's features private, so they can be scripted and styled without the fear of collision with other parts of the document."

• MDN

I believe I caught Wes Bos on Syntax.fm referring to the Shadow DOM in a very simple way: it's a private, separate DOM that's inside of the regular DOM you're used to working with. If you're still a bit unclear of what a Shadow DOM is, read through that MDN link above. It does a fabulous job. It's important to understand what a Shadow DOM is before we proceed.

Now let's talk about encapsulation a bit more for CSS and JavaScript.

• Documentation

By default, Web Component styling is encapsulated because of the Shadow DOM. Styles from your application cannot override our component's styles unless those components expose either CSS variables or parts via their public API.

Let's look at a brief example. Say your application code had the following CSS.

/* Within your application */
/* app.css */
button {
  /* We _really_ want all buttons to be red! */
  background-color: red !important;
}

And say you had a Lit Web Component with the following.

@customElement('simple-button')
export class SimpleButton extends LitElement {
  static styles = css`
    button {
      background-color: blue;
    }
  `;

  render() {
    return html`<button><slot></slot></button>`;
  }
}

Whenever <simple-button></simple-button> is rendered in the DOM, the page CSS does not affect nodes inside the shadow DOM due to the encapsulation protections. The button background color would remain blue.

Sweet. This is exactly what we want with Design System components - to make styling adjustments part of our component's public API, so that a consuming application's styles can't clobber our component styling.

We want styling to be very intentional and to allow only certain knobs to be adjusted so that the component doesn't end up looking like Frankenstein's monster. I discussed exposing these things via a component's public API already in a previous post if you're interested.

For a quick example, here's how we might expose a CSS variable for background-color to be adjusted.

@customElement('simple-button')
export class SimpleButton extends LitElement {
  static styles = css`
    button {
      background-color: var(--simple-button-background-color, blue);
    }
  `;

  render() {
    return html`<button><slot></slot></button>`;
  }
}

/* Within your application */
/* app.css */
:root {
  /* Set the CSS variable to the color we want. */
  --simple-button-background-color: red;
}

Well, we've covered CSS. How about JavaScript?

JavaScript is a bit different, in that there is a way to interact with the internals of a component when its mode is set to open.

Taking a look at the MDN example, there are some protections in place already. You can't query the internals of a Web Component by simply using querySelector or any other selection method. But you can get to them by using host.shadowRoot.querySelector as outlined in the example a bit further down.

If you use our examples from above, doing something like this won't work.

// Try to query for the <button> tag within `simple-button`
document.querySelector('button');
// > null

But if you do the following, you can.

// Query through the host's shadow root
document.querySelector('simple-button').shadowRoot.querySelector('button');
// > <button></button>

This is quite different than what we covered with CSS. With CSS, you have to intentionally expose variables or parts via the public API to allow for the consuming application to modify styling, whereas with JavaScript, you can break the encapsulation by simply targeting the host and using shadowRoot to query inside of it. What a bummer!

This is problematic, because it means the encapsulation promise we've discussed thus far is great for CSS, but not for JavaScript. But what if I told you there was a way that could help? It's not perfect either, but it's one more extra protection to keep the internals of your components private from outsiders.

"If you don't want to give the page this ability, pass {mode: 'closed'} instead, and then shadowRoot returns null."

• MDN

That's right - we can set the mode to closed for our component to restrict that access.

@customElement('simple-button')
export class SimpleButton extends LitElement {
  static shadowRootOptions = {
    ...LitElement.shadowRootOptions,
    mode: 'closed',
  };

  static styles = css`
    button {
      background-color: blue;
    }
  `;

  render() {
    return html`<button><slot></slot></button>`;
  }
}

Doing this provides a similar encapsulation as our CSS flow above. It ensures no one gets to put their hands in our cookie jar and interact via JavaScript with the internals of our components. It helps prevent misuse of our components.

If you've read through to the next paragraph, you'll notice the following.

"However, you should not consider this (setting mode: 'closed') a strong security mechanism, because there are ways it can be evaded, for example by browser extensions running in the page. It's more of an indication that the page should not access the internals of your shadow DOM tree."

• MDN

Users can programmatically set the mode back to open if they'd like, but to me this means they're signing themselves up for potential unknowns. It's a break in the contract.

To follow the philosophies of Web Components above, users shouldn't care what the internals of your component are or are doing under the hood - they use your components because they want the UI/UX they provide. Just like how you treat react-query or any other library as a black box - you insert inputs, you get outputs - you should treat closed shadow root Web Components the same way. You don't go dumpster diving into react-query - you interact with the public API directly. If you do dive into the internals and change things, you're probably doing something you shouldn't and it's a huge code smell.

"When the mode of a shadow root is "closed", the shadow root's implementation internals are inaccessible and unchangeable from JavaScript—in the same way the implementation internals of, for example, the <video> element are inaccessible and unchangeable from JavaScript."

• MDN

No one dives into the <video> element internals to interact with it. They use the public API instead. Why should our components be any different?

So how do we expect users to interact with our components if the mode is set to closed? The same way you do with native elements. Just like when you need to interact with the native <input /> element, you go through the attributes, properties, and methods. You attach event listeners when things happen. Stick to JavaScript fundamentals!

For our simple-button component above, you can interact with the element just fine with JavaScript APIs via the host.

// We use the tag name directly and don't require
// the `.shadowRoot` at all! Everything can
// go through the host element.
document
  .querySelector('simple-button')
  .addEventListener('click', () => console.log('clicked'));

// Click it
document.querySelector('simple-button').click();

// Check if it is disabled or not
document.querySelector('simple-button').disabled;

Button here is a simplistic case, but my personal philosophy is to stick to what native does. Writing a Web Component that ultimately renders an <input />? Make the API identical to the native input element. Making a Modal/Dialog Web Component? Expose the open attribute and showModal methods just like the native elements. This makes your component APIs familiar, standardized, and consistent.

You may be wondering how you access content within the closed shadow root. The answer is that Design System authors should be relying on composition. Say you have a Modal component and want to render a form inside of it.

<simple-modal label="Information" open>
  <form>
    <label for="firstname">First name:</label>
    <input type="text" name="firstname" id="firstname" /><br />

    <button type="submit">Submit</button>
  </form>
</simple-modal>

And for pseudocode say simple-modal looks something like.

render() {
    return html`
      <dialog ?open=${this.open}>
        <h2>${this.label}</h2>

        <slot></slot>
      </dialog>`;
  }

Rely on slots for compositional APIs. Because of our slot, the form element is still accessible to you via JavaScript directly because it is in the "light DOM". This means, that yes, you can interact with everything here by doing the following.

document.querySelector('simple-modal #firstname').value = 'Tony';
document.querySelector('simple-modal button').click();

The h2 rendered inside of the Modal on the other hand, is not accessible because it is inside of the closed shadow root of the simple-modal component. It's important to decide what should remain accessible versus not, but that's one of the advantages in my opinion of encapsulation.

All of this is why I believe mode: 'closed' is great for Design System components. It forces Design System authors to write public APIs that a consumer can use to interact with your components rather than them diving into the internals of your components. It'll help promote consistency and reliability. It has the advantages of Web Components, where anyone can place your Web Component on their page, no matter the framework and get a full UI/UX experience for that particular component. It offers privacy and encapsulation to Design System authors.

When building Design Systems, we want to ensure folks are using our components as they were intended. Closing the shadow root provides a ton of protections for authors. It's always better to start as the most restrictive and slowly open things up, rather than going the opposite direction and attempting to shove the genie back into the bottle later. It also promotes a good separation of concerns, between Design Sytem components and application code, which most developers should appreciate.

To summarize this entire post, I'd say: learn or relearn how to use JavaScript, CSS, and HTML without a framework.

A lot of us started learning web development this way; however, we quickly switched to a framework because that's what the industry forced us to do. We've forgotten a lot of the fundamentals. Go build a little web app with no framework and get back to the basics of web development. Because Web Components are part of the native Platform and treated as first-class citizens by the browser, remembering how to add event listeners and attributes goes a long way when diving into Web Components.

For those that don't have the time to go do this (I get it!), here's a quick brain dump from me.

The first thing you should do is go read Jake Archibald's excellent post on HTML attributes vs DOM properties then come back here. Seriously, I'll wait. It'll take you like 5 minutes. Go read it!

Attributes passed to Web Components can only be one of the following:

• String
• Boolean
• Number

Unlike in frameworks where you can pass arrays or objects, you can't do that with attributes in Web Components due to the limitations above. I know what you are thinking - why not just stringify/serialize the complex data type into a string? You do you! I wouldn't do that though. There are a few options: you can make them properties instead or think about your Web Components a bit differently to fit into "The Platform™" patterns. Would composition in your components help? Hopefully!

It's important to call out Boolean attributes in particular. In React, you may have something like the following for a checkbox.

const [isChecked, setIsChecked] = React.useState(false);

return <input type="checkbox" checked={isChecked} />;

Super convenient! Your state isChecked is a Boolean that's either true or false and it acts just as you'd expect.

Now open up a codepen and paste the following code.

<input type="checkbox" checked="false" />

The checked attribute is a Boolean type. The snippet above provided the checked attribute with a string value of false. I've asked a lot of people what their expectations are for this and the answer is normally that it shouldn't be checked.

It appears to be checked though. Why is that?

The presence of a boolean attribute applies that attribute. Simply setting checked="false" enables the checked attribute and the string value is ignored - even though it is set to "false". This is maybe unexpected given the React example above.

In the React example, we are using a Boolean value, whereas in the input example above we are using a string for the value. This is where the difference lies; however, it could be a bit confusing at first. React does some magic for you to automatically handle this case by removing the attribute when the value is falsy - how nice of them! But it could make things confusing when it comes to Boolean attributes when you're building without a framework.

So the tl;dr of this section is: if you don't want to activate a boolean attribute on a native element or Web Component, don't add it at all!

I've been listening to the new Glass Animals album and happen to love this song.

Based on the point above about the attribute types, this means you can't pass functions into components.

In React, you would maybe have something like this:

const handleClick = (e) => console.log('clicked!', e);

return <ProductCard onClick={handleClick} />;

How does that look with Web Components? Events! You attach event listeners and when those events are dispatched, your callback is called.

document
  .querySelector('product-card')
  .addEventListener('click', (e) => console.log('clicked', e));

Internally, Web Components can dispatch their own events or custom events when something happens that a consumer should be notified of. This is identical thinking to passing a function into a component, but the difference is that the component itself dispatches the event and the consumer must add an event listener for it to be notified when "the thing" happens. In Lit, this is accomplished with this.dispatchEvent.

// Within my Web Component

function onSomeEventHappening() {
  // Plain old event
  this.dispatchEvent(new Event('cool-event'));

  // Or custom events, where you can provide
  // some extra details to the consumer!
  this.dispatchEvent(new CustomEvent('cool-custom-event'), {
    detail: 'some info',
  });
}

Attach event listeners to the custom events and you're all set.

document
  .querySelector('my-component')
  .addEventListener('cool-event', (e) => console.log(e));

document
  .querySelector('my-component')
  .addEventListener('cool-custom-event', (e) => console.log(e.target.detail));

For an example of what I'm talking about, take a look at this playground.

I already wrote about the advantages Design Systems have when it comes to styling with Web Components due to the Shadow DOM. Essentially Web Components need to make styling part of their public API either via CSS Custom Properties (variables) or CSS parts. Unlike in React, your components can't accept a class or className property that gets applied as only CSS variables pierce the Shadow DOM. Instead, stick to the blessed Platform way.

Slots are great! As a Web Component author, you get to decide areas where consumers can supply their own markup and it goes in those specific locations you identified.

The slot HTML element—part of the Web Components technology suite—is a placeholder inside a web component that you can fill with your own markup, which lets you create separate DOM trees and present them together.

Say you had a header component and you wanted to expose a way to render elements either on the left or right side. You do that with slots in web components. Here's how consuming a component with slots may look.

<my-header>
  <home-button slot="left"></home-button>

  <sign-out-button slot="right"></sign-out-button>
</my-header>

The home button goes on the left, the sign out button now sits on the right. The my-header component would look something like this.

<header style="display: flex; justify-content: space-between;">
  <!-- Left side container -->
  <div>
    <slot name="left"></slot>
  </div>

  <!-- Right side container -->
  <div>
    <slot name="right"></slot>
  </div>
</header>

We're relying on CSS a bit here to simplify putting things in their respective places, but you could imagine a more complex component where custom content needs to go in very specific places. By exposing slots, you get to define those locations! Pretty cool. I dig them.

Web Components don't use self-closing tags, which is maybe a bit of a surprise if you're coming from a framework.

So in React you may have something like the following.

<MyCoolComponent prop1="Hello" prop2="World" />

With Web Components, this would need to look like this.

<my-cool-component attr1="Hello" attr2="World"></my-cool-component>

Another great read from Jake on some history here. There's also more info at MDN about void elements and self-closing tags. I could write more about this topic, but these two resources combined do such an excellent job that you should read these instead!

As time progresses, I'll add more here with amendments below. For now, that's all that comes to mind. Let me know if there's anything I missed or worth discussing! Enjoy! 👋

Here are some links that may be helpful.

• Web Components
• Custom Elements
• Custom Element Best Practices
• Templates & Slots
• Shadow DOM
• Lit Docs
  • If you'll be using Lit to build Web Components
• Lit for React Devs
  • A little dated, but still applies

If you've worked with me in the last 5 years or so, you've probably heard me harp on consistency being key to the long term success of a codebase. Consistency is extremely important in many areas of software development and UI/UX. In the UI/UX realm, your customers expect visual consistency in a product. They expect similar flows to be consistent across different areas of the product. Without it, the experience feels disjointed and your product may become annoying to use. In software development, without consistency, refactoring code is like untangling a massive, impossible nest of spaghetti while also trying to find a needle in a haystack.

One of the strong opinions I have is that I'd rather have 10 consistent "areas of improvement" in a codebase than 10 one-off solutions for that problem scattered about. It's way easier to collect the consistent patterns and arrive at an improved solution, or maybe a nice abstraction. It also makes refactoring way easier - you know of all current places doing "the thing" because you can search for that pattern fairly easily. With the one-off approach, it can be extremely difficult to track all of those use cases down. This leads to hidden tech debt. Ouch.

For the past 6 months, I've been working with an incredible team. We grew very rapidly to 8 engineers including myself. As we kept growing, it was clear to me that we needed to establish and enforce patterns in our repository to ensure we maintain a high quality bar while also ensuring the codebase was easy to contribute to. Without patterns and guidance, the codebase would quickly become chaotic. It would make it harder to onboard new engineers. Different, inconsistent patterns would pop up over time. It would make PR reviews a lot harder. Not being able to automate some of the decisions we've previously decided on lead to rehashing the same conversations with different people in different PRs.

One way I solved this was driving consistency via Prettier and ESLint rules. Automated tools are always a great place to start. Prettier formats the code, while ESLint enforces coding patterns. Using off the shelf rules are great, because it's less work for you. There are a lot of great ESLint plugins you can use like unicorn; however, you may reach the point where what you want to enforce is very specific to your codebase's needs. This is where writing custom ESLint rules come in.

In my opinion, a great sign of a well established repository is popping into it and not being able to tell which developer wrote which file. Each file follows a similar format and the patterns are consistent across files. When I look at a repository, I prefer everything following the same patterns. This happens quite a lot in large open source projects. They have so much automation and tooling in place to help drive consistency - it makes it a treat to contribute to that repository because there's less to think about.

I strongly believe custom ESLint rules are extremely helpful for any codebase. They help drive this consistency I've been harping on above. It's even better when the code provides autofixes - then the developer doesn't even need to think about how to format or structure their code. It gets fixed for them automatically by running a command!

I've open sourced a repository on GitHub at https://github.com/ynotdraw/example-eslint-plugin. It's a walkthrough of how to write your own ESLint plugin and rules. In the README, I talk through everything as best I can to hopefully share some of the knowledge I've collected. Some of it may be incorrect, or there may be other ways - this is why I open sourced it! Please feel free to put up a Pull Request if you find improvements.

Overall, consistency is very important to me. It helps a codebase from spiraling out of control. It makes contributions so much easier. It serves as documentation in a way for how the repository wants code written. It makes developer's lives easier by autofixing code for them to match the patterns we decided on as a team. It makes refactoring easier. Leaning heavily on Prettier and ESLint goes a really long way. And whatever areas software can't fix automatically, using documentation is a great solution too.

In a previous post I mentioned how you should productize your Design System. Every product wants customers - it helps them get funding and succeed. The same applies here. It's important to show the value your Design System is bringing to your customers - your colleagues. Measuring success and collecting feedback go hand-in-hand. Not only should you be measuring success, you also need the feedback from people using your Design System so that it can improve.

Measuring is hard, collecting feedback is easier.

To me, collecting feedback is easier than measuring success because it's more direct. I feel as though measuring success can be really difficult, because collecting metrics can be tricky. Reviewing the metrics and coming to conclusions without being biased is also difficult. This is exactly why I wrote this article! Without further ado, here are some ideas I've come up with around measuring success and collecting feedback.

This is where I like to start - it's similar to being in sales. The sales department's job is to interact with you and convince you to buy their product to fulfill your needs. In this case, you are the sales person meeting with your fellow colleagues and convincing them your Design System will help them at their job. Pitch the Design System to them if they aren't using it already. "Get in the field" with them. See how they are doing their work currently and offer your Design System as a potential improvement. At a minimum, see what feedback they have about your Design System. Hopefully you'll sell them on it!

One of my favorite things to do after selling folks on a Design System is meet with both designers and engineers as they work on a new product or feature. Give them access to what they need in Figma and start with the design side of things. Sit with them as they begin to work through the process of building. Ask questions along the way about their thinking and how they feel things are going. Then go do the same thing with engineers - give them access to your Design System library. Was the process smooth overall? Did it accelerate their development at all? If yes, nice! If not, you'll have some feedback to make things better for next time.

Holding office hours is another great way to measure "customer satisfaction". Having dedicated time for people to ask questions or even just hang out and talk about your Design System is a great way to spread the word about your work, while also getting additional feedback in a casual way. It's similar to above as well, where it could be a pairing session that reveals improvement areas for your team.

Another metric I like to use is measuring adoption. Before measuring adoption though, I have a piece of advice: Don't make using your Design System a requirement. It should be optional and left up to the teams building the product/feature. But why?!

Say you're at a company with an existing Design System and a group wants to spin up a new product. If they immediately reach for using the Design System, that's a huge win for your team. It means they see the value in using it versus starting completely from scratch. This is why I prefer making the Design System optional - you want it to be so good that people want to use it for every single project because it saves them time and effort.

Another good adoption metric is the case where there's an existing product not currently using your Design System. They end up adopting it. That's huge! This means that team sees the value your Design System is providing.

These are more "long term" or "long feedback loop" metrics. Not every organization spins up new products at a rapid pace. That's okay. I think it's one of those items to celebrate when it does happen though. What are some other ways we can measure adoption of our Design System that have a shorter feedback loop?

I like collecting data around how many times each component is used in a codebase (and even across codebases!). It ties into adoption, and allows you to see over time which components are leading the pack. It can help provide information later on to UX Researchers so they can have a better understanding of patterns in your products. It helps your team understand which patterns are most used across products. This is a great metric around adoption.

Collecting data for the number of components used in a project doesn't necessarily mean the Design System is successful. "Adoption" and "Success" are related, but just because someone uses your Design System, doesn't necessarily mean your Design System is successful. It does help the overall process of maintaining and developing a Design System though - it's a great way to collect additional feedback and make improvements.

If you release a new component and after a few months you notice that it's not getting used as frequently as you were hoping, that's feedback unlocked by simply keeping track of usage data. You can then figure out why that is and make adjustments.

I had brainstormed this idea with my amazing wife around 2020, but never had enough time to implement it. She ended up building something similar and it's been working out well for her team. Here's the gist:

• At some cadence, query for usages of your Design System components (using GitHub APIs, for example).
• Keep track of how many times each component is used across each repository.
• Store this data somewhere (in a dynamo table, S3, Tableau, etc.) you can run queries on it in the future.
• At some cadence, weekly/monthly, post the usage stats (it'd be ideal to build a UI surfacing this data with nice charts).
• Review the data as a team.

Collecting data allows you to ask questions. Are the numbers going up or down? Is adoption of a component fairly low? Why could that be? Does that component need additional functionality? Do folks not know when to use that particular component? These are great examples of questions that come up around your Design System - and you can only ask these questions if you collect the data!

Similar to above, but see how frequenty certain props are used for components.

If something isn't being used, you can begin asking questions about why that may be. Do the designs not call for that functionality as much as you had thought? Does it not have a good UX? Are there accessibility issues? Do people not know about it? Was this added by an engineer, but isn't in Figma, so no designers know about it?

This also helps if you need to deprecate usage of a prop at some point. You'll have the data to help you decide if it's a good idea and what the impact to users will be. Maybe you'll write a codemod to auto-migrate folks to a new property name you want to use instead. Having data around how your users are using your components is extremely helpful when it comes to maintaining and improving a Design System.

User interviews can be really helpful to get feedback on areas to improve. I suggest scheduling them with folks who have been using your Design System for a few months, at least. It's enough time where they may still remember their "I'm new" feedback, while also working with it long enough to offer suggestions on what could be improved to help their day-to-day. I also suggest interviewing folks from different levels - the more junior folks may have feedback that is completely different than the more senior people. This makes sure you cover a wide spectrum.

User interviews are great, but there's another way to get feedback as well. People love leaving reviews. Take a look at Google and Amazon reviews. But in a professional setting, sometimes people don't feel as though they can be as open or honest as when they review their cool wolf t-shirt. This is totally understandable!

Not everyone wants to tell you to your face (or via Slack) that the component you made sucks or has issues. It can be difficult for folks to bring up. But if you provide an anonymous way for folks to provide feedback, it can give a chance for those voices to be heard in a safe space.

We want all of the feedback - positive, negative, and somewhere in between. Offering many avenues to get to this information is key. I typically use a Google Form. They're quick to setup and most folks are familiar with the UI/UX of Google products already.

Does using your Design System improve an accessibility ("a11y") audit? A metric I've used in the past is the case where you introduce a Design System into an existing product. If your audit score improves, that's great. Another win for your Design System. After all, I firmly believe Design Systems should have as much accessibility baked in as possible. This topic deserves an article by itself!

There are a ton of tools to help measure accessibility in your products. Here are some I recommend:

• Follow the ARIA Authoring Patterns Guide and Practices Guide.
• Lighthouse is a fine place to begin your a11y improvement journey. If you're already using Chrome, it's really easy to use! (It also ties into my performance point below.)
• axe DevTools for Chrome is a great extension that provides a ton of great a11y information. If you're already using Chrome, it's another no brainer to install.
• axe-core allows you to write integration or end-to-end tests and verify accessibility programmatically.
• pa11y is another great tool to use that's similar to axe-core. I haven't used it yet, but I've been keeping an eye on it for a while now and have heard excellent things.
• If you're using Storybook, their accessibility addon shows a11y issues right in your story. Convenient!

Does using your Design System improve the web performance of your application? You could start by using a Lighthouse score. I'm not sure how much weight this metric should carry, but it could be interesting to see how your Design System would affect performance.

When folks begin adopting your Design System, do less bugs appear in the product? The hope would be that the application would become more stable and have less bugs over a longer period of time as adoption increases. This is another "long term measurement" that may pay off over time, but could be hard to get data from in the short term.

One case I've seen is where there's a photo upload component in a product that's shared across the application. In my case, the existing component was quite buggy, had some UI/UX issues around drag and drop, and wasn't accessible. The Design System team I was on built a new component for this use case. It handled receiving photos from the file system, supported drag and drop, supported keyboard and was friendly to screenreaders, and had a nice horizontal scroll-snap behavior. When we replaced the existing component with our new one, we immediately deleted about 5 bug tickets in the backlog.

Of course our team took the time and effort to build this component, which could have been spent resolving the bugs directly; however, at the end of our task, the Design System team provided a design approved™ component, with better UI/UX, better tests, and made it accessible via keyboard and screen readers. It could also be used across multiple features and products. The product team was also very happy we took on the work to build that particular component and increased our overall relationship with the team. That's a win in my book!

Keeping an eye on analytics for your documentation site is a great way to get information on your Design System. Are people regularly visiting certain pages? Is that component frequently used or are they having issue with that component and diving in to learn more? This is all great information to have available! Using information from interviews and the methods listed above, coupled with the documentation site information, you may learn about additional areas for improvement.

Well, if you made it this far, thank you for reading my ramblings! As mentioned at the beginning, measuring success can be difficult, but it's paramount to the success of your Design System. Collecting feedback also creates improvement opportunities and is equally as important. These are all the ideas that come to mind to me around those two areas. What did I miss? Let's chat on LinkedIn or Bluesky. Cheers!

I'm not sure I can say it any better - take it from ThePrimeagen:

I agree with his point. Improving as a developer means developing a solution, realizing it's the incorrect one, and getting the opportunity to do it again and again and again. I feel as though the industry is incorrectly against "rewriting x feature every n timeframe". Although I understand how wasteful that can seem on the surface, if you're rewriting it for valid reasons, I don't think it's wasteful at all. In fact, quite the opposite.

Obviously if you are having to rewrite it because the organization keeps firing the team that's supposed to maintain it, that's a different story. But if the original group who keeps rewriting it is coming up with better ways of writing that feature, it likely means there will be other positive impacts as well. Maybe those improvements mean cost savings, better performance, or any other increased/positive metric. If rewriting something comes with a net gain, it should be embraced. Okay, back on topic, Tony.

All that to say: it's super important to be given the space and time to make mistakes. The first solution you land on may not be correct or as great as you were hoping. That's okay! Hopefully you'll have time to improve it. Maybe you won't, but maybe you'll experience a similar problem at another company in the future. As long as you learn from that experience going forward, you'll come out ahead.

To organization leaders out there: Don't fail fast, fall fast and get back up. Encourage risk taking. Encourage trying. If you don't read the rest of this article, I encourage you to watch this video from Simon Sinek.

It can be very scary to take on the unknown, but where there are unknowns, there are opportunities to learn and grow. Rather than being afraid of taking on a task you have no idea how you'd solve, be confident in your abilities and try it. At a minimum, you'll walk away learning something new.

It can feel very uncomfortable taking on something you know nothing about.

"Why would I attempt to create a new GraphQL mutation when I know nothing about how this service works?"

Valid question. But if you complete it, you'll know how to add a new mutation in GraphQL and have a better understanding of work in a backend service. You may also come to the realization that you love writing service code rather than frontend code. That could completely change your career trajectory, all from taking a stab at a single task.

It's good to get out of your comfort zone now and then to stretch your wings and challenge yourself. You may learn more about yourself too!

Earlier in my career as I started working closer with designers on a day-to-day basis, I realized they have a superpower that developers tend to lack: receiving criticism of their work and not taking it personally. I was working with a designer friend on a new project when he pitched his designs to a few others at the company. In my eyes, the others were somewhat brutal with their feedback. I was shocked at how calm and engaged he was chatting with his colleagues about his work, right after he took a bit of a beating. He was asking clarifying questions on how the design could be improved, jotting down notes, and acting as though this was normal. How foreign to me as a developer! He just spent a full day working through the designs to be told they were all wrong and not good. And yet, it didn't bother him? How is this possible!?

I asked him how that made him feel and if that type of feedback loop was normal. I was surprised to learn that, at least according to him, yes it was normal. He then explained how it makes him a better designer and how he looks at it as just that: feedback. He gets to decide what he changes or not by taking in all of the feedback, processing it, and coming up with a different solution that he thinks is better. It goes back to the fall fast mentality above. From that day forward, I looked at feedback of my work in a completely different light by removing the personal factor from the feedback process.

Most developers can probably relate: getting Pull Request feedback can really suck. But it doesn't have to. I know for me personally, prior to the point mentioned above, receiving feedback on something I spent days on and being told "this is all wrong" was a very difficult pill to swallow. It's not a reflection on you as a person though - it just so happens that you didn't consider all of these other things your colleagues have thought of.

Imagine working in a factory building parts that have extremely tight tolerances. There's very little room for error when you're manufacturing these particular parts. If at the end of the day, someone reviews the parts you've created and throws out the ones that weren't in spec, would you be upset and take it personally? Probably not. It should be a mutual understanding that the items created must be within spec. Some items you made weren't within spec, some were. It may drive you to do better the next day. So why do we, as software engineers take things so personally on Pull Request reviews?

Instead of receiving feedback and taking it personally, look at it as a chance to improve. Ask questions. Learn more as to why someone thinks their suggestion is better. Have you considered that maybe you are wrong? Being open minded and not carrying an ego goes an extremely long way. Have a civil debate back and forth on topics you may not agree with so that you can understand the counter-arguments and then come to a path forward with your team. Additionally, being able to change your opinions on a topic as new information comes in is extremely important.

All of this is about learning and becoming a better engineer. Obviously when you're giving feedback, you shouldn't be an asshole - that's not what I'm saying. My point is to frame the feedback loop as a positive learning experience rather than one you dread. If every time you put up a Pull Request you feel anxious - ask yourself why? It's not a personal reflection of you as a human being - it's simply the work you output for the job you are paid to do. There's always room for improvement and that's okay. It's all about growing.

I was interviewing a candidate when I worked at Toyota in 2017 and I heard a response that has stuck with me to this day:

"People problems" are harder than the technical problems.

What a thought provoking statement. Sure, figuring out solutions to technical problems can be challenging, but have you tried leading a project with completely different individuals towards a goal, accomplishing it in a reasonable amount of time and at a high quality bar, while also attempting to grow the team, while also not driving each other insane? It's so hard. Everyone has different needs. Some folks are stronger in particular areas than others. Sometimes folks don't get along at all.

This is where I have a ton of respect for places that focus on culture fit rather than technical ability. The teams I enjoyed working with the most were the ones where we all got along and had a good time, rather than the teams that were full of rockstars and none of us liked each other. There's definitely an art to team building.

But even if you are on a team where you don't agree with someone, I go back to what I said above about feedback. Learn from those people and understand their view points. Maybe you think they are overly picky in Pull Request reviews - why are they that way? Are their opinions valid? Maybe it's boils down to a personality difference.

From my experience when I encountered people like this, it turned out they really did know what they were talking about. It offered me a lot to learn - it turned out that their communication style was more direct and different than mine. I was taking their feedback too personally. As I got to learn more about them and what drives them, I realized they actually were really nice human beings that did really high quality work. I also learned a ton from them. I recommend trying your best to solve "people problems" as well as the technical problems.

Learn to gel with the folks you work with. Work doesn't have to be a slog - we're all human and crave connection to some degree. Working in a team is all about alignment and driving towards a common goal. Find ways to make work more enjoyable. You may gain some lifelong friends!

Lastly, I recently participated in a DiSC assessment with my team. As most developers likely would, I was thinking: "I'm not sure this is going to be a good use of my time"; however, I walked away thinking the exact opposite. It was extremely helpful. Learning the stressors and motivators of your teammates goes a long way. Maybe large ambiguous tasks make one person extremely anxious, while for another those tasks are where they excel. Doing this assessment helps outline where folks fall in different categories so that you can work better as a team. This type of assessment is a bit of a catalyst to what I described above - you get to learn more about your team much faster than the more organic process and get to cut down on "people problems".

It's super important to ensure your mental and physical health is taken care of before anything else. Without being in a good mental and physical state, you won't be you (is this a Snickers commercial?). One recommendation I received is to say "no" more. It's important to protect your time. If you're in the position where you can decline something, and you think it'll tip you over the edge, just say no. There are obviously more professional ways to politely decline things as well.

Even simple things like someone scheduling a meeting outside of your working hours. It's appropriate to decline and say something along the lines of "is there a chance we could move this between 7am-3pm?". Or simply decline and suggest a time block that works better for you. This is one of those tips that doesn't get talked about enough in the workplace. Obviously there may be some cases where very important meetings need to fall outside of your typical schedule; however, don't be afraid to protect your time when you feel it is appropriate to.

There is absolutely nothing wrong with asking for help, but sometimes struggling with the issue for a few more hours could mean you get to the bottom of it. If you're on a time crunch and there's a fire in production that you're on the hook for - you should ask for help immediately. But if there isn't an extreme urgency, there's an opportunity for you to dig deeper on the problem. It goes back to above on being uncomfortable - not understanding why something isn't working as you'd expect is an uncomfortable feeling, but taking a step back and evaluating what could be going wrong, then digging in to see if your hypotheses are correct means more opportunities for learning and growth.

One of the patterns I was taught early on in my career was to dig through stack traces and attempt to figure out the root cause of the issue. You learn a ton by doing this and you get exposed to things you may not otherwise see. It also sharpens your troubleshooting skills. Sometimes you may find a legit bug in a library - this means an opportunity to contribute back to an open source project in a meaningful way. Other times you may hit a dead end - that's okay! You made a great attempt.

One tactic I use is going for a walk or stepping away from the problem. Continuing something for multiple hours straight and not making any progress can lead to a dead end, but sometimes an idea will come to you out of the blue if you step away for a bit. For me, my best ideas come about when I'm by myself doing a mundune task like driving or doing yard work. Give yourself a break for a moment and see if any new ideas come to mind.

When you do end up asking for help, it's important to describe the problem and also show everything you've tried. That will give whoever is pairing with you an idea of what you've thought through and tested already. Maybe it'll give them some clues as well. It also shows that you respect your coworker's time by letting them know you really are stuck. Asking for help isn't a bad thing, but it's important to feel a little uncomfortable at times to see if you can figure it out before phoning a friend.

Now onto a more technical suggestion…

If you're abstracted away from a lot of concepts at your workplace, try spinning up a side project or get on a project at work that is greenfield. I firmly believe every developer should create a new package from scratch, publish it to npm, and maintain it for some period of time. Being able to create packages on GitHub, build them, publish them to npm, setting up testing, linting, prettier, and general repository maintenance is one way to learn a lot of skills that are extremely applicable to your job in a short amount of time. It really levels you up fairly quickly.

From a high level, doing this means you'll:

• Learn the different fields in a package.json and what they do
• Add tooling to build your packages
• Setup a test framework
• Setup GitHub Actions
• Wire up tests
• Update your GitHub Actions workflow to include running your tests
• Setup up ESLint and prettier from scratch
• Publish to npm
  • I recommend changesets to help!
• Write documentation on how folks use your work
• Setup TypeScript configurations (if using TS)

All of above takes a lot of effort, but you'll walk away knowing so much more. The experience you get setting up these tools for the first time is well worth it. You'll also appreciate the tooling that is abstracted away from you at larger organizations, because you'll have a better understanding of what all is going on. Not only will you learn a bunch by doing this, it's also fun to do!

These are the things I've done to improve as a software engineer over the years. I hope this is helpful for others. Let me know on LinkedIn or Bluesky!

I'm trying to write at least once a month, so I figured I'd try a slightly different format for this topic to save myself some time. I decided to have a little more fun with it and it's a bit more loose than usual. Let me know what you think!

Productize it. That's probably the most important piece of advice I'd offer to a team or individual starting a Design System today. This goes for both startups and large organizations. You may be wondering "but why"?

If the Design System is a side project, it'll never reach its full potential. Instead, it could quickly become a burden, rather than being a jump start for designers and engineers.

Too many times at places both big and small, I've seen Design Systems start out as a grassroots effort. A couple of individuals (it's me, hi, I'm the problem it's me) get really excited about building one, so we go off and begin chasing our dreams (don't let your dreams be dreams). I don't think being a grassroots effort is a bad thing necessarily. People don't always understand the value of something until it's tangible. Simply speaking about the benefits without proof isn't enough. So you do what you must: make something tangible.

There's a lot to be said about building something and letting folks get their hands on it. It's even better when you convert people who are skeptical about your project by showing them how much your solution brings them value on a day-to-day basis.

"Oh, I don't have to build all of these components myself? I can slap these existing elements together to build a feature? Far out!".

That's been my experience building Design Systems full time since 2017. Sometimes discussing the advantages isn't the same as someone experiencing it for themselves - and that's okay! In fact, I think being able to prove your thing does what you said it would is extremely important. It's how you build credibility and trust with others.

At some point you need buy-in from leadership to ensure the Design System remains successful. Otherwise you'll find yourself getting swamped with feature work and never have time to maintain, improve, or further develop the Design System. This means you and your pals who were previously very excited about the Design System end up becoming stressed due to needing to ship things elsewhere and no longer having the time to work on it. This is the danger zone when it comes to side projects. We can fix this though! Pitch your Design System as a real product.

Not sure how to get leadership buy-in? Design Systems University has you covered with a slide deck. I was actually sent this a day or two ago as I began writing this article. Great timing!

What will productizing get you? Sustainability, stability, and focus. Pitch your Design System as a real product, because it is! Your customers are your internal users and team members. Your job as a Design System contributor is to make design and engineering lives easier. You provide the Lego building blocks and your "customers" construct a feature or product. There's a ton of value in that - you are helping the organization ship faster, at a high quality bar. It also means you can hunker down and focus, rather than bouncing around between completely different concepts.

By productizing your Design System, it means you'll also have the opportunity to form a real team around it. To me, an ideal team looks something like the following, which is pretty similar to the Design System University recommendation with a few minor tweaks:

• Engineering Manager
  • Frontend Engineers
• Design Manager
  • Designers
• Accessibility Expert(s)
  • For both Design + Engineering
• QA folks
• Researcher(s) / Producer(s)
• Content Writer(s)
• Product Owner

Looks familiar, eh? One might say, it looks similar to a product team - because it is!

By having a real, dedicated team it means the Design System can flourish. Bugs can be addressed in a timely manner rather than being thrown into an abyss that never gets looked at. New features can be added to the Design System, which further improves the lives of the people using it. Components can be properly documented and given the time and care they deserve, rather than pumping something out as fast as possible due to a deadline. Researchers can help provide data-driven metrics on your Design System and patterns in your products to help ensure you're making the correct decisions. Your applications will have visual UI/UX consistency. The list goes on and on.

That's my 2 cents on the topic! Productize it. Have a good one and see you next time! I've started my next article which will be about measuring success in Design Systems.

Adding micro animations to empty states are a great way to add a little extra detail from a UI/UX perspective. A lot of times empty states use illustrations that look quite nice already; however, adding some movement makes things more fun.

Maybe it's too subtle? Here's a sped up version.

Notice how each individual shape around the one in the center drifts around a bit? Fun! After creating one of these, it was essentially rinse and repeat. I kept rolling with this pattern for other empty states as well in this particular application, swapping out individual icons and tweaking their animations slightly. It was a good time.

So how did I go about building this?

I ended up going over to Figma and combining multiple chromicon icons (free, open source icons I helped build!) into a single frame. Once I had the frame, I exported it to a raw SVG.

From there, we can use the raw SVG and animate each individual shape using CSS. There are really awesome tools like GSAP and Framer Motion, but I like to try using only CSS before reaching for another tool. For this case in particular, making shapes move is pretty straight forward.

I ended up creating a couple of options for different shapes, as you can see, with staggered start delays and animation durations. All of them leveraged keyframes and used the translate CSS property.

You may notice the "hero" icon in the middle is a different shade than the surrounding shapes. I ended up using the stroke-opacity attribute (or strokeOpacity in React) to ensure the main icon is front and center, and the surrounding icons have a much lower opacity and are thus lighter.

The shapes roaming in this example are pretty subtle, but if you begin adding more motion in your empty states you should consider using the prefers-reduced-motion media query. If your animation duration is pretty short, you'd use this media query to increase the duration so that it reduces the amount of motion on the screen.

That's it! Pretty straight forward! I've pasted the code below for React, but you can also find a pure HTML + CSS version on my CodePen. Happy coding!

import styles from './styles.module.css';

export function RoamingShape() {
  return (
    <svg
      className={styles.svg}
      width="77"
      height="56"
      viewBox="0 0 77 56"
      fill="none"
      aria-hidden="true"
    >
      <path
        d="M46 36H32C31.4701 35.9984 30.9623 35.7872 30.5875 35.4125C30.2128 35.0377 30.0016 34.5299 30 34V20C30.0021 19.4702 30.2135 18.9627 30.5881 18.5881C30.9627 18.2135 31.4702 18.0021 32 18H46C46.5299 18.0016 47.0377 18.2128 47.4125 18.5875C47.7872 18.9623 47.9984 19.4701 48 20V34C48 34.5304 47.7893 35.0391 47.4142 35.4142C47.0391 35.7893 46.5304 36 46 36ZM33.2 36L37.4 31.15L41.6 26.3L44.8 29.7L48 33.1L33.2 36ZM35.8 21.4C36.3321 21.3998 36.8478 21.5842 37.2593 21.9217C37.6707 22.2591 37.9524 22.7288 38.0564 23.2507C38.1603 23.7725 38.0801 24.3143 37.8294 24.7837C37.5787 25.253 37.173 25.6209 36.6814 25.8247C36.1898 26.0285 35.6428 26.0555 35.1336 25.9011C34.6243 25.7468 34.1843 25.4206 33.8886 24.9783C33.5929 24.5359 33.4597 24.0046 33.5117 23.4751C33.5638 22.9455 33.7978 22.4503 34.174 22.074C34.3871 21.8599 34.6406 21.6901 34.9196 21.5745C35.1987 21.4588 35.4979 21.3995 35.8 21.4V21.4Z"
        stroke="currentColor"
        strokeWidth="2"
        strokeLinecap="round"
        strokeLinejoin="round"
      ></path>
      <path
        className={styles['animate-shape-roam-1']}
        d="M58.6785 8.26405C58.9702 7.97233 59.3659 7.80844 59.7784 7.80844C60.191 7.80844 60.5866 7.97233 60.8784 8.26405C61.1701 8.55577 61.334 8.95143 61.334 9.36399C61.334 9.77655 61.1701 10.1722 60.8784 10.4639C60.7326 10.5954 60.5601 10.6937 60.3728 10.7522C60.1854 10.8107 59.9876 10.828 59.793 10.803C59.3758 10.788 58.9142 10.6996 58.4428 10.6996M62.6069 6.53557C63.4248 7.35354 63.9338 8.42982 64.0472 9.58102C64.1606 10.7322 63.8713 11.8871 63.2286 12.8489C62.5859 13.8108 61.6296 14.52 60.5227 14.8558C59.4157 15.1916 58.2266 15.1331 57.1578 14.6904C56.0891 14.2478 55.207 13.4482 54.6617 12.428C54.1164 11.4078 53.9417 10.2301 54.1674 9.09559C54.3931 7.96104 55.0051 6.93985 55.8994 6.206C56.7936 5.47216 57.9145 5.07107 59.0713 5.07107C59.7281 5.07023 60.3785 5.19917 60.9852 5.4505C61.592 5.70183 62.1431 6.07058 62.6069 6.53557V6.53557ZM57.225 11.9174L57.2643 11.8781L57.225 11.9174Z"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
        strokeLinejoin="round"
        strokeOpacity="50%"
      ></path>
      <path
        className={styles['animate-shape-roam-3']}
        d="M18.6886 41.2523C18.4519 40.9143 18.0907 40.6842 17.6845 40.6126C17.2782 40.541 16.8601 40.6336 16.5221 40.8703C16.1842 41.1069 15.954 41.4681 15.8824 41.8744C15.8108 42.2807 15.9035 42.6988 16.1401 43.0367C16.2608 43.1915 16.4136 43.3183 16.588 43.4085C16.7623 43.4986 16.9541 43.55 17.1501 43.5591C17.5636 43.6168 18.0335 43.6099 18.4978 43.6918M15.12 38.8679C14.1725 39.5314 13.4843 40.503 13.1727 41.617C12.8612 42.731 12.9455 43.9186 13.4114 44.9774C13.8773 46.0362 14.6959 46.9007 15.7278 47.4236C16.7596 47.9465 17.9408 48.0955 19.0702 47.8451C20.1995 47.5947 21.2071 46.9605 21.9213 46.0505C22.6355 45.1405 23.012 44.011 22.9867 42.8545C22.9615 41.698 22.536 40.5861 21.7829 39.7081C21.0297 38.8301 19.9954 38.2405 18.8562 38.0396C18.2095 37.9247 17.5466 37.9388 16.9054 38.0809C16.2643 38.2231 15.6575 38.4905 15.12 38.8679V38.8679ZM19.4856 45.1026L19.4537 45.0571L19.4856 45.1026Z"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
        strokeLinejoin="round"
        strokeOpacity="50%"
      ></path>
      <circle
        className={styles['animate-shape-roam-1']}
        cx="18"
        cy="12"
        r="3"
        fill="currentColor"
        fillOpacity="50%"
      ></circle>
      <circle
        className={styles['animate-shape-roam-2']}
        cx="6.5"
        cy="1.5"
        r="1.5"
        fill="currentColor"
        fillOpacity="50%"
      ></circle>
      <circle
        className={styles['animate-shape-roam-3']}
        cx="70.5"
        cy="1.5"
        r="1.5"
        fill="currentColor"
        fillOpacity="50%"
      ></circle>
      <circle
        className={styles['animate-shape-roam-2']}
        cx="75.5"
        cy="54.5"
        r="1.5"
        fill="currentColor"
        fillOpacity="50%"
      ></circle>
      <circle
        className={styles['animate-shape-roam-3']}
        cx="6.5"
        cy="54.5"
        r="1.5"
        fill="currentColor"
        fillOpacity="50%"
        style={{ animationDelay: '2s' }}
      ></circle>
      <circle
        className={styles['animate-shape-roam-1']}
        cx="58"
        cy="42"
        r="3"
        fill="currentColor"
        fillOpacity="50%"
      ></circle>
      <path
        className={styles['animate-shape-roam-3']}
        d="M-0.000199058 28.237L9.41478 25.1779L6.23685 31.415L-0.000199058 28.237Z"
        fill="currentColor"
        fillOpacity="50%"
        style={{ animationDelay: '1s' }}
      ></path>
      <path
        className={styles['animate-shape-roam-2']}
        d="M67.8472 34.242L71.3948 25L74.242 31.3948L67.8472 34.242Z"
        fill="currentColor"
        fillOpacity="50%"
        style={{ animationDelay: '2s' }}
      ></path>
    </svg>
  );
}

.svg {
  height: 11rem;
  width: 11rem;
  color: #9ca3af;
}

@keyframes shape-roam-1 {
  0% {
    transform: translate(0);
  }

  50% {
    transform: translate(1px, -1px);
  }
  100% {
    transform: translate(0);
  }
}

@keyframes shape-roam-2 {
  0% {
    transform: translate(0);
  }
  50% {
    transform: translate(-2px, -4px);
  }
  100% {
    transform: translate(0);
  }
}

@keyframes shape-roam-3 {
  0% {
    transform: translate(0);
  }
  50% {
    transform: translate(2px, -2px);
  }
  100% {
    transform: translate(0);
  }
}

/*
  If your animation duration is short,
  consider using the prefers-reduced-motion
  media query to respect user's preferences.

  In this case it's probably okay, but if you
  get to a 1-2s duration, you may consider
  adding the media query and bumping it up to
  something more like 6-8s here.
*/
.animate-shape-roam-1 {
  -webkit-animation: shape-roam-1 6s infinite;
  animation: shape-roam-1 6s infinite;
}

.animate-shape-roam-2 {
  -webkit-animation: shape-roam-2 7s infinite;
  animation: shape-roam-2 7s infinite;
}

.animate-shape-roam-3 {
  -webkit-animation: shape-roam-3 8s infinite;
  animation: shape-roam-3 8s infinite;
}

If you'd rather read my high-level opinions rather than my longer ramblings, here they are:

• If you're building a Design System for multiple frameworks, web components mean you build it once and can use them everywhere
• Web Components provide encapsulation, which is really important in Design Systems
  • You have full control over the Component API and styling
  • This helps enforce rigidity versus flexibility in product Design Systems
• Web components use the platform and feel like "getting back to the basics"
• Interacting with web components in each framework differs and could be a bit of a mental model shift by your fellow developers
  • For example, using JS to attach event listeners, rather than a simple onClick property.

Have you used an <iframe> before? Things don't leak out from the iframe and you don't get full access into it either. The iframe can dispatch events when certain things happen that consumers can listen for and react to. This is essentially a similar concept to web components. Users render your component on their page, they provide some attributes and add event listeners and that's about it. Other than that, the web component just does its thing.

The web component contains the full UI/UX, without exposing ways to modify anything internal to it. You have access to some knobs to adjust things via attributes, can call methods on the component to invoke some internal action, and get notified via event listeners when things happen, but that's about it. All you know is that you need a button element, so you render a <cool-button>. Maybe this separation of concerns is a good thing? It means you are signing up to use the component as is, and only get scoped access.

Web components are essentially an opaque box. You put some things in and get some things out. You don't get to look into the box! Contrast that to typical components, where you can adjust things like styling and modify the inner workings of a component if you really try. The encapsulation of web components offers a lot of advantages, in my opinion, which I'll share in a moment.

Does your organization build UIs using multiple frameworks? It's a pain to share components between them! From my experience, you normally end up building the same thing in each respective framework. Double the work, but not double the fun. Maybe you end up trying to share CSS, since CSS is "easy" to share, but the problem remains: you're building the same thing for two or more distinct frameworks and writing JavaScript in different ways.

Instead, why not build the components once? That's what web components allow you to do. Web components work on all frameworks and are "framework agnostic". Say you have one app in Ember and another in React - they can both use the same exact web component. Take a <cool-button> component for example. The way you interact with this component may be different depending on the framework, but the markup to render the component is identical.

// Here's an example of a very simple and not
// fully-featured button component written in Lit.
import { html, css, LitElement } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('cool-button')
export class CoolButton extends LitElement {
  static styles = css`
    button {
      background-color: #4095bf;
      border-radius: 0.375rem;
      color: #ffffff;
      border: none;
      padding-top: 0.5rem;
      padding-bottom: 0.5rem;
      padding-left: 0.75rem;
      padding-right: 0.75rem;
    }
  `;

  @property({ type: Boolean, reflect: true )
  disabled = false;

  @property() type: 'button' | 'submit' | 'reset' = 'button';

  render () {
    return html`
      <button ?disabled=${this.disabled} type=${this.type}>
        <slot></slot>
      </button>
    `;
  }
}

// In Ember
import 'some-path-where-cool-button-lives';
import Component from '@glimmer/component';
import { on } from '@ember/modifier';
import { action } from '@ember/object';

export default class SomeComponent extends Component {
  @action
  handleClick(event) {
    console.log('cicked')
  }

  <template>
    <cool-button {{on "click" this.handleClick}}>Button</cool-button>
  </template>
}

// In React
import 'some-path-where-cool-button-lives';
import { useEffect, useRef } from 'react';

const SomeComponent = () => {
  const buttonRef = useRef();

  useEffect(() => {
    const handleClick = (event) => {
      console.log('clicked');
    };

    buttonRef.current.addEventListener('click', handleClick);

    return () => {
      buttonRef.current.removeEventListener('click', handleClick);
    };
  }, []);

  return <cool-button ref={buttonRef}>Button</cool-button>;
};

You'll notice that in the React example, you're back to using addEventListener. You may be thinking "well this isn't very React like!" - that's true, but it is your favorite old friend, vanilla JavaScript. If you'd prefer more React-like syntax, Lit offers a React package that wraps your web components and offers a more friendly React-like syntax so you can ditch refs and event listeners and get back to using props.

The big advantage here is that you write a web component once and can use it anywhere. You render it like any other component and wire up attributes and events. Now you don't have to make <cool-button> twice! Nice 👍.

The best part of web components is they're part of "the platform™". Similar to how you can build a web app using only HTML, JavaScript, and CSS, you can create web components using the tooling you already know and love. There are no external dependencies if you're writing custom elements yourself. Using only HTML, JavaScript, and CSS feels like getting back to the basics - and I'm loving it.

If you're building a Design System in a repository separate from your main app repository, you will need a way to build your components and distribute them. We've been using esbuild and it seems great for this. Projects like Shoelace do something similar. In an organization, I think it's almost guaranteed you'll be using some existing tooling for things like builds, tests, etc., but the idea that the underlying components are "just HTML, JavaScript, and CSS" is pretty cool.

By being baked into the platform, it means there are a lot of protections around web components. Browsers know how to render and what to do with them - they're treated as first-class citizens. We shouldn't expect huge, breaking changes in the short term - contrast that to when you go to bump versions for your favorite JS dependency. Take a look at SpaceJam's 1996 website, this baby is still alive and kickin'! Web components will carry the same support far into the future due to being backed by browsers via the platform. It's similar to CSS - there will be new features added as time progresses, but what's there today is set in stone and it's unlikely they'll break or stop working as the years pass.

Whoa whoa whoa, Tony, you just mentioned above you're using Lit. Why do you keep harping on the platform when you're obviously using an abstraction on top of web components?

Lit is a light abstraction on top of the native APIs that increases developer experience and make our jobs a bit easier when it comes to writing components. The decorators are quite helpful and it removes a lot of boilerplate you'd write yourself for each component. I'd recommend folks read their docs and see what I'm talking about. Every Lit component is a native web component - under the hood they're using custom elements, so the browser treats them like built-in elements. To me, the benefits of using Lit are worth it.

One of my favorite parts of web components is encapsulation. You get protections automatically when using the Shadow DOM. A big selling point of building Design Systems is ensuring consistency across your application(s). This can be really difficult when anyone can come in and target your elements to apply any styling they want. This leads to inconsistencies throughout your product and your customers will notice. Not with web components! With web components, there are only three ways to expose styling to consumers:

1. CSS variables (aka custom properties)
2. parts
3. :host (I do not recommend going this route as it's not as clear in my opinion as options 1 and 2 above - I'll elaborate more.)

Using CSS variables for sharing styles across web components is really nice. After all, you probably don't want to repeat the same color across n number of components - it makes sense to leverage a variable instead. They can also be used for customization within web components. CSS variables pierce the Shadow DOM, meaning that a parent rendering a web component can override a style inside of a web component if it is exposed as a CSS variable.

You get to decide what consumers get to style by making it a public API, driven by CSS variables. Take a button for example, you may want to allow the consumer to support different color modes - maybe they should be able to adjust the background-color CSS property. When you define the background-color in your web component, you can expose this via a CSS variable to allow consumers to override the default.

button {
  /* Allows a consumer to adjust this! */
  background-color: var(--button-background-color);
}

:root {
  /* Elsewhere you define the variable, maybe at a global level */
  --button-background-color: #4095bf;
}

.cool-button-override {
  /* ...or maybe at the class-level */
  /* where you'd do something like <cool-button class="cool-button-override"> */
  --button-background-color: #4095bf;
}

If you want to protect a style from being overridden by consumers, keep the style hardcoded/local to the component itself. Maybe you defined the padding of buttons and decided that padding should not be modified at all by consumers. You want button padding to remain 100% consistent and not be adjusted. If that's the case, you can set those values directly in your web component. Since these values are not exposed via a CSS variable, it means consumers have no way of adjusting these values. Nice!

button {
  /* Consumers can't adjust these! */
  padding-top: 0.5rem;
  padding-bottom: 0.5rem;
  padding-left: 0.75rem;
  padding-right: 0.75rem;
}

The second option to allow customization to consumers is via parts in CSS. You expose areas of your UI that consumers can target with CSS, which allows them to customize it to their needs. If a part is not exposed, the consumer does not get access to style that piece of your UI. Say for example you have a "card" component that you want to expose a header, body, and footer to consumers to style as they please. You'd expose a part for each.

<!-- From a `cool-custom-element` web component -->
<div class="card">
  <div class="header" part="header">
    <slot name="header"></slot>
  </div>

  <div class="body" part="body">
    <slot></slot>
  </div>

  <div class="footer" part="footer">
    <slot name="footer"></slot>
  </div>
</div>