Maintaining our Pattern Library

How we use Folio and GitHub to manage collaborative Sketch files across the team.

We’re not a big team here in London, the three of us (Claire, Rob & Lee 👋) work closely and collaboratively but we still run into *that* problem of keeping a file synced between a couple of people.

The front end team have started to move our view layer out of Rails over to React making us much more component oriented in the code. At the same time, we’ve moved from Photoshop to Sketch and have started to build out a component based pattern library. Our goal is to have the UI across the site powered by components – meaning that an update to the pattern library would roll out to that component and across the entire site.

Whilst we look to build and iterate on our products in this way, we’re still a bit of a work in progress. We’re in the midst of establishing patterns across the site, and beginning to create a pattern library as a foundation for the future.

Part of the challenge in building the pattern library has been creating, maintaining, and updating components in the library collectively. We wanted an automated way of syncing Sketch files between the team and aspired to have the latest version of the library readily available to work from, limiting inconsistencies and repetition in UI design at Lost My Name.

The aim:

• Have each designer work with the most up to date UI patterns, principles, and guidelines to maintain cohesion across the team
• Create transparency and clear reference documentation for front end developers to confidently work from
• Enable accountability, autonomy and version control for pattern library updates

GitHub and Folio

We took some influcence from the version control systems that we’re already familiar with. GitHub was an obvious choice to host our repository of collaborative files. The software development team use it to manage the code for all aspects of the site and share code without conflict, and we looked to replicate aspects of that system for collaborative design files.

Building on top of Github — we seached for a tool that could help us intergrate version control to our current workflow. We found Folio (check folioformac.com and Folio on Medium) it’s based on Git and it automatically syncs repositories whilst offering visualised version control that’s easy to navigate and restore.

The idea

• Set up a GitHub repository to host collaborative Sketch files and provide a version-control system that we can conveniently loop both the design and development teams into.
• Use Folio to auto-sync Sketch files between our machines and enable unified collaborative input on single Sketch documents.
• Hook Folio (and so GitHub) directly into Sketch so the most recent document can be opened directly from the templates menu.

Setting up GitHub

1 ) Create a team: We got everyone in the team set up with a GitHub account and made sure we were all able to contribute to the Lost My Name organisation. Here it’s pretty simple to create a new team. We just called it Design and made sure the three of us were members in there.

2) Create a new repository: Within the organisation we’re able to add a repository. This repository will host the sketch files and the history of changes made to them. Our’s is called pattern-library, and we’ve set it to private to begin with.

3) Add the team: In the settings tab at the top of the page we can add a team to access the repository. Head to collaborators & teams and hit the add a team dropdown to find the team and add it to the repo. Once the team’s been added, we want to change the permissions of the team from read to write.

4) Copy repo URL: Head back to the <code> tab and you’ll see the quick set up screen again. There you can grab the HTTPS. Copy the URL or keep it somewhere handy.

*If you’re joining a repository that already exists then you just need to hit the clone or download button under the <code> tab:

Setting up Folio

1) Clone Git repository: After downloading and installing Folio, we need to create a project (they offer a 15 day trial which we used to test all this out, give that a go for sure!). When you open up Folio the first time you’ll be prompted by the Welcome to Folio window. Here, select clone Git repository or you can got to file> open remote project.

2) Enter repo HTTPS URL: Now you can pop that URL for your repo into Folio. This will allow GitHub and Folio to talk together:

3) Choose project destination: Folio grabs the most recent file from GitHub and makes a local version on your machine. The placement of the local file is totally up to you ~ it’s just where Folio will sync the latest version of the files to your machine. I created a new folder called pattern-library for now:

*You’ll be prompted to login into GitHub using your username and password. If you run into trouble with the password, then generate a new personal access token, and use your new token as the password. (GitHub help here)

4) Clone: Hit clone to link the GitHub repository to Folio. We don’t have any files in our repo just yet. So you’ll see a message asking you to add files.

5) Add files to repository*: Now that we have Folio hooked up it serves as a visual interface for GitHub. We can now just drag the files that we want to upload to our GitHub repositry and sync them between the team.

*If you’re cloning a project that already exists then you should see the files appear in Folio and sync to the local folder we pointed to when cloning the project.

6) Create your first version: You’ll see the files show up in Folio 🎉 to complete the loop between Folio and GitHub you need to create the first version of the file. Just select the file and in the tool bar on the right, name the version and hit create.

Not only will you see the file appear in Folio, but also the files now synced to your local and on GitHub.

7) Making a change to a synced file: Make a change to a synced file by opening the file from Folio. Double-click or ctrl-click to open. Make changes to the file and save it out. When you save the file, you’ll be prompted by Folio to make a new version of the file. Create the version and it’ll sync that change to GitHub.

8) Set up Folio for the whole team: Now the files are synced up, other members of the team can clone the repository onto thier local machine, make changes, and sync that file back to GitHub.

Syncing GitHub/ Folio to Sketch Templates

We made the decision to point the local project folder to the Sketch Templates Folder on our machines. This means the most recent files that Folio pulls down from GitHub would sit right within the new from template dropdown in Sketch.

It meant we just needed to clone the repo again, but this time change the rooting of the file to point to Sketch’s template directory. It’s tucked away in your User Library:

This does add an extra layer to our workflow. Our proposal at the moment is that if you want to make a change to synced files then open them up though Folio, make the change and version the file. If you want to reference the pattern-library or use elements from the library, then just open it from the templates folder. This way, we hope to reduce any unnecessary changes to the synced file, and give freedom to the designer to hack away at a template file that would include shared styles, shared type styles and our responsive grid.

Caveat: We’re pretty new at this and would love to know how your team is solving the same problems we’re facing. We’re constantly looking for ways to improve our workflow and cross discipline collaboration.