Thread by @MatuzalemTeles

Building a component library is rather complicated than just creating a few components based on the Design System implementation.

Developers want to go beyond implementation because products evolve, but some of them just want to follow implementation.

Within an enterprise it is not an option for you to just take one approach but it is also not right to attack all directions to deliver the components. Balance is always the secret but the hard part is getting there.

Balance must exist on both sides, in the Design implementation and in the component library. If Design System blocks the creative mind of the designer, he can make a decision:

1. Do not use the implementation
2. Use desired "limited experience" implementation

In a ripple effect the developer will have to make some decision:

1. Use the component library
2. Create your own implementation.

This is quite complicated but what do you do not to frustrate the developer and designer? This will depend on which direction your Design system implementation follows.

1. Just define the primitive components and the foundation of the designer (typography, spacing, grid...).
2. Define possible components beyond primitives.

I like approach 1, but it will give a lot more work for developers...

...to implement these new experiences, approach 2 can block the creative mind of the designer and perhaps make the developer's life easier. In the end the hybrid is the most suitable.

Transporting this thinking to the component library seems easy, but there are some challenges:

How to support these possibilities, flexibility and specialized components, to what extent are these components limited?

In a first release of our components on clayui.com, we had taken the approach of faithfully following the specification of the components...

...without allowing too much flexibility. The answer against this was the low adoption in our company, the component library was not seen as something that could help teams create new products or new features.

Developers want more flexibility to create new behaviors, this has resulted in components with large APIs and high complexity with a high degree of maintenance.

The adoption of composition was not adopted at first because we really wanted to get people to follow the specification.

We recently launched Clay v3 with a different and hybrid approach to component delivery. We call it the Multi-Layered API library.

Multi-layered components mean that we have two ways to deliver a component:

low-level - Basic building blocks to provide flexibility so that you can customize and create high level components.

high-level - Highly specific component that tend to cover only specific use cases, limiting their flexibility.

The principles are pretty basic but to be called you need to follow some laws.

Low-level components follow the composition, for example:

<ClayDropDown />
<ClayDropDown.Action />
<ClayDropDown.Item />
<ClayDropDown.ItemList />
<ClayDropDown.Search />

High-level components may also follow composition but may be more specific components with something in common among many teams.

<ClayButtonWithIcon />
<ClayCardWithHorizontal />
<ClayCardWithNavigation />
<ClayDropDownWithItems />

High-level components are built with low-levels, this may decrease maintenance but increase the surface of available APIs.

The benefit of this is that you can come up with a hybrid approach that reaches more adoption and many teams with different tastes.

You can read more about this in our composition documentation: clayui.com/docs/foundatio…

The result is that we have been able to build this approach and many of our teams are happier, we have gotten a lot more adoption even before the official release with the beta versions.

But it was still quite challenging how we can balance the difference between low-level and high-level components. This I can talk about in another thread...

...but what I mean about all this is that it's very challenging to create a component library and make it work for your company.

I'm not saying that following this approach in your business may work, but there is a great chance. First talk to your team, get feedback, and collect developer expectations on components and models.

Our Liferay component library is Open Source and you can access it through Github:

- Github: github.com/liferay/clay
- Site: clayui.com
- Design System: lexicondesign.io

I have been working on this for 2 years and will be very happy to hear your thoughts and experiences.

Our Github repository is full of very interesting thoughts and speeches. Explore our issues and PR's 😁