Managing Style Guides at Shyp

How we use Github for design collaboration

When we rebranded Shyp last year, there were three of us collaborating on the product design. As we worked, we implemented a style guide that could help us maintain a consistent aesthetic between designers. We now have a style guide for each of our products and they have become great resources for designing new features and moving between teams.

Like most teams, we use Dropbox to share files and collaborate on projects. If a designer wants to change the font size of a file, they simply make the change, press save, and the rest of the team can use the updated file. This is great for ongoing projects but can be dangerous for something like a style guide. There is very little accountability when it comes to overwriting work and style guides need consensus from the team before a change is made.

Why Github Works for Us

When we thought about what our ideal workflow might be, we realized the engineering team already had an established system for sharing code without conflict. Using Github, engineers propose changes to a codebase, come to a unified agreement about the change, and push it to production. This was exactly the process our design team needed for files like our style guide; we needed a way to require team approval before saving over a previous version of our style guide.

Designers should be empowered to recognize flaws in a style guide and propose changes to them. Using Github is great for this because if someone proposes a change, others on the team have the chance to compare the differences to the current version, provide feedback, make modifications as necessary, and agree on a new version

Commit → Review →Update

Although we were wary of introducing a new step in our workflow, we felt that certain shared files deserved a bit more friction. We wanted style guide changes to require unanimous agreement from the team so we decided to try a workflow similar to our engineers:

Step 1: Branch & Commit — A designer makes their proposed change and commits it to a branch on Github

Step 2: Pull Request — When ready, they open a “pull request” into the primary branch

Step 3: Review — The team reviews the pull request and provides feedback

Step 4: Modify — If necessary, the designer makes modifications to their proposal and asks the team to review again.

Step 5: Merge — Once approved, the designer merges the pull request into the primary branch.

Step 6: Everyone Update — A critical last step is for everyone to update their files. The changes are now official and everyone can move forward with the new style guide.

Another benefit of using Github is the Slack integration. Whenever someone makes a pull request, it sends a notification to our #Design slack channel, announcing to the team that there is a proposal change and feedback is required.

Work in Progress

This has been an improvement in our previous workflow, but Github still isn’t perfect for us. There is a learning curve for designers to use Github and it introduces another step in our workflow. There also isn’t a clear way to see a “diff” of the visual changes being made on Github which makes the feedback a bit more difficult — we have to download the file and manually compare with the previous version. We looked at using other services, like Pixelapse, but they didn’t offer the same “pull request” process we wanted.

Obviously there are still ways this workflow could be improved but overall it has been successful at adding accountability around our most important files. It allows for true collaboration across our design team and the benefits will pay off as the team grows in size. When new designers join our team they’ll have the ability to use our style guides and propose changes to them with a healthy review process.

How does your team manage style guides?

We’re always curious to hear how other teams manage their style guides. Does your team use a style guide? What process do you use to make updates and changes?


Follow me on Twitter or follow the Shyp Design publication for more from our design team.