Magic Paintbox

Aegir Hallmundur
Sep 13, 2018 · 10 min read

We made a pattern library! We are still making a pattern library.

It’s been an interesting process, sometimes fun, sometimes frustrating, sometimes boring, but we’ve learned a lot. The benefits have been greater than we realised, partly as a result of the problems we had making it.

First, a quick intro on what a pattern library is, and isn’t, to us at Firefly. Other definitions are possible.

  • It isn’t brand guidelines. We have a separate brand document already. This is not that.
  • It is a practical tool. Ours contains functional graphical representations of real product UI we can use in designs to help us represent and test our ideas in context.

Other ways of making pattern libraries exist, including combining front-end code with a design tool so what you design is immediately usable in your product. That sounds amazing, but we didn’t make one like that.

Why? Because it wasn’t practical to do that. We use high-fidelity mockups and prototypes because we get the best results in design discussions and from user interviews from them. We needed a tool to help us to do that better. It needed to cover the full product as quickly as possible.

We are making a front-end pattern library of code, but that involves refactoring old code, testing and all sorts of other things that are different from making a design library. We’d get caught up in the problem of joining the two processes rather than making anything, so, they’re separate. For now.

The product itself

Firefly is a learning and teaching tool used in schools. It’s primarily web-based with a set of supporting apps for iOS and Android. At its core it is a Virtual Learning Environment handling learning resources, course structure, assessment and the like, but is made significantly more powerful by features supporting the administrative, pastoral and non-curricular activities schools need, along with a suite of features specifically for parents to stay involved in their child’s education. Schools can also choose from four design themes which we can customise for them with their own colours and logo.

The four themes, showing an example teaching resource

Why we needed a pattern library

  • We don’t want to have to keep recreating the same UI elements over and over again.
  • We also don’t want to be copy and pasting those things from old designs, risking a confusing mix of current and superseded designs for elements in our work. We wanted a ‘single source of truth’ for our UI design.
  • We want to put all of our design time and effort into designing (and redesigning) things, not recreating the stuff we already know.

What we get from the pattern library is time and freedom to be creative. I’ve seen people claim pattern libraries are the death of creativity and innovation in design. For us, it’s the opposite of that. We work with rough sketches and doodles like any traditional design until we’re ready to see how it works in its natural environment on screen. No redesign or new feature sits in isolation; we need to create it within the design environment of the existing product. We use the pattern library to put the props and furniture in place to create that context and realism.

Later in the process, we go over what we’ve made and work out what we already have, what’s a pointless variation, and we end up knowing what’s actually new and needs to be created and added to the library.

The winding path

Starting out: the dawn of time

We had a large Illustrator file with various elements drawn up in it with variations labelled and a layer on top showing the redlines and margin measurements.

It worked OK. Not great, but OK.

Look at all the red text

Sketch had been around a little while, but at this point it seemed full-featured enough to give it a go, and of course we immediately switched to it. Scaling symbols and having them do sensible things was quite a selling point, along with everything else.

Much manual labour

This was before Sketch shared libraries existed.

We’d copy and paste from there to whatever we were designing. If we updated something in the UI we’d have to go and copy and paste it all over again. Yup, painful.

We found we had a lot of shared elements that weren’t themed and needed to be included in all four theme files. That would have magnified the grunt work considerably, so instead of that, we moved everything into one Sketch file. Moving the symbols and all the embedded dependency symbols was hard work. I wouldn’t recommend anyone doing that.

Part of the pattern library for one theme, arranged neatly

We like to keep the pattern library as readable and scannable by eye as possible, so we keep things arranged on the page in a particular way so that they make sense. By default Sketch puts everything in one long line in the order it was made. Rearranging things was a pain, and even now we sometimes have to go chasing symbols down because they’ve been pasted… somewhere. (The plugin ‘Find Instances of Symbol’ is useful for this — more on plugins at the end)

Filing, naming, renaming, re-renaming, re-re-renaming

Some of the work of building and maintaining a pattern library feels like how filing was in a pre-computerised office. Often dull, worthy, repetitive work tidying stuff away, but without which the office wouldn’t function well, if at all. The bonus of it is that it feels very satisfying to have done it all.

Sketch lets you put a slash in symbol names and it creates a dropdown tree for you when you go to insert a symbol. It helps with keeping things organised, but you have to work out a whole new taxonomy for your symbols. Chances are that you, like us, won’t get this right first time.

