My philosophy when designing APIs and libraries is to make it as easy to use as possible, but as difficult to use INCORRECTLY as possible. When I used to make plugins with jQuery, there would often be guards on functions to ensure that the data passed in met the function's expectations:
In a previous article, I discussed Surfaces as an abstraction on APIs and how we could measure complexity as the size of that surfaces' perimeter – the "visible" part of the API to consumers. I shared this article with a colleague who I was actively working closely with on a new implementation of a design system. They has some interesting feedback on different ways of reducing complexity of certain APIs that I felt compelled to revisit this topic.
Maintaining growing software is challenging. Poorly architected APIs and incorrect abstractions can significantly impact the ability for engineering teams to deliver new features in a timely manner. If we consider an API's complexity as being a significant contributor to its overhead, maintainability, and ease of use, then it becomes a question of how do we best measure this complexity so that we can make informed decisions about how to refactor and improve our APIs.
The following is a checklist I like to use to ensure I'm covering all the bases when building a component library. It's a work in progress, but I hope it can be useful to others.