Invest in Material-UI React Component Library

[shanberg]

We should start using an existing component library

Athens' internal component library is ad hoc, minimal, and lightly tested. The quality of some of our internal components has reached a local maximum where further improvements may take an order of magnitude more work than we’ve already done, like breadcrumbs (which break when there are too many) and modal dialogs (which are portaled but don’t properly capture focus).

We could solve those specific problems by bringing in utility packages (like react-popper and react-focus-lock), or we could lean on an existing component library with established patterns and component compatibility. A mature component library will give us access to a well-tested and internally-consistent library of common atoms and utilities, so we can can spend less time worrying about styling, low-level component functionality, and component API design, and more time prototyping and iterating on the product. Raising the level of abstraction will also allow more contributors to create layouts, interactions, and workflows more easily by drawing on the toolbox and documentation that's already available.

Material-UI is a fairly complete component library, with a mature API pattern for components, a system for global theme, css, and prop overrides, and flexible methods for local style overrides, on top of reasonably high test coverage and very high real-world usage: Material-UI has 68.8k stars, 22.3k forks, is depended on by 577k GitHub projects, and is in active development, moving toward a 5.0 release later this year.

---

What should qualify a component library for Athens?

• It’s open-source.
• It’s a component library, and not just a styling system.
• It’s built to be themeable and not just the implementation of a specific design system.
• It’s thoroughly documented.
• It’s well-used and well-tested.
• The project is still actively developed and used, so we can both expect updates to the code, and for contributors’ knowledge to transfer to and from other projects.

Other libraries that might qualify, but don’t seem as good

• Theme-UI — This is compelling, but hard to argue for over Material-UI given Material’s much greater overall usage.
• React-Bootstrap — This is themed with Sass, so it lacks modular CSS, and the project’s activity is lower than Material-UI’s.
• Semantic-UI-React — Very little activity on the project since January
• Chakra UI. A newer, fresher library, built on styled-system.
• Tailwind UI — Paid. Maybe $600 for team use? They have a bit in their license referring to open-source projects.
• Base Web — Uber’s react design system. Looks fairly complete to me, but is directly tied to Uber.

What are the downsides of Material-UI?

• Styling with their classes system requires learning how Material-UI works. It’s sensible, but it’s some extra work.
• There are a lot of ways to style Material-UI components. This may be a benefit, and may be a drawback. Athens could determine a single recommended pattern, or could allow contributors to build in the way they’re most comfortable.
• Material-UI is fundamentally built to implement Google’s Material pattern, though it’s also very customizable. There may be some UI-architectural impact to the Material foundation, though components made with Material-UI all appear to be very pliable.

Further thoughts

Styling systems are a lot more fun to talk about than component libraries because they’re more freeform and creative development tools. Picking a starter component library feels more like a hold-your-nose-and-dive-in thing.

Most of the high-profile options provide styling at runtime rather than buildtime, which has a measurable performance cost. Ideally we’d be able to avoid that cost. Some systems and libraries might support this workflow, but I haven’t found them yet.

Likely Questions

Why not continue making our own components?

Leaning on an established component library favors prototyping speed over a slower and potentially more bespoke waterfall development process like dev -> design -> dev -> polish.

Does leaning into a component library mean deeply tied to another codebase?

Maybe, but it gives us a major speed boost, having all these components ready out of the box. We can continue to make custom components as needed, but we get to focus on the meaningful things instead of everything.

Is Material-UI too tied to Google?

No, the project is not operated by or sponsored by Google, and the theming system is robust. Properly-used, Athens will look like Athens, and nothing else. It supports theme-level changes (like light/dark mode, font, accent colors), global prop overrides (like disabling the button ripple effect), global style overrides (like saying buttons in breadcrumbs should be smaller padding), local style overrides (this button is blue), and class style overrides (this button, with class X, is red)

What immediate benefits should we expect?

• Better breadcrumbs that collapse into a “more” button instead of squishing into unreadabie infinitesimality.
• More polished and accessible modal dialogs.
• Easier prototyping with a large toolkit of ready-to-use components.

What about Stylefy? Tailwind?

Material UI internally uses and exposes a styling system similar styled-system. Use of this appears to be optional, but it’s an atomic CSS pattern similar to Tailwind.

What are potential good reasons we shouldn't use Material-UI?

• We want to build everything in-house, and we can afford the development time to build all the functionality we need.
• We don't like any of the styling options available in Material-UI and we're prepared to find another library with lower overall usage and development velocity.
• We don't like the way the Material-UI project is managed, and that's significant enough to us that we should use something else.
• Material-UI doesn't provide enough of the specific components we're likely to need to be worth making any large effort to adopt.
• We have a strong preference for build-time styling, rather than run-time styling, and we can find a library that fits that need and provides some of the other stated benefits.
• Material-UI has some significant performance, accessibility, or quality issue that holds Athens back

What are the practical steps being proposed?

1. Add MaterialUI's ThemeProvider to the root of our view component’s main return content.
2. Customize the MaterialUI Theme to blend with the current look and feel. No Google style.
3. Upgrade our Breadcrumbs, Dialogs, Buttons, and Dropdowns with Material UI equivalents.
4. Continue to replace existing components with Material-UI equivalents, and encourage contributors to use the library to build new features and prototypes.

[juniusfree]

I converted the Merge Roam DB modal using MUI. This is my first time using a design system. Here's my initial impression.

Cons:

• Needs a workaround for the upload button. Not sure if this is common. I just followed the example. e.g. https://material-ui.com/components/buttons/#upload-button
• Needs to be comfortable on relying on the design system. Initially, I struggled because I still think on how to layout or color the element. In a design system, it's mostly handled by the component.

Pros:

• Faster to add the components once I got past the initial learning curve.
• Consistency

[neotyk]

As we've discussed @shanberg after Self-Hosted effort, we'll create prototypes to explore MUI vs TailwindCSS before we'll make a call on this.
I've used both in past, they are both good, but TailwindCSS especially with TailwindUI components is so much easier for design & engineering to collaborate.