Expert Perspectives

Let’s Talk: Live Style Guides

We sit down with three Boston product experts to get the inside story about what makes their live style guides so effective.

We focused our last article on Live Style Guides, and how to make them both useful and relevant over the long term. To explore other perspectives on the topic, we gathered three Boston-area product experts to talk about how they build and maintain live style guides that support their products.

Our guests for this Let's Talk discussion were:

Josh Briley
Principal Design Engineer at Berkshire Hathaway Specialty Insurance

Vanessa DeCollibus
Director of Product at MIT Technology Review

James Young
Director of User Experience at SS&C Technologies Boston

How do you define this resource? In other words, what do you call it, and whats in it?

Two seemingly simple questions that people encounter when they build a resource of this kind are what to name it and how to define its scope. As it turns out, the former is more a lot more important than we might think—and can have unintended consequences on the latter.

JOSH BRILEY: When we first set out to build this thing, it was intended to be a tool for anyone doing front-end development work.  The intent was for it to function as a repository of approved markup for common design patterns. At the time, “style guide” seemed to be the all-encompassing term for such a tool.

VANESSA DECOLLIBUS: The idea for ours is that designers will be able to download Sketch files in addition to viewing code examples. We thought about calling it a live style guide. But a style guide is something specific for external partners at our company—something we share externally that relate to branding and copy voice. And that is not what this is. So we’ve been toying with it calling it a storybook but that’s also not super intuitive for people not on the product team. So we’re still kind of trying to figure that out. Right now we call it our style guide or storybook, interchangeably.

JAMES YOUNG:  The audience for our resource is a bunch of globally distributed sprint teams within a big company that moves at a fast pace. So we decided to follow how the developers that were leading the project were comfortable referring to it—as a UI component library.

JOSH: What we’ve learned is I have to define this thing based on the context of the person that I’m communicating with. A “style guide” to some folks means “branding assets,” to others it may suggest a pattern library of atomic design elements, and then to others could represent an asset management tool.  Over time, we’ve expanded the style guide to include a lot more of those elements that different staff members and vendors expect to see.

JAMES:  We’re using it as the source of truth. We’re saying that the source of truth is no longer drawings of screens or components in Sketch, it’s the implemented UI that’s on our staging environment. In the past, our guidelines might have just been visuals or only a reference, but we still had to re-create the work. Now it’s copy and paste, and we’ve got a component.  

What is your elevator pitch for why you need a live style guide?

Many of us feel instinctively that we should have a live style guide (we’ll continue calling it that for the sake of simplicity), but it isn’t always easy to articulate just why we need it, or why it is worth the sometimes significant investment of time and effort. We asked our round table to make the case for the resource.

VANESSA: We’re doing a complete redesign, so we’re taking this opportunity to consolidate and streamline and the style guide is going to codify that work so we can keep everything standardized this time. It’s gaining us time and efficiency, because we can lean on the style guide to start informing any new pages or components that we need.

JAMES: For us, the benefit is trying to get our sprint teams more closely aligned. We’re a big company, so not all of them are in the same location. People can just copy a code snippet and over time that will result in more baseline consistency. It’s also an entity with a process in place that can help us move toward consensus on where we want to go with certain UI elements.  

JOSH:  A style guide brings significant value to our digital team. Not only does it support consistency in our code base, but it also works as a teaching tool for developers of varying experience. There is a productivity boost in development because the style guide helps limit the number of assumptions required to get a feature to the screen, or other devices. It also gives our QA team a source of truth when doing acceptance testing.

JAMES: In the past we were like, “Well if we don’t see a design for it, we’ll just build it and move on.” The proliferation of inconsistencies could grow and grow. Now the style guide provides a clear structure. Work is tracked and considered. We are saving time and gaining efficiency, because we can lean on the style guide to start informing any new pages or components that we need.

VANESSA: I think that as we hire new UX designers it will help them get up to speed faster. As new people come on board, new developers as well, I think it’ll help just make sure everything stays really consistent. In our previous site design, we ended up having like 40 headline types and a million buttons.  

JOSH:  It makes it a lot easier for someone to come in and help out on front-end development. There’s also the benefit of faster time to market. When we go to build something we don’t have to create it from scratch every time. It’s already there.

Which comes first, the product or the live style guide?

Should you build a style guide first and use it to create your product, should you build the product and extract a style guide, or should they be built in parallel? Our panel agreed that a tandem approach might be best. But whatever you do, they warned, the live style guide should be treated like a product.

JAMES:  We’re running the product development in parallel with creating the library. I don’t think there’s a right or wrong way to do these things. We took an approach that was appropriate to the way that our teams are configured.

