Shipping Way More JavaScript than We Need

[cogwizzle]

Shipping Way More JavaScript than We Need.

Should we consider dropping our replicated native elements? I intend to outline the reasons that I think that we should. I also outline all of the elements that currently replicate native behavior in the browser.

Summary

We could effectively ship less JavaScript and provide a better experience for our users by doing so. Shipping less JavaScript means decreased build times, decreased load times, and a smaller burden on our CDN. All three of these would amount to a cost savings. All of these benefits are either passed directly onto the user or benefit Twilio in a large capacity since Paste is the default UI library now.

Additionally less time would be required for maintaining the code for effectively reimplementing the native elements. This could save development time. Many of the components do little outside of forward props to the native implementation and style the element. Why not just make a CSS file that makes the elements look like Paste elements. For instance...

Example

The button code we use today like this...

<Button variant="primary">
  Hello World!
</Button>

...would simply become.

<button class="primary">
  Hello World!
</button>
<!--You could keep it as variant instead of class if you wanted I guess...-->

As you can see it is actually a little shorter to write the non paste version, and it doesn't incur any JavaScript penalty for using it (aside from the penalty from our framework.) Our button elements when using paste, would just be button elements. It still frees us to use CSS to override the styles as we still can today if needed. 99% of the time this won't be a problem.

Developers would have to look up the Paste API less because more of the elements being used would be native elements. Hopefully we all know the native HTML APIs relatively well. This will also lead to less accessibility issue surface area. We can be more effective by using the semantic elements in some cases.

Proposed components to change

Form elements

I'm going to give a few examples of purely duplicated form controls.

1. Anchor This is just wrapping React Router's abstraction I think. Also I think React Router is dying. Not an emergency but something'll have to change eventually so that we can move off of the project if it becomes stale.
2. Button
3. Datepicker
4. Form
5. Input
6. Label
7. Radio Groups
8. Select
9. Slider Input type range
10. Textarea
11. Timepicker

Visual elements

A list of visual components that we effectively duplicate are below.

1. Card We could effectively just style article. That is what is happening under the hood anyway.
2. Description List Isn't this just dl, dd, and dt elements?
3. Disclosure This is just a styled details element.
4. Display Heading These are just headers.
5. Flex Feels like it could be a CSS class.
6. Grid Feels like it could be a CSS class.
7. Headings These are just headers too.
8. Inline code We could just use code.
9. List This is just shipping extra JavaScript for the exact same API.
10. Meter This is a progress element.
11. Modal and Alert Dialog This is effectively dialog. Very important for accessibility. How would a vision impaired individual know that a div is higher or lower on a page.
12. Page Header This is just a header.
13. Paragraph Just use a p tag.
14. Progress bar This too is just a progress element.
15. Combobox This is just an input with a datalist.
16. Seperator This is just an HR element.
17. Skeleton Loader. This is an animated progress element.
18. Summary detail. This too is just a details element.
19. Toggle Switch. Maybe we should just use a Checkbox? It would likely be more accessible.
20. Table This is a table element.
21. Tooltip This is title. You can style it.

Proposed Solution

I propose that we do not kill the components outright. Instead we can take a two pronged approach to properly deprecating the components. We should be very careful about the roll out as to not create a burden on the engineering teams to migrate again. Also we should roll the changes out to each product slowly iterating migration tools and bug fixes along the way.

1. Wait until the next major version to roll this change out.
2. Add a JSDoc deprecated tag to the elements when they are ready to be deprecated.
3. Write a Code Shift or some form of automated script to migrate the old tags to the native counterparts. This removes the burden of a person having to manually convert everything by solving the problem once.
4. Slowly roll these changes out to all Paste consumers while fixing bugs along the way.

Potential Problems

1. These components aren't a 1 to 1 map to one element. For instance Combobox is a label, and a selectbox or input/detaillist. The utility of being able to add a label property vs adding a label element does not outweigh the degradation of the user experience by creating an additional JavaScript tax. UX > DX
2. As previously stated the developer experience may shift in a minor way by relying on native apis. Using classes vs variant tags is a good example of this. However truly putting the customer first may mean small sacrifices. I doubt that our engineers would even notice the difference. Using classes to style elements has been a paradigm since 1996. It is commonly seen in popular libraries like bootstrap or pico.css. It works fine.

