How we keep our styleguide up-to-date across the GoCardless design team

A new project, ready to go with our GC styleguide

Like a lot of Design teams, we use a styleguide at GoCardless to document our visual language, maintain consistency, and turbo-charge our design process. However, we’ve found that the benefits of a styleguide diminish in tandem with how out of date it gets, and managing a styleguide and keeping it current can be an arduous task.

I was charged with creating a styleguide for the GoCardless dashboard shortly after joining last year, and have come up with a simple way of keeping it up to date and the rest of the team in sync.

Sketch templates

Like most startup design teams, we use Sketch for the vast majority of our work. So it made sense to choose a Sketch template as the medium for our styleguide. It slots into our process nicely as when you start a new project you just go File > New from template > GC styleguide and 💥 you’re up and running with all the latest assets, colours, typography and components.

Managing Sketch templates, however, is a bit of a faff. To create the template initially you just save your ‘master’ styleguide as a template. But there is no ‘update template’ feature so you have to do this every time you update your styleguide, as do the rest of your design team. (And god help you if you spell it differently and want to remove the duplicate, that /templates folder is hidden af).

In a busy Design team this ends up being quite a large barrier to maintaining the styleguide. After putting so much time into the first version of our styleguide it quickly fell out of date, rendering it useless. So I decided to have a pop at solving this.

A peek at some of the components in our GC stylguide

Dropbox and symbolic links

My solution consists of a cunning combination of lesser-known file-storage app ‘Dropbox’, and a little command line tool known as a ‘symlink’ (see edit).

Dropbox’s role is pretty obvious: the master styleguide lives on it, everyone on the team has access to it so when it’s updated, everyone gets the latest stuff. It has a degree of version control too, so if someone screws the pooch and deletes or overwrites it you’re protected.

The symlink’s role is also pretty straightforward. A symlink is essentially a reference to another file on your computer, that you can place anywhere you like (think desktop shortcuts in Windows XP or the like). The result is that you can link from your master styleguide in Dropbox straight to the Sketch templates folder with a teeny line of code you can pop in your terminal.

ln -s ~/Dropbox/Design/gocardless-style-guide.sketch ~/Library/Application\ Support/com.bohemiancoding.sketch3/Templates

The command above would create a symlink in your Sketch/templates (the ~/Dropbox/Design/gocardless-style-guide.sketch bit) folder connected to your ‘master’ styleguide in Dropbox (the other ~/Library/Application\ Support/com.bohemiancoding.sketch3/Templates bit). The result is that whenever your master styleguide is updated, the rest of the team’s styleguides will be automagically updated too. No more messing about with templates in Sketch, one less hoop to jump through in your quest toward a living styleguide.

What a perfect system, you sure are smart

That’s very kind, but it’s not all champagne and caviar over here. There are a few shortcomings in this system that it would be remiss not to mention.

The use of Dropbox as a home for the master styleguide has its shortcomings. It means you kind of have to keep it shipshape at all times, which is not all bad, but it means you can never leave it in an unfinished state (unless you really want to upset your fellow designers).

Also conflicts in Dropbox can be confusing and messy. I’ve found that it’s easier if one person is responsible for maintaining the styleguide to avoid them, but this is obviously not ideal. Storing it on Github could mitigate this, as it would give you tools like branching and pull requests, and mean you could save locally and go home without upsetting anyone. However I don’t know how well it works with image and .sketch files (look out for a future edit as this is something I will probably explore).

This setup is also very reliant on humans maintaining it whenever there is an update to the app or vice versa. In a perfect world these two would be aware of and talk to each other, and update themselves when they detected a changed. I’m not smart enough to figure that one out yet, but do let me know if you have any ideas 🤔


Thanks for reading, I hope that you found something in there that was useful. Please do comment below if you have any questions or thoughts on how this setup could be improved.