Consider a more flexible API

[cseas]

We've been seeing a lot of suggestions lately for building custom components with Blade tokens.

Some examples where Blade components are available but can't be used for designs:

• Created CustomBox because Box didn't support the needed styling properties for HeroPolygon.
• Created CustomBox again because Box doesn't support onClick.
• Created CustomBox again because Box doesn't support backgroundImage.
• Created CustomLink because Link didn't support implementing the intended design.
• Need to create CustomRadioGroup because RadioGroup doesn't support the intended design.

Some examples where there are no Blade components available (yet) for implementing them:

• Created CustomCarousel because Blade didn't have Carousel.
• Created CustomCarousel again (different design) because Blade doesn't have Carousel.
• Created VerticalTabs because Blade doesn't have Tabs.
• Need to create CustomCarousel once again for new designs for GPT generator.
• Might need to create CustomTooltip because Blade doesn't have Tooltip.

The design deviations have been flagged multiple times by devs and the recommendation from the Blade team is clear: "If Blade doesn't have it, build a custom component using Blade tokens". The problem here is, building any component from scratch with just a bunch of tokens still takes a lot of work and iterations. Teams generally don't account for this extra work because the assumption is that designs made for Razorpay products are supposed to be Blade compatible. We've seen this assumption fail several times and the pattern is continuing in every new design.

Now usually the request for visually different components isn't a big problem when we're using something like MUI or Chakra. Because while those libraries can be used to build Blade designs quickly, they can also be used to quickly build any one-off design deviations. The problem with Blade is that the API is so restrictive, we need to spend hours justifying the use-case for every CSS property or build the component entirely from scratch. This means Blade itself is making devs slower in implementing Blade designs than open source UI libraries.

The consensus from the Blade team is that if there's a design deviation, the devs are still supposed to implement it because the product designer has taken the call. But this is not reflected in the Blade API because the components make it impossible to build anything other than the documented set of design building blocks. So the design deviation is going to be implemented one way or another. By keeping the API handicapped, all we're doing is increasing the work & time taken by Blade's consumer devs to implement those design deviations.

We've also seen multiple times during developer reviews of designs that developers need to point out some variant of a component isn't possible with Blade. This is clear indication that designers aren't using Blade to build designs the way its intended.

If we want to keep up with keeping the API as rigid as possible, we need to setup a design review process for designs that includes a review from Blade advocates before it reaches the developers. All designs should be approved by Blade advocates & the Blade team so devs don't need to go back & forth between the product designer and Blade devs on what is possible with Blade and what not, and where do we draw the line on respecting deviations. There's a process setup for this but is not being followed because almost all our requests for changes in Blade API come as a hindsight after the product devs look at the designs. Designs are supposed to need Platform Approval before being passed for development.

The repeated justification for a rigid API is that we want to maintain design consistency in usage of components. But consistency gets broken with every suggestion to build a custom component. Are product devs supposed to flag and discuss every design element that's not possible with Blade? (If yes, we need restrictions on designers) Or are devs expected to implement all design deviations since designs will vary based on product? (If yes, we need to provide an escape hatch, something like the sx prop. It can be discouraged but if Blade team has already agreed that a custom component is needed then devs should be allowed to use the escape hatch). A lot of this confusion can be cleared with a better design review process so devs receive Blade compatible designs where any design deviations have already been flagged and approved by Blade advocates. This would save a lot of discussion time for product devs.

Related: A Figma plugin to identify design system issues.