I finally will assert that my opinion is that the potential DX improvements here will never reach the customer. The customer doesn't care if you've got a custom React element that saves you two seconds by not forcing you to write a label tag. They will however notice if the page loads slower. The will notice when bugfixes take longer to get out because the bundle is bigger. These changes I've proposed are intended to put the customer first and potentially have a big impact across the org.

This is not intended to be a criticism of the Paste library, but trying to make broad stroke improvements for the developers that use it. Feel free to disagree with any of the topics above. If any of this gets through it'll make the experience better IMO. I also don't think anyone should take this on all at once. It should be done slowly. Thank you for hearing out my rant.

[TwilioPasteBot]

Disclaimer: This is a very experimental bot using OpenAI's GPT-4. The answers may not be correct, a human will review the answer and update it if necessary.

---

Sorry, I don't know how to help with that.

I did do a search though, and I managed to find these other Discussions that might be similar or related to your question. Give them a read to see if they answer your question. If they do, head back here and update this discussion and mark it as answered, pointing others to the related discussion:

• best practice of using custom styles / classNames on paste components - Answer (updated: 08/08/2022, similarity score: 87%)
• Paste Bundle Size - Answer (updated: 02/02/2023, similarity score: 85%)
• Release of the new Paste visual language and new navigation - Answer (updated: 01/26/2024, similarity score: 85%)

[TheSisb]

Hi @cogwizzle,

I appreciate your perspective, though I think there might be some nuances to consider regarding design systems. While the concept of using native elements with CSS classes to minimize JavaScript payload is valid, the reasons behind the current architecture are more intricate than a simple discussion reply can cover. I might consider delving into this topic further in a series of blog posts in the future, but for now, I'll offer a brief overview below.

Why do some companies need design systems

As tech companies expand, so does the number of engineers working on user-facing products. Those engineers come from varying backgrounds and levels of experience. How do the people working at the company ensure quality, consistent, and brand guidelines are followed?

• You can tell new hires what to do, up to a point. It stops scaling as one team becomes three becomes fifty.
• You can have ARBs, code reviews, monthly guild meetings, working groups, or other synchronous methods to disseminate information but that is blocking, not everyone attends, and things can still go awry. It's not the right tool for this particular job.
• You can have a component library that people from different teams commit to and maintain, but lacking an ownership and governance model it usually has good parts and bad parts. The main bad part is that every team can impose opinions on the system at will, and it no longer becomes "one system" as the company grows. Instead, it becomes an unusable amalgamation of philosophies that is no better than what you started with.

So you need a centralized team to create a system that satisfies the needs of that particular company, can budget in education and documentation, as well as manage the codebase so competing products or groups within the organization don't cause rifts. A funded design system team signals that you take product design and engineering seriously and supports new hires with onboarding.

Now what do design systems actually do?

Many things, but for the sake of this discussion I will focus on one: change management. More or less, every tech company attempts to do a UI refresh every 3 or so years. Technologies change, styles change, the brand evolves, etc. It doesn't always have to be a conscious thing.

Let me try to paint a picture. Say we said to use <button className="primary"> and some team didn't like primary. It didn't fit their needs perfectly for some reason. So they create a CSS file in their codebase and add button.primary { /* some overrides */ }. Now some other team that is working on the same product, or even an engineer on the same time in some cases, doesn't know that override is in the codebase. They use the primary button and get a weird result in their page during development. They think "ok... I know what I want here and it's not that". So they add another override. This chain goes on for a while and someone eventually gets frustrated by CSS specificity so they toss in an !important or two. I hope you can see where this is going.

Problems in the codebase occur creepingly, and by the time you notice it it is usually quite late. The first problem is that the design system team cannot reasonably affect change in the product as the designs evolve due to the overrides battling each other on top of the base designs. The second problem is that new engineers who aren't part of this override history have no idea why things don't look the way they should. They may not even have repo access to where the CSS overrides are happening in order to fix them. Lastly, someone has to eventually look at all the variations and remedy the situation in the codebase to create a new single source of truth without overrides. This is where Twilio Console was when this team got funded, and that's exactly what we did.

