Rebuilding the Perch UI – creating a pattern library

This is the second in a series of posts about the work I’m currently doing on the Perch CMS user Interface. You can read the first article introducing the issues we face here.

The existing Perch UI has developed organically over the last few years. Our reference has been the original and updated UI designs created for us by Nathan Pitman. Rebuilding the interface gave us the chance to think about the process of working on the UI and what we could do better in the future.

Our goals

In addition to creating a more usable, more responsive interface for Perch we were keen to create for ourselves better way of working to improve and enhance the interface in the future. Currently the only reference to the UI is Perch itself and some flat designs. Working on the UI involves making changes directly to the core product, in this case fairly sweeping changes. Changing markup can require changing Field Types and helpers within Perch, trying to do that directly in the product leads us to tweak what is there rather than consider what might be ideal and then figure out how to change it in the product. It also makes it hard for me to work on the front-end, without also needing to run back-end changes via Drew. As I’m often working on the road, that kind of collaboration makes work slow to a crawl.

I wanted to be able to document our decisions somewhere. A key goal for me is to be able to link up any resource I have used to make a decision about something – in order that we can refer back to that in future and check it is still regarded as best practice.

There is another group of users who need to understand how the Perch UI goes together – anyone who is developing an add-on using the Perch API. Currently they have to inspect our elements to figure out which classes to apply to their elements to make the add-on look like the rest of Perch. I felt that creating a reference to the UI would be really helpful to these users too – they could just look up the HTML that would create the smarter, use our classes for the various buttons and input fields far more easily and consistently.

We needed a pattern library

I spend quite a bit of time at conferences, and so I’ve been lucky enough to hear people like Brad Frost talk about style guides and pattern libraries. I was quick to decide that this would be a great way forward for Perch. A pattern library that was separate to the product would make it much easier for me to work on CSS and markup.

My first thought was just to build this in HTML and CSS. Ultimately that is the output format, so why not just build a set of HTML pages representing each element in the interface? I started down that path, however what I very quickly realised is that there is a lot of duplication in an interface like the Perch UI. I was copying and pasting elements from one page to another, then I would realise I needed to change the mark-up around a form input and have to search and replace though all my forms to update it.

I was also having to encode chunks of markup in order to be able to display reference markup on the page, and change all of this every time I changed the markup of any element. I could very quickly tell that even if I got through the initial rebuild of the UI in this way, keeping this up to date was going to be a huge hassle, and probably wouldn’t happen.

Working pattern library first

I realised that what we need was a way of working with our pattern library that encouraged us to work pattern library first. Where the starting point of redesigning any element was the pattern library, and not Perch itself. That way the Pattern Library would become the source of truth about any element, not something we tried to remember to keep up to date.

While I could use Gulp or another tool to write scripts that would build the CSS to be imported into Perch, working directly in HTML was never going to be an efficient or enjoyable way to work. It was never going to encourage a pattern library first method of working, as it would be quicker and easier to work directly in Perch.

Finding a pattern library tool

As an industry we just love our tools, so I knew there would be existing things out there. I had a look at Pattern Lab and the Node version and poked around the tools and resources mentioned on styleguides.io. However many of these tools were very focussed on creating pattern libraries and style guides for websites. In our case we were creating a pattern library for an application, and it felt that in most of the tools I downloaded or looked at the demo for I would be fighting against the website focus while building our library.

While thinking about this I saw a tweet mentioning a tool called Fractal. It’s the pattern library tool used by our friends over at Clearleft, and developed by Mark Perkins. The mentions on Twitter sounded very positive in terms of the issues I had already identified with existing tools. Positive enough for us to test it out. Within a few hours we were certain we had found the best tool for this particular job.

Reasons to love Fractal

The key thing about Fractal for me is the fact that it doesn’t make many assumptions about the sort of thing you want a pattern library for. It doesn’t seem to care if you are creating a brochure site, or an application mostly consisting of different forms and widgets.

It leaves the naming of components up to you – we have chosen to go with the naming that Brad Frost uses – atoms, molecules and organisms – however we could have named our patterns anything that we liked.

Fractal is file based. This makes it very easy to move patterns around in the file structure, rename things or break things down into smaller components as needed. As we started to work with it we quickly found that our initial stab at organisation needed some work, this was no problem, we simply rearranged the files and committed the new structure into git. Being file based makes it easy to collaborate using git, and use the commit messages to see what each of us has been changing in the library.

Fractal allows us to document decisions alongside the pattern in the Readme. I’ve been collecting information about accessibility and best practice, I can add these links right into the Readme for that pattern. In future we’ll be able to look up details of any decisions – and our Add-on developers will also be able to reference this information and see why a certain HTML element was chosen, or an ARIA role added.

The issue that I had with repeating the markup of elements is removed when using Fractal as we can reference smaller components in other files. For example if I create an “atom” for a button, and then want to include that button in a toolbar, I include the button atom rather than writing out the HTML in the new pattern. This has meant we have very quickly been able to build up larger pieces of the interface.

From any pattern we can take a look at the template that generates the pattern, the Sass used to create CSS to style it and the rendered HTML. No more encoding HTML to display it on my HTML style guide pages!

Getting from Fractal to Perch

It was important to make Fractal our source of truth. Drew created a build process for Perch that builds all CSS within Fractal – and not inside the Perch build scripts. The resulting CSS is then copied into the Perch build. This process ensures that any work on the front-end happens inside the pattern library first. It can’t get out of date with the UI in the product.

We’re still midway through the process, however the speed at which we’ve been able to create different patterns within Fractal has been eye-opening. An unexpected benefit is how achievable this rebuild feels when working in Fractal. Instead of having the whole interface in front of me making me feel as if I am chipping away at a vast task, all I need to think about is the single component I’m working on. I feel more of a sense of achievement as each item takes shape – we can mark individual elements as “done” and have that feeling of completing tasks each day.

Once we have launched the next version of Perch that includes this new UI I feel that we’ve developed a system that will keep our Pattern Library up to date as we make changes, and ensure it remains a great resource for us and for our add-on developers in the future.

Pattern Library Resources

A short list of resources I found while researching pattern libraries and style guides: