> But that's a lot of steps to just tweak a border, isn't it? Why not to just have "overrides.FooComponent.style" and let the library do the rest. This doesn't open more surface, just a quality of life API. Arguably you can run into the same type of style breakages when devs are restyling our subcomponents. They will not look inside of them every single time we release a new version.

The ability to arbitrarily override styles in every single component exposed through the library is exactly the crux of my concern outlined in my original post and later reply.

> "people are going to start using our components ways that we can't possibly ever fully anticipate" - That always happens no matter what you do! Unless you make your API super strict and then nobody will want to use your library. It's a delicate balance - keeping other teams moving fast and happy while not introducing breakages often.

Yes, there's definitely a balance to be struck here.

Opening up the API to arbitrary style overrides is sitting at one end of that spectrum, optimizing for short term user freedom/productivity and quick adoption of the component library over the long term maintainability of the library (every change becomes a potential breaking change), and with it, the ability of users to upgrade with confidence to take advantage of new changes and features.

However, the alternative to the wild west approach of arbitrary styling overrides isn't only to make an API so strict that it will never fit anybody's use cases outside of the ones it was originally designed for.

There exists a middle ground of providing an explicit API designed for specific use cases and then deliberately growing that explicit API to cover more use cases, informed by real world usage patterns, while taking care to make sure that those use cases are actually ones that make sense for the library to support long term (rather than built as one-off usage specific components), and that the resulting changes aligns with whatever styling consistency standards the library wants to enforce.

This approach affords maintainers an API surface to reason about and communicate breaking vs non-breaking styling changes to users, in exchange for short term speed of adoption because we're deliberately limiting the initial breadth of use cases the library can cover.

The former approach could definitely be the right tradeoff to make at this time given Uber's current circumstances.

Personally, I still have my doubts, after seeing how quickly this kind of API can break down even at a much smaller scale, but ruling that out without any context would be pure hubris on my part.

However, one caveat I'd like to add is moving from an explicit API to one that allows arbitrary overrides is easy, because adding an arbitrary overrides system is a non-breaking change, but going the other way is another story, because doing so would break everybody that relied on the overrides system to cover whatever use case the base API ever bothered to grow to cover, so it's not a decision to be made lightly. This is definitely not meant to imply that the team at Uber made the decision lightly, as I can tell from your thoughtful responses that you certainly did not, but rather as a word of caution to anyone else who's thinking about going this route.