Cascading Style Sheets are great until they're not. The Cascade part is an anti-pattern at scale. If you research the cascade and why it's bad, you'll find plenty of blogs talking about it.

So the design system team needs to restrict access to overrides. CSS modules is a solution, but while it fixes the cascade you can still add classes to any element over the existing ones. This prevents a central team like us to affect any change. Also it's confusing, because people think CSS class ordering on elements matters but it does not. Take for example <button class="primary custom"> and <button class="custom primary">. The outcome depends on where the classes are defined in CSS, not in the order in which they're used. On large decentralized organizations working on a single product suite, this is chaotic.

We need guardrails

It hurts to say, but we need guardrails. Good intentions don't always lead to good outcomes. It could be an early-in-career engineer or it could be a lead, but things always slip given enough time. At Twilio scale, and at the time when we started, the best technological solution for this problem was Emotion + Styled-system. I had come from a background of PostCSS + CSS Modules but it didn't allow us the same level of control and change management as a CSS-in-JS solution. This solution comes at a minor runtime cost, but allows us to operate at Twilio scale and ship design updates without breaking changes. The price we pay for this degree of confidence and resiliency is truly worth it. In other companies that are structured differently, a different solution may make sense.

Duplicating semantic HTML into React components

Not every engineer is a semantic HTML expert. A lot of engineers at Twilio are backend engineers trying to get by on the frontend. They may not know things you consider common knowledge. Aside from that, we have carefully crafted each component to work harmoniously with each other in a design language that is entirely Twilio. Instead of reaching for a h2 element, the Heading element bakes in the correct margin and sizing. Typography scales and vertical rhythm are a big part of any cohesive design system.

Questions we asked ourselves

• How do we make sure only tokens are used and not hardcoded values?
• How do we eliminate footguns?
• How do we make a design change without breaking downstream products, causing potential incidents?
• How do only ship the minimal bundle for each product?
• How do we manage package versions and rollouts?
• What's the least worst option?
• How does a team of 4 support thousands?

Technology today

Any workable solution, even by today's standards, will employ a minor runtime overhead to achieve the guardrails we need at enterprise scale. By design, only specific props are allowed on Paste components; the only technological surface upon which we can restrict that is through Javascript. When we started, no one was using Typescript. Even today we aren't completely a Typescript shop, and it's too easy to // @ts-ignore to call it good enough. The component has to fundamentally restrict behaviors in development and runtime to prevent teams ejecting and causing long term, far reaching issues for everyone involved.

---

This has been a long answer, but is still very superficial and misses many key elements. Let me know if this has helped at all clarify why some things are the way they are, and if anything requires further explanation.

[cogwizzle]

So they create a CSS file in their codebase and add button.primary { /* some overrides */ }.

I can appreciate this and I've absolutely seen this occur one thousand times in code. This is a compelling point, but I don't know if I'm 100% bought into the idea that CSS couldn't work. Perhaps I am too idealistic in this regards. Maybe I haven't been burned enough.

So the design system team needs to restrict access to overrides. CSS modules is a solution, but while it fixes the cascade you can still add classes to any element over the existing ones.

Yes, but, I can still do this with Paste. Some components accept "style" as a property and I can just pop in styles. I shouldn't but I can. One thing I want to mention is sometimes you need a break glass in case of problem. I think adding custom classes or styles in that circumstance might be appropriate depending on the situation. I've done some off-grid stuff with customers in the past that uses negative margin to float stuff to weird spots and stuff.

It hurts to say, but we need guardrails. Good intentions don't always lead to good outcomes. It could be an early-in-career engineer or it could be a lead, but things always slip given enough time.

I agree. I think the appropriate guard rails are people oriented though. Perhaps it has been an issue in the past. It may be a cultural issue we've had previously at Twilio. I've seen CSS applied at scale effectively. I'm going to get a bit anecdotal here.

