Base Web, Uber’s New Design System for Building Websites in React

> 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.

You're right, sorry! I write TS every day at work but for some reason I sometimes forget which languages use bool and which use boolean ;)

I disagree- the default use case is still to use the components without overriding. Having a well defined mechanism for changing the component allows for consumers of the components to still get the main benefits of the component and the owners/maintainers have better visibility into what (if any) changes may need to be made to the core components.

A concrete example probably does a better job of explaining how this is used: https://medium.com/@dschnr/better-reusable-react-components-...

Referring to the Uber Freight RadioGroup and Tag Edit overrides from that article (not my article to be clear), those are cases where the vast majority of functionality from the original components satisfied the usage requirements, but a small tweak was needed to get the desired outcome. The override pattern is simply a way of building flexibility into the components and acknowledging that the users of the components may want to change them in ways that were not obvious to the component author. Those two examples may be fairly straightforward, but at what point do you stop with exposing the ability to change things? In our prior component library we saw a number of cases where teams wanted the ability to customize things that were more subtle, ie- changing the html element type on a subcomponent for a very specific purpose. This pattern came from observing the usage of our prior internal component library and talking with many of the internal consumers. It's probably not be a fit for everyone, but it works well for us.