JOSH:  You know, there are so many different ways to go about it. Certain design specifications would be nice to have up front when starting a new product, but it’s a big ask, to build out a style guide before a product. You may not know exactly what the product is yet. You will likely pivot. For us, the style guide changes as the product changes. There are also things we discover from the style guide that may influence the direction of the product itself. So I think the process of creating a product and a style guide really happens simultaneously.  

VANESSA: Our designer has been breaking the new design for our site into components and the grid system that the templates use. As they’re coding it they’re building the style guide in tandem. We’re creating a library of components. Our site has a content feed that is made up of teasers that click through to full articles or expand in place. So as an example, all of the different iterations of that are included in the style guide. The people on our team who are coding the specific elements will be responsible for keeping those stories updated.  

JAMES :  We literally treat it as a product. It started off because we didn’t have any preconceived notions. We started off with a small team dedicated pretty much 100 percent to figuring this out. Our goal was to just run it as its own product to support the teams. We did get a bit of a head start, but not a long head start, to take care of some of the basic atomic features of it—you know the “atoms and molecules.” We got those things that you can easily anticipate people needing in place, and we are working from there in parallel with the product.

Can you share an insight you gained in creating your live style guide that surprised you?

The path to a great live style guide doesn’t always run straight.  We asked our round table what happened along the way that was challenging or surprising.

VANESSA: Building a guide like this takes work. I don’t know that we could have done this if we weren’t doing a site redesign. I think it would be hard to retroactively put something like this in place. Not impossible—but I think you would need to take a step back and probably consolidate and cut things from the live site. As people are moving forward on their day-to-day work it’s hard to do that, so for us it was probably a recognition that doing this during a redesign made it a lot more easy and intuitive than retrofitting or starting from scratch.

JAMES:  I think what may have surprised us a little were the places where there was a disconnect between the theoretical and the application. The UI library could have some stuff in it that works in theory but then we’ll find in practice it needs to be fixed. Also really understanding that this is a living guide, that the library is not a strict, sacred guideline. Just because something is in there doesn’t mean it’s perfect. But our hypothesis that we’re still testing out is that when we need to refactor or pivot direction on certain UI controls, it will be easier to roll those changes out across a bunch of different teams. I have a feeling that the pace of development is going to pick up to the point where we don’t want to be a bottleneck. If other teams need to develop a new component, we’ll pull it into the library. We might be refactoring it in the process then communicating that back out. But adding it into the library assures that all those refinements are a part of future releases, and that’s the real goal for us.

JOSH: One challenge we ran into was code bloat. If you use Bootstrap or Foundation or any other kind framework, you probably deal with the same issues. Our style guide contains everything and the kitchen sink. So we’ve become very focused on creating a build workflow that strips out any of the code that a project doesn’t need.

What advice would you give a product owner that doesn’t yet have a live style guide?

Every organization is different, but what wisdom would our three panelists pass on to someone who is just starting out on this journey? Flexibility, simplicity and pragmatism come to the top of the list.

JOSH: Don’t just jump in head first. Familiarize yourself with what this thing can do for your organization and for your team. Also, different businesses have different needs. Look at a Fortune 500 company versus a startup where everybody does a thousand jobs. I think individual roles within companies will probably dictate how much time and effort can be spent on something like this.

JAMES: Don’t just jump in head first. Familiarize yourself with what this tool can do for your organization and your team. Different businesses have different needs. And some businesses just don’t need a style guide to get a product out the door.

VANESSA: For me, as a product manager, it’s been a challenge getting up to speed in what having a live style guide means to our process overall. It makes sense, and it’s something the team’s really excited about, but it’s not something that we all have had a lot of experience with. We are learning as we go. So I think my biggest piece of advice to anyone starting this journey with apprehension is don’t be afraid to ask questions.

JOSH: Sometimes it’s just about getting stuff out to market and little inconsistencies aren’t a big deal. But if you’re seeing a whole bunch of inconsistency in your design or you are working with outside vendors, it is worth looking into.

JAMES:  You’re not just adopting something to check a box but you’re actually building a system that works day to day for your team. You can capture what you’ve done in the past, and try to forecast the types of things you might need in the future. But expect it always to lag behind the innovations your team is making, and make it flexible enough to capture those. It’s a big job, so allocate support to develop it and maintain it. Also, try to do a good job of communicating what this resource can and can’t do. It’s not a magic UI machine. You’re still going to have to go through the really hard work of translating it into an actual product.

How great are these three? Our thanks to James, Vanessa, and Josh for being part of this interesting discussion and sharing their experiences and advice with us!

And, if you’re ready to roll up your sleeves and get started on your own live style guide, be sure check out our article How to Create a Live Style Guide That’s Not DOA.