From a designer to a developer: about styleguides

March 13, 2014 Shatarupa Nandi

At Labs, we’ve been working with styleguides quite a bit. In fact a few months back Nicole Sullivan and Colin O’Byrne even gave an amazing talk about how they’ve been doing styleguide driven development on CF Console. As a developer, I love styleguide driven development! Inserting clean, modular components of design into the styleguide, not having to write custom CSS and markup to jam an ill-fitting list into an one-off modal and working on CSS that has not turned into black magic by the end of 2 weeks – I am blinded by how awesome styleguides are. But I wondered, what my designer friends think of styleguides. Did they have any unanswered questions for developers about styleguides? So one fine Friday at Whiskey Club when I had a rare designer sighting I capitalised on the opportunity and soon I had a list of questions from a designer to a developer about styleguides. Next, I set about finding developers (both clients and Pivots) who would spare a few minutes to answer my questions. It was not easy – there was a lot of blackmailing and ping pong involved, but I had answers! Here are snippets of my conversations:

  • When is it too soon to start thinking about a live style guide? Wireframes? Complete visual design? Complete understanding of entire system (if this happens…?)
    It makes sense to think about a style guide from the wire framing phase, but implementing one might not make sense until later. There is some overhead involved in creation and maintenance of a style guide, although gems like Hologram reduce this overhead a lot. A good style guide essentially captures small, reusable and modular components of design. Thinking about wireframes to be made up of such components leads to a cleaner and more unified design that can later on be easily implemented in a styleguide.
  • To work on a live style guide, would you rather sit with me for a few hours to move text 3 pixels to the right or left or would you like have me spec out a document with red lines? Or both? Does this vary from developer to developer? Or is there an always preferred method?
    It depends. This varies quite a bit between teams. I’ve been on teams where the designer is a CSS genius and has the bandwidth to pair with developers. In such cases, its always great to have a designer-developer pair working on updating and maintaining the style guide. It gives designers better insight into the effort involved in making changes and gives developers more ownership on design decisions. Pairing with designers on building and naming components in the styleguide similar to how the design for that element was born and took shape in the designer’s mind, helps codify a designer’s train of thought. That being said, more often I am on teams where designers are stretched for time and the best use of their skills is to work on user research, workflow design and wire framing. In such situations, I find that just having a designer hover over my shoulder ready to answer questions while my pair and I work on the style guide from fairly high-fidelity mocks = happiness
  • How often do you want to update the style guide with me? Is this a good weekly chore to add when the backlog is low? Or should it be added to every story? Or does it vary? If it varies how can I figure this out quickly as a designer?
    Its most useful to consider updating the style guide as part of a story. Just like test-driven development dictates that we write a red test before writing any code, I think its important to add/update an element in the style guide before doing so in production code. And just like every test suite needs pruning and maintaining so does the style guide. Whether you do this as part of a weekly chore or every time you reuse/modify a particular component, depends on the team. Either way, the important thing is to make sure that the styleguide does not fall behind.
  • Do you always prefer to have components in a style guide? Or are there times you wish you had just a mockup and it would be faster for you to put it in the style guide? Do you think there’s any overhead to maintaining the style guide?
    Turns out I am not the only developer professing my love for styleguides to all interested and uninterested parties. Everyone that I spoke to agreed that there was an overhead to maintaining a styleguide, but they promptly went on to list ALL of the benefits of a styleguide. Amidst the songs of praise that followed here are a couple that were interesting:
    Styleguides make it easier to rampup new team members. New designers and PMs can reference individual components from the style guide to get an idea of existing design. For example, a new designer may not know the different kinds of lists and what each one represents on an existing site; instead of navigating through the entire site or getting hold of the previous designer he/she can reference the Lists section of the styleguide. New developers can look at the styleguide to see existing CSS classes and markup. As a new developer on the team, when you see a mockup of a crazy modal with a list that’s draggable, sortable, has special hover states and checkboxes you either begin sweating a little or begin showing off your ninja skills. Neither of these outcomes is particularly desirable. Styleguide to the rescue! You realize that such lists are a common feature of this site and are already represented as a component or several components in the style guide. You pick up the markup and CSS from the style guide and thank your lucky stars.
    Styleguides make story acceptance and detection of visual bugs easier. PMs can look at the design of a component in the styleguide when they are unsure about how an element should look like while accepting stories. Similarly, if a PM/designer suspects an UI regression, logging it as a visual bug is as simple as pointing out differences between the styleguide entry for the particular element and what is on the website.

Finally, while this question isn’t directly related to styleguides I think it answers one of the universe’s biggest mysteries: are designers and developers BFFs?

  • I want to work next to you, like pairing style for 40 hours a week to make everything awesome. It’s not really in budget, but it would make me happy. Thoughts? Do you like me too? Can we prance into the sunset?
    Prancing into the sunset with you? Undoubtedly.

About the Author


More Content by Shatarupa Nandi
BOSH CPI Support for CloudStack
BOSH CPI Support for CloudStack

Today’s guest post is from Iwasaki Yudai, research engineer at NTT Laboratory Software Innovation Center an...

How To: Cloud Integration with Federated Cloud Applications
How To: Cloud Integration with Federated Cloud Applications

As the big data and cloud eras merge and bring massive advantages, it also breaks the link between applicat...

Enter curious. Exit smarter.

Register Now