Creating a Bocoup style guide

In between client work and working with my design colleagues on an internal project, I’ve been busy creating a Bocoup style guide. One of the fantastic things about Bocoup is that we make a lot of the tools we use to track our work, schedules, and skills—but we didn’t have an easy way for anyone who was making a tool to theme it in something that looked like Bocoup. What often happened is Bocoupers cobbled together styles in the best way possible from the sources available, scouring our repos for what could be reusable.

Luckily, the need to have everything in one place for the sake of consistent branding just happens to dovetail with one of the things I love to do: creating style guides. I like creating order of chaos, which usually happens with a style guide. I also love how the act of doing so helps clarify so many different pieces of the puzzle when it comes to how we want the things we make to look and feel, whether they be for ourselves or to share with the world. I’ve spent time over the past few weeks working on the beginnings of a style guide to house all that information in one place, where any Bocouper can access it.

The process of creating a style guide can vary slightly from project to project and brand to brand, but the steps themselves are usually the same. And it’s always fun to dive in and spelunk my way through a code base that I know nothing about.

One of the first iterations of our guide, the left navigation has been changing as we figure out exactly what works for us.

Tool or not?

The first decision I needed to make was if I was going to use a tool to automate or if I was just going to hand-roll the guide. I’ll be honest: I’ve hand-rolled a lot of guides in my time, and I don’t mind it. Hand-rolling a guide can be beneficial as it is exactly what you want and how you want it, you aren’t using someone else’s ideas of how a guide should be. There’s a case to be made that maintenance can be more of an issue, but in my experience maintenance is an issue no matter what you do to build your guide; very few maintain themselves.

But for this project, I wanted some automation and wanted to be able to really make it modular, since the future use of what I was building could be used in any number of ways. For example, people may just be grabbing the styles for certain elements such as <ul>, type, or a grid that is mobile first to use in their projects. In addition, we knew that template starting points would be helpful for us as well, so I wanted flexibility with the ability to break things up into their smallest parts if possible as well as showing an entire template design. I headed over to styleguides.io to take a look through the absolutely huge list of possible tools.

I settled on Fabricator, because it’s not only easy to get up and running, but we can define our own taxonomy and customize it. I love the notes feature, so we can talk about usage of things to help direct the right way to use a component. And it was great: within minutes I had an install up and running and not long after that I had put the CSS from Bocoup.com into the tool, added some components and Fabricator put it all together. In essence we had a starting point along with a local server running and detecting changes; Fabricator does the work of taking all the templates and creating the static site, which worked perfectly for our situation.

Audit

Here’s where the real work came in: I audited the existing CSS used on Bocoup.com to create components for future use. I read through the CSS, and created components, but this was only the beginning point and by no means did I anticipate our web site having all the styles for everything we may want to be a part of our guide, but I had to start somewhere.

I slowly started getting things into components that were class-based and not reliant on anything else. Since we use WordPress for our website, the CSS relies a bit on its structure, but for our guide, I wanted it to be neutral and easy to reuse.

Then came the questions. I’m new to Bocoup, I’m new to the brand itself, so I started collating questions as issues in the repo where I was working. Looking for the design team, along with the company as a whole, to help me think through what we want our style guide to be.

Much of the work for this guide was a collaboration. This is where design and development really comes together, in my experience. We talked at length about the organization of the guide. We made decisions on how to differentiate between all the different types of work we do and how styles and components will feed into that. And we determined where we needed to fill in the gaps in our visual design language.

Make it yours

While tools are great and we had a great starting point, the style guide you create needs to work well for your team—and this guide for Bocoup was no different. If I build something that no one looks at or uses in the future, it’s a failure.

So the process I’ve gone through to get us to a certain point of documentation and inventory is only going to go so far. The next step is talking with my fellow Bocoupers, gathering user stories and use cases, so that I can get the guide to a point that it’s easy to use for the team.

An example of user stories provided by fellow Bocoupers.

We often think of user stories when we do client work or start a new project and that was no different for this style guide. I created an issue and asked my teammates to respond and help me fill in use cases. I got some great responses, and it helped the design team and I think about how to make sure we were meeting those needs.

At Bocoup we create branded internal tools, one-off pages and documentation sites for open source projects, and stand alone sites like cssconf.com (in addition to all of our work for clients—which is outside the scope of this project). While the designs of those sites will all vary in many ways, there’s usually a common thread running through each of them—some callback to the overarching Bocoup brand, typified by Bocoup.com. And the goal for the style guide is to make it easier, to have a starting point for any of the above projects. So our style guide needs to have broad applications and a variety of styles that can be used when needed.

One thing we decided to do that I’ve never done in a style guide is have some basic pages laid out and ready to go, almost like a wireframe in code. This gives a great starting point to customize and use it for a new project. We’re also going to include links to Sketch files in our Dropbox so designers can go right from the guide to grabbing files and start designs from there. Along with both of those things, a universal footer for when we want to show that Bocoup is the originator of things, even if the project is somewhat separate.

A reusable template done in code, ready for use in another project.

Naming things is hard

All the use cases I’ve outlined above are where we got down to figuring out a taxonomy for how we would talk about the various pieces of this puzzle. Since we want our guide to be useful for a wide variety of projects, we needed to be able to clearly name them and talk about them as a team.

A screenshot of some of our process thinking through naming and organization of the guide.

Naming things is one of the most difficult aspects of a guide. But here’s the thing I’ve come to believe: the names don’t matter as much as we might think. What matters is that the team you are working on knows what you are talking about when you use the words you chose.

We made our choices for our guide based on what the team felt was clearest and moving forward we will have it documented. Hopefully a new team member can easily grasp what we mean as well.

Just the beginning

This is just the beginning of this style guide. Since we look at this as a living thing, we’ll continue to iterate on it. We’ve even stubbed out spaces for components that we know we need but haven’t got styles yet for, such as a form checkbox, or buttons appropriate for an internal application. And we are adding issues to continue on and think more deeply about certain aspects.

I still have a lot of work to do to ensure that both the HTML and the CSS works well for everyone and they are able to easily grab what they need without wading through a lot of files. This guide is very much a buffet, people will come and take what they need to use in their projects, so things need to stay modular and easy to use.

Also now that the guide is started, I’m eagerly awaiting for someone on the team who hasn’t been as involved in it to use it. Feedback in this way is the true test and it will help us evolve the guide into being something that works for the entire team. So we’ll continue to usability test with our team members, think about the guide as a design team to see how we can improve it, and work on it as we have time.