Over the last several projects, we have chosen to commit to the construction and maintenance of a live style guide as part of the development process. However, the reasons in each case have been varied, and I’d like to give a quick rundown of these cases with some benefits and pitfalls of each.
My primary reasons to build an live style guide are when:
-
On a new codebase,
-
Bringing an existing frontend codebase under control, and
-
Implementing a “phase II” design.
Stipulations
-
It must be a web-based product. I am unaware of any successful process for an live style guide on iOS, Android or any technology not using CSS and HTML.
-
The live style guide must exist on a basic page that the developers and designers can affect quickly with HTML (preferring HAML, SLIM, etc), CSS (preferring SASS or LESS) and inline Javascript.
Universal Goals of a Live Style Guide
This is a good point to describe the goals for a live style guide. In all situations, my primary goals for using are:
-
to showcase and create best practices for the team to use going forward,
-
to properly factor the frontend codebase so future changes are straightforward and decoupled from each other, and
-
to enable all members of the team to pair on it’s creation, maintenance and evolution.
Universal Benefits of a Live Style Guide
There are some general benefits that the live style guide brings, regardless of the context:
-
It creates a culture that appropriately estimates the scope of new widgets: I personally believe that CSS work is habitually under-estimated by agile teams and designers. New widgets, variance in widgets, conditional behavior, conditional display, and new layouts all increase the entropy of your frontend by a factor that is exacerbated over time. In the same way that adding a feature increases your codebase and maintenance costs, so do new design elements.
-
Eliminate handoffs by pairing with a visual designer: If the team has a visual human resource, pair with him or her as you build. If you don’t have a visual resource, bring in the product owner as you near completion of each bit. Most visual designers nowadays are interested and skilled in frontend development. Anecdotally, every designer I have paired with quickly recognized the advantage of repetition and versatility of widget design and then promptly eliminated unnecessary visual variance from their existing and future designs.
- Spread best practices by pairing with engineering: It’s amazing how a little CSS best practices, mixed with pairing and with a dash of SASS-magic can transform all team members into competent and exceptional frontend developers. After all, agile engineering is no stranger to pairing. Arrange the pair assignments so the two of you hammer out a complex CSS design. They will appreciate it!
Situation 1: A New Codebase
Honestly, designing in-browser live style guide on a new codebase is one of the most exhilarating experiences us frontend geeks can find. The benefits in this context are:
New Codebase Benefits
-
Agile live style guide construction: Only put what you need for the upcoming iteration(s) into the LSG. If you only need H1 and H2, do not bother with H3, H4 and H5. If you only need one button, design that button (and make it POP!). You need a fancy table? Focus on that. Odds are that what you NEED ASAP is a manageable workload.
-
Make live style guide stories unpointed Chores: Resist acceptance process for the style guide. The consumer user does not see the live style guide. It will be accepted anyway down the line. Why subject it to double jeopardy Any issue that might hold up the acceptance of the Feature when implemented, can be 90% handled during the live style guide phase by bringing over the designer or product owner and pointing at it on the screen.
New Codebase Pitfalls
-
Engineering catches up: This is in the pitfalls section only because you have to watch out for it and react appropriately. You can not create a bottleneck here. You know they caught up when they are picking Features off the backlog that have a corresponding story to style in the live style guide. This is time to delete your Chore for the style-only. By this time, you should have many elements in place, most notably a file include structure, a framework choice and at least one layout example. Do the style guide in the layout of the app. This way, you set the best practices for grid usage. Your goal is to enable the team so you can roll off, not create a bottleneck that requires you to create every line of CSS.
Situation 2: Bring an existing codebase under control
To be continued…
