Pipedrive's journey to Convention UI
By Kaarel Metsaots, a Product Designer at Pipedrive’s Platform design team. Kaarel has been responsible for helping Pipedrive to create a design system to make designers and developers more productive.
When I joined Pipedrive almost 3 years ago the company started growing its headcount fast. Our app was looking more and more inconsistent throughout. After small design inventory was conducted the problem of inconsistency across the web app was obvious to all of the designers. We were all over the place with more than ten buttons, five tabs and multiple different popover and menu designs. Solutions were needed as the company would have more designers and developers joining us than ever before. We assumed that communicating the correct usages of components and patterns would become a necessity to keep design and user experience consistent.
I hadn’t worked on design systems before I dove into creating one. I had run a small design company that didn’t work out well for me. I had previous experience with HTML, CSS and JS, mainly working with Bootstrap or Foundation to put together websites. To this day I say that I learned more coding and design skills in my first 6 months at Pipedrive than in the previous 5+ years. Pipedrive has been super supportive of people taking the initiative and I was trusted to pursue this effort, for which I’m forever grateful.
In this article I will share my experience of creating a component library called Convention UI (CUI), my failures, and what I learned from them.
What we needed?
As the app grew we were wasting more and more time on clearing up the design and technical debt. Stressed about how things were getting outdated fast and how developing the views of newly designed features was taking up so much time from developers and designers, it seemed that we were putting out fires instead of doing our work. Designers were wasting time on redesigning the same button and developers on refitting the code – things were bad and getting worse.
Conducting a design inventory gave us something to grab on to. It told us that there were major inconsistencies all across the app. We had more than 5 different designs for buttons (and I don’t mean colors here), 5 different types of tabs, ~100 different font-sizes and 400+ colors scattered around our CSS files. In general, there was a lot of code and design that was actually intended to do the same thing but didn’t.
Using our app and clicking on similar looking buttons led to different behaviours, clicking on the different looking buttons led to the same behaviour – it was safe to assume that we were confusing the user. As a designer, I felt that we were failing to deliver a consistent experience.
The designers were not the only party having issues with the way things were. Developers had to recreate a lot of code and that was the main reason why we had almost 100 different font-sizes in the CSS files. Some of the components existed, but some developers used them, some didn’t. Most of the design or code related updates had to be done manually across the different features, thus resulting in more hacks and inconsistencies.It was far from ideal for both parties.
So, we reasoned that if we could save even one of our developers from debating pixels of smaller components like Avatars or Buttons with a designer, and a designer could rely on having pixel perfect components in place, then we could save the designers and developers days of design and development time in the long run.
History of building a component library
We started putting together some concepts of the component library about month or so after I had joined Pipedrive. One of our product designers at the time had prepared some of the smaller components like buttons and input fields that we would like to use in the web app as HTML/CSS. At the time I was sharing a flat with a longtime friend of mine who had an exhaustive knowledge of JS and was happy to lend his knowledge to help me out with coming up with a JS based concept to present to my colleagues as a proposed solution.
When I showed the concept to my team lead, he thought that we should talk to someone from the engineering department before going too deep into it. He set up a meeting with one of our engineering team leads, and we showed him the concept how we’d imagine this library working. During the meeting we found out that having just pure JS functions that would spit out HTML/CSS wouldn’t help us at all, as the app was built on Backbone. This meeting was, I believe, a checkpoint that set us up for creating CUI. A Backbone.js based solution based on the original concept was created and we got to test it out. Although the CUI versions 0 and 1 failed because the technology was not entirely fit for this purpose, new technologies like React were around the corner and we were not about to give up.
The second version of Convention UI drifted in the right direction. I had taken all summer to teach myself React and believed it to be the silver bullet we were looking for. I took all the work that had already been done for the previous versions and converted it to React – I even added some extra components to sweeten the deal for developers to test it out. I was really happy about the BEM in the CSS and PostCSS processing, and about writing React components in ES6. I had a lot of fun learning these new things, but as the end of the summer neared I realized that I hadn’t actually produced anything else tangible other than knowledge about the new technologies – panic ensued.
I was a designer who had learned something new, but not the principles and best practices behind programming. I had just hacked something together to prove the point and had failed to communicate that.
When developers started showing up at my desk and asking complex questions I realized how out of my depth I was. How could I, a designer, maintain a component library? I definitely needed help. As the summer ended, so ended the endeavours of CUI version 2. The company did not gain much in terms of production ready code, but some of the key members noticed the time and effort that I had put into learning and testing the approach out on React.
The real learnings from the second version of CUI came later when I was given actual feature work. I started my next project – creating the design for the Statistics Dashboard that was supposed to give Pipedrive users a good overview of their key metrics. I still kept working on the CUI, but feature work took more and more time to the point I was only focused on that. After finalizing my initial designs, I started working closely together with the team that were supposed to develop this feature and it turned out that they were going to do this in React. This was the point where things started to turn around. The Dashboard project used some of the components that we had defined for the CUI at the time, but the same problems started popping up that I hoped a component library would take care of. I was handing off designs with pixel perfect dimensions, but the resulting output in the code had different dimensions – I was frustrated. I voiced my concerns (in retrospect, I think even too loudly and bluntly). One day, Lembit Lõpp, a front-end developer who sat at a desk behind me during this project, started asking questions. “Will there be multiple lines of text here?”, “Is this true for the whole list or just for the first element”, “Is 13px enough?” (we had had 8px grid in place for ages). Something that really got me was: “Then provide correct documentation!” – I had overlooked something so very crucial.
I had made no efforts to communicate the specifications, behaviour, and usage of the components that I had designed for the dashboard. I felt stupid. Pixel perfect was not good enough. Lembit took a well-deserved vacation soon after.
Christmas was here and it was really quiet around the office. I felt that I could put in extra effort without anyone distracting me. I planned to do all the visual front-end code that I could for the Dashboard before everyone came back. I was going to use CUI and React to do it. When Lembit was back from his vacation, I heard one of the most encouraging sentences a developer could have said to me at the time: “I wish all the designers coded”. All that I had done was created some extra components for CUI version 2 that could be used in the Dashboard – the time and effort to learn something new had paid off, at least for me.
After the Dashboard project ended, Lembit effectively advocated for similar efforts and helped set in motion the creation of a team that would be responsible for the code side of Convention UI.
I had worked on two iterations of our component library that had failed miserably mostly because I decided to work on it alone. Only when I decided to communicate the value to others did it gain traction. I learned that building a company-wide library was a team game.
The most important thing I learned was to make sure to find projects and people you could test your concepts out with. People who get excited when they encounter new technologies and approaches are the best kind of people to have around.
Documentation is crucial
With the Dashboard project over and Lembit moving to his new team, the planning phase for CUI version 3 was started. The Core Front End team (COFE) would take responsibility for the CUI’s code and several other internal front-end tools that the company had created over the years. The questions that were asked by Lembit during the Dashboard project made me realize that documentation and specifications play a crucial role in developing and designing usable components. What was true for Dashboard components was true for Convention UI components.
There were not any good examples of component specifications to draw inspiration from. I once again found myself a bit lost. Learning from the mistakes that I had made in the communication process with the Dashboard project I soon decided to approach Dmitri Nikolajev, my manager at the time, to give me some guidance.
We scheduled a few sessions to come up with a specifications sheet generation framework (that’s a doozy). He decided that it would make more sense for me to come up with the solution myself and participate as a listener while sometimes interrupting and asking questions on how I’d see the documentation/specifications part working. The approach worked like a charm and cleared my head – I just needed someone to bounce my ideas off of. We designed the specification sheets to be understandable for all the main stakeholders; product managers, developers, and designers. After I created 2 specification sheets of the older components and 1 of the new component that were to be added to the CUI, we validated the framework with COFE team and the first iteration of component specifications sheet was born. COFE of course built the components with no extreme deviations from the specifications provided and with excellent code quality. COFE was a success – a bridge between engineering and design.
When the specifications sheet and component creation process was in place the design team decided that, similar to COFE team, we as designers should have a group of designers responsible for the CUI. The mission of the group was to review the specifications sheets that I was about to start putting together.
Thanks to COFE, the CUI version 3 became a reality in no time. The team decided to divide the CUI codebase into production-ready HTML/CSS (almost what we started with) and React components based on that library. All new features were now to be developed using the CUI which saved our developers time and made it easier to keep the features designs up to date.
The 1:1 meetings with Dmitri had been extremely beneficial for coming up with a great solution. He provided a different angle and asked a lot of questions just out of curiosity. I loved having someone to bounce my ideas off of.
Share your knowledge
Sharing knowledge with other designers was a weak point. I had directed most of my time towards working with developers and left my peers to figure it out on their own. Luckily we have a channel in Slack where we, Pipedrive’s designers, share the work that we’ve done during the last week(s). We share the topics that we worked on and images related to them. While I was now pretty happy that we were on track with the code and specifications, the designers were still lagging behind and not using the components as defined in the specification sheets.
We keep all Convention UI related design files in an Abstract (an app which helps us to store and version control Sketch design files) project where almost every component has its own library file, and if not that, then just a specifications sheet. The problem that became evident from the pictures shared in the channel was that designers were either not in sync with the specifications or they had issues using the tools. I decided to hold a workshop on the topic as I reasoned that it would help all designers in different ways. It would allow me to see what the issues might be, and other designers – if nothing else – to learn the technical skills needed to use the components.
The workshop I put together challenged participants to build one of our web app components from scratch: the filter menu. The workshop covered everything from creating a project in Abstract, linking component libraries to it, and using CUI components in the component we’d be creating. As a bonus it made sense to show designers how to create sketch symbols. After I was done with the workshop I collected anonymous feedback to see if there were any loose ends or if anyone still felt left out.
Sharing knowledge is important. I had somehow assumed everyone to be at the same level with tools and technical skills but that wasn't the case at all.
This was the first workshop that I held on the topic, but now I can see this becoming a regular thing to help my fellow designers with keeping their technical skills and knowledge about tools up to date.
What’s next for us?
Building and maintaining a design system has become a full time job here at Pipedrive.
Today we have almost 30 components set up for building the web app, but that does not mean that we’ve created a usable design system yet.
Many of the components still require a good pattern example, do/don’t example, or a guideline so our designers and developers would be able to work with the components correctly. We’ve just laid the foundation.
Recently a Platform design team was assembled from the group of designers who were responsible for providing me feedback on the specification sheets. Our focus is currently set on identifying all patterns across the web app and improving them with Convention UI so we could document them to serve as guidance and inspiration for our designers and developers. If we have the process for web app and CUI cemented, we want to extend this approach to mobile platforms also. We’re now keeping a keen eye on React Native as engineering has already started to do research on the topic. Once we have all platforms covered then we can say that we truly have a design system.
These have been some of the highlights during my time at Pipedrive. The people here are crazy smart and I feel privileged to work with such awesome people as I get to learn something new every day. The experiences at Pipedrive have led me to believe that everything is achievable with the right people and by not being an ass yourself.
But wait, there’s more.
I want to share a list of links to articles and resources that inspired and helped me.
Also, if you also want to work with awesome people, check out https://www.pipedrive.com/jobs