Applying a new pattern library to legacy code

31st Aug 2017 / By Michael Gunner

Pattern libraries, or component libraries, or “front end style guides”, are all the rage. And rightly so – it’s high time we moved on from treating web projects as a bunch of cobbled together “pages”. The trouble with that approach is its lack of flexibility, the design and build cannot be used for anything else. This is despite the online presence of a business being so much more than just its website.

Many companies are beginning to appreciate that they need to think bigger and wider in terms of the design of their digital self. A pattern library gives them a tool they can use to apply their branding across all their various digital touch points, whether it be a website, landing pages, Facebook pages, Advertising or E-Commerce.

The only problem with pattern libraries, is how we can get them to work with legacy code. Ideally, a pattern library would be developed in tandem with a new product. And if you’re starting fresh, that should absolutely be the case and I would encourage you to even look at building the pattern library into a component library (basically, it has an API).

But if you’re being asked to develop and apply a new pattern library to an existing project, this presents quite a few technical (and mental) challenges. How do we know we’ve covered all our bases? How do we develop our pattern list? How do we simultaneously refresh the mark up and develop our patterns? How do I get my head around another developers code, approach, thought process?

Audit the code

Before you do anything, run through all of the legacy code. Get your head around what’s going on, what is responsible for what, and how it’s put together. Then, preen the mark-up, one file at a time, of any mark-up that isn’t required, being careful to maintain functionality. Use this part of the process, if you can, to assemble your list of required patterns, working closely with the design team. Identify opportunities to condense and simplify.

Remove all existing CSS and bunk classes

That includes all those Angular/React/Bootstrap CSS frame works. Your pattern library replaces the need for these “solve everything” CSS files. Don’t be afraid to gut them from the project, even if when you then reload, everything’s lost styling and structure. You’ll get that back soon enough. If you keep them, you are likely going to encounter issues with conflicting classes and styles between them and your library and you will just be increasing downloaded CSS. You can always pull back if there’s a part you still need – for example, you may want to keep the “datepicker” or the “tabs”.

Handle the layout and grid first

It’ll make the task of applying your library to the legacy code much more manageable if you look at layout and structure first. This is a given for any web project really, but it’s especially so in this case. If you’re changing the grid, use find and replace, or regex, to handle swapping out class names on elements.

Have a back-end developer on hand

Someone built that legacy code for the application or website you’re applying your library to. Or, there’s somebody responsible for it who maintains it. Having an open channel of communication between yourself and this person will help make your project run more smoothly. Instead of spending hours trawling through folders, try to understand how the site is put together, you can ask them. The creation and implementation of your patterns is a cyclical process so expect a lot of back and forth between design teams, UX and development to achieve consistency.

Don’t worry if you cannot get everything perfect

There may be parts of the project that you can’t apply your beautiful BEM class names too. Flag it with the back end developer, but then let it go. Your pattern library itself can still include your BEM class names. For example, a project I worked on was using an Angular directive for tabs and I had no control over the class names or mark up. So in my library, it just ended up something like this:

mk-tab, .tab {}
mk-tab-content, .tab__content {}


One pattern at a time

Don’t go all out and start throwing patterns at the build all at once. It sounds obvious, but you really should apply one at a time. Use find and replace in sublime (or the equivalent in another editor) to help you find all the mark up you need to revise and apply your new pattern too, and do it for all of them.

Test until you can test no more

Honestly, I cannot stress this enough. You need to be sure that what you’re doing is working, so keep testing as much as you can, across all the devices and browsers you need to.