By Scott Mathis, SMTS UI/UX, Clarity Design System Team – VMware
A couple years ago, four of us at VMware launched the Clarity Design System. Since then, we’ve gone from a small, scrappy team to being the second most popular open source project at VMware. We’ve learned a lot in the process, so we decided to share some of the insights and lessons learned with the broader open source community.
If you don’t know the Clarity Design System, allow us to introduce it. Clarity is an open source set of UX guidelines that serve as the foundation for a framework of HTML and CSS deliverables upon which a library of Angular material and components is built. It takes a lot of the UX and UI basics off developers’ shoulders so that they can focus on workflows and interaction. Since we unveiled Clarity Design System, dozens of VMware product teams have adopted it, as have numerous external users.
Here are the 10 biggest lessons learned from launching Clarity Design System:
1 – You can move too fast
As often happens with projects like this, we just needed to get something out of the door quickly when we started. We didn’t focus as much on the building blocks (i.e. architecture, proof of concept or early-stage explorations). We felt like we were in survival mode, so many of our early decisions were just about staying alive. In hindsight, that was a mistake. Daniel Kahneman wrote a book titled “Thinking Fast and Thinking Slow.” When you’re in survival mode, you’re always thinking fast. A lot of times, that’s not going to give you the best results. Sometimes, what is good enough right now isn’t really good enough long-term. We made it through but would have benefitted from more deliberate and analytical thinking early on.
2 – Don’t be too nice
Starting out, we set a precedent that we would step in and fill knowledge gaps. That ended up being something we’d struggle to both live up to and live down. For example, someone posted a question on Stack Overflow looking for good ways to learn more about Angular. Another person responded with some tutorials to use and then said, “if you really want to learn Angular, go use Clarity and if you run into an issue, file a bug and they’ll teach you how to use it.” It’s advantageous to be a good open source citizen, but you don’t want to be so helpful that you take time away from your core work either.
3 – Know why you’re saying “yes” or “no”
When you’re in survival mode, you’re constantly figuring out when to say “yes” and when to say “no.” You’re under massive pressure to simply make decisions, but you still need to have the capacity to understand what you’re really agreeing to or dismissing. What does a “yes” really commit you to? What will a “no” cost you down the line? You need to take the time to think through these things. You should also have a way of ranking every “no.” When you’ve said no, how absolute was it, and how high on your list of “want-to-dos” should it stay in case you find yourself with the resources to tackle it later?
4 – Know your dependencies
Your dependencies are key to moving you forward. Just as importantly, any issues they have are going to cause problems for your own project down the road. We learned the hard way that we needed to understand our dependencies and stay on top of them. We had a few rocky moments where Bootstrap Angular broke on us, for example. We got excellent, responsive help in addressing the issue, but it could have been a disaster. Because we didn’t expect the issue, we had to scramble, which wouldn’t have been the case if we had a plan already in place.
5 – Be transparent
This is something we got right the first time—we’ve always been careful to be very transparent with every user. We committed early on to one tool or “source of truth,” first using Jira at VMware and then moving fully to GitHub once we were open source. With one source of truth, people can go to one location to figure out what we’re working on, what’s important to us and see what’s in our pipeline. That transparency and open line of communication build and sustain trust.
6 – Commit to code quality and stability
This is huge. It allowed us to do weekly releases as a pre-1.0 product so that we could consistently fine-tune the user experience of our project as it evolved.
7 – Don’t delay refactoring
As our complexity increased, refactoring became harder and harder. A great example was with buttons. When we started with buttons, we just needed four or five colors, rounded corners and some sort of click interface. Refactoring wasn’t a big deal; it just took a week or two. Now we have small buttons, icon buttons, drop-down buttons, button groups, buttons in modals, buttons in wizards and buttons in data groups. A change to a button can break a lot of different things. Spending a little more time with framework and architecture in the beginning can save a lot of grief later on.
8 – Trust your robot army
This is about continuous integration and unit testing. In retrospect, we didn’t put enough effort into this at the beginning. Then, as our complexity increased, it got harder and harder to add it in. Put the time in to automate everything you can as early as you can. Real, robust, continuous integration on a project that’s only a few hundred lines is easier than when it’s a lot larger and you have more priorities and pressure on your project.
9 – Be a good taker and explain how permissive you want to be
We didn’t establish clear guidelines for contributing to Clarity early on and that created an unintended hurdle for people who wanted to engage with our community. In our defense, we didn’t know then what we know now. And when we first started building, Angular was still in alpha. But because we didn’t have clear guidelines, many early contributions caused regressions or breakages that we then had to go in and fix. There’s a balance to reach here around permissiveness. If you’re too strict, you make it harder for people to contribute. But if you’re too permissive, you risk introducing unstable or untested code into your project that you then have to take ownership of.
10 – Don’t worry!
Overall, if I could talk to myself back then, I’d tell myself not to worry about survival so much and make decisions as if everything will end up being fine. One of the reasons I like to work in open source is that if you have good intentions, people will feel positive about your efforts in return. You have a lot of people rooting for your success and wanting to make it happen.
Looking ahead, we’re proud of what we achieved with Clarity Design System on bare-bones components and a lot of hard work. We plan to keep growing and building the system beyond a 1.0 build. We’re also investing more time in continuous integration and updates to Clarity Ui, aiming to move to nightly builds and automated delivery of our web page before long. Watch this space! In the meantime, download Clarity Design System from GitHub here and start exploring its user interface.
Stay tuned to the Open Source Blog for more updates on Clarity Design System, and be sure to follow us on Twitter (@vmwopensource).
