Empowering Design System Users

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

In my experience, the answer is "yes."

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

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

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

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

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

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

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

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