• I have never met a designer who doesn't deviate from a design system in some way. Some are better than others at accepting that and pivoting.
• I've used robust design systems like Bootstrap, Evergreen, and at one company I consulted for I worked with a design system really similar to Paste. These have relatively good results when the design is adhered to. Bootstrap one backfired because this was back when we manually downloaded source code and included it. People started modifying the source. 😱
• I've used Tailwind to CSS all of the things with inline classes.
• I've used libraries like Pico.css, which I ultimately think is the best approach and requires the least amount of code. To your point I can see this getting messy if discipline is not applied.

Not every engineer is a semantic HTML expert.

Couldn't we just show them the right way to implement the native element? The wrapper wouldn't be needed then.

Instead of reaching for a h2 element, the Heading element bakes in the correct margin and sizing.

You could accomplish this with classes as well. I noticed we effectively have three heading elements. You could consider something like this.

<h2 className={superVariant.one}>The names don't matter for this example.</h2>
<h2 className={superVariant.two}>Hello World!</h2>
<h2>Lorem Ipsum!</h2>

h2 {
  // Styles

  &.one {
     // More styles
  }

  &.two {
    // More more styles
  }
}

How does a team of 4 support thousands?

You guys are killing it. I did not realize it was a team of so few.

My final question (for this message at least) that I'm going to ask is what if React loses momentum and popularity? Don't get me wrong. I've worked with React for almost 10 years. I like it well enough. But eventually just as with jQuery and MooTools before that it will fall away. After the jQuery to component based leap I have naturally gravitated towards the platform rather than putting all my chips in one basket. Ultimately it is a choice not for me, but I think potentially something to consider. React is in a way already fracturing. There is Next.js React, and Remix React, and React. They all have a bit different ecosystems. Sorry I'm not trying to doomsay, but I just want to bring that perspective. I'm sure you've already made the calculation that the investment is worth the risk. As you said we're likely to revamp in 3 years and could address it then.

[TheSisb]

Maybe I haven't been burned enough.

This.

On some level, design systems are a set of philosophies and opinions. You may not agree with them or think it can be done better, and that's perfectly fair. I will say that after 4ish years of maturation, we have been pretty pleased with our results. Technology does advance and I'm seeing new systems like ShadCN do things differently with great success in the open source community. I do not think it would work for Twilio, however.

Yes, but, I can still do this with Paste. Some components accept "style" as a property and I can just pop in styles. I shouldn't but I can. One thing I want to mention is sometimes you need a break glass in case of problem. I think adding custom classes or styles in that circumstance might be appropriate depending on the situation. I've done some off-grid stuff with customers in the past that uses negative margin to float stuff to weird spots and stuff.

The only components that should accept a style prop directly is our primitives, like Box. Primitives are unstyled, accessible UI interaction or behavior that can be used as a starting point for specific UI needs. They don't bake in Twilio design decisions, so allowing style is fine. If you have noticed style being accepted in a Component (not a Primitive), please do file an Issue as it would be a bug.

Ejecting is possible, it's web tech after all. Nothing can stop you from adding a <div className="whatever" to your project. All we try to limit is how our own designed components can be customized, since it affects our ability to make changes.

Couldn't we just show them the right way to implement the native element? The wrapper wouldn't be needed then.

This doesn't work at scale, unfortunately. It has been tried by many other design systems and after a certain level of scale it begins to fall apart. The uncomfortable truth is adding this complexity on our own shoulders is the most scalable and resilient solution.

My final question (for this message at least) that I'm going to ask is what if React loses momentum and popularity?

Twilio is a React shop as far as we can tell. We built this system for Twilio and that means using React. If Twilio decides to move off of React in the future we would need to figure out what that means and how to do it.

---

We can discuss this topic at length in our office hours. I hope you don't mind if I mark this resolved as I don't want to give users the wrong impression from the topic title.

[cogwizzle]

Do you want to rename the title of the discussion? I'm happy to do that. I'd love to have more of this conversation out in the open so that others can refer back to it. If you still think it should be closed that is fine. I'll have plenty to say during our Office Hours.

I was just thinking the deeper we debate the merits of these approaches then the less often you'll have to have this conversation more than once.