The Sketch dropdown thing in action. Funnily enough, we don’t use nested dropdowns in our product.

Because we were using overrides, including ones for embedded symbols, we ran into the problem Sketch had of truncating symbol names. Choosing a new symbol when you can’t see the last bit of its name was a problem, so we went for abbreviations and a wide, flat structure.

That made things hard to find. We had this giant scrolling drop down list of categories of symbols. It wasn’t a good thing.

So when the truncation problem went away, we renamed our symbols. Things made more sense and everything was easier to find.

If naming things is hard, renaming things is harder. Renaming things again is miserable. Renaming them yet again makes you question your life choices.

The refinement

We ended up with three scales of symbol: Construction, Pattern, and Part.

  • A part is the lowest, most granular level. It’s stuff like a text label for a button, or a dropdown container, or a button background, or an icon.
  • A pattern combines parts into a useable functional bit of UI. So a button pattern might be made of a label part, a button background part and an icon. The parts then appear as overrides when we use the pattern and we can set the button to appear active or disabled, change the label, the icon, colour, or whatever.
  • A construction is a utility bit of design, something we often include in mockups as furniture, and sometimes as starting points to modify for something new. For example, we have one showing the page navigation for each of our four themes, it’s set to show a page fairly deep in a sample navigation structure. It’s not in itself a pattern, but it saves us loads of time to have things like this. We don’t use them often, but we have ones for main nav, whole pages with example content, common dialogs and so on.

These three labels sit within our naming convention and let us very quickly find and choose the right thing when we need it. It means Sketch shows a list of parts alongside the part you already have, rather than a mix of parts, patterns, and constructions. Very neat and tidy.

Roadblock: the colour problem

We tried the Craft plugin from Invision, but the UI meant we quite often accidentally changed entries we wanted to keep as fixed, shared values. There was no undo, so we stopped using it.

Top: colour chips in Sketch. Bottom: the extra documentation we do for Zeplin. Neither is ideal.

We now use colour chips defined as symbols in Sketch and use them with masks to apply colour to things. It works for mockups but we’ve had trouble with Zeplin when we want to create developer-friendly documentation. It will show the colour, but you can’t get the properties of the mask for it — so if that mask has rounded corners you can’t get the radius. Zeplin also assumes that a particular colour can only be assigned to one variable name. Imagine how often white is used for different things, it gets to be a problem.

We’re hoping colour libraries are on the Sketch roadmap. So much of what we’ve hoped for has been added, so fingers crossed for that too.


…or, our glorious future

On top of that, what it’s taught us about our product is incredibly valuable. At the start of the process we knew our product (we made it, after all), but now we feel we have a better, deeper understanding of our design language.

Documenting this design language has given us fluency in how we use our product’s vocabulary and grammar. Like any language there are exceptions, slang, words borrowed from elsewhere, things that don’t appear to fit, but now we can understand their value (and cost) and decide what to keep, what to replace and what to ‘translate’.

Our pattern library is not yet complete, and probably never will be. We still have legacy UI in the product that we haven’t brought up to date, and there will be things that we currently think are vital and core to the product that’ll get removed and replaced at some point.

What we won’t have to do is guess. We know the importance and value of all the elements of our product design. It’s already let us see where we need to make improvements and inspired us with new ideas for doing that.

Plugins and other technology

Tools for working as a team

Very handy for documenting designs, being a source of conversations with developers and the rest of the business, and linking to from Jira. Abstract is starting to add some of its features, but it’s early days for that. If it handled colours better it’d be wonderful.

Tools for working with lots of symbols

Symbol Instance Renamer
Very good if you’ve renamed or copied symbols and want the layer names (and labels in the override panel) to make sense.

Select Similar Layers
Just useful if you’re using Sketch anyway.

Find Instances of Symbol
When you want to delete a symbol but Sketch says it’s in use somewhere. Doesn’t always work as you’d expect, but when it does, oh yes. Very handy for when you’ve pasted in some symbols from another file and Sketch has put some of them… somewhere.

Symbol Swapper
This is handy when you’ve got a symbol that you know is also in a shared library, and want to swap it out without losing any overrides and so on. We haven’t had to use it often, but when we have we’ve been very glad of it.


How the Product Design and Engineering teams at Firefly are…