Clean Coder | Aviture | Culture
From the trenches, Our experiences with Style Guide Driven Development
Style Guide Driven Development (SGDD) is a technique of developing your UI components in a living “Style Guide.” There is no one set definition but the basic idea is that you develop a separate page or pages outside your application that use the same CSS and HTML that your application uses. There is an excellent introduction to SGDD and its benefits at Smashing Magazine and we encourage you to check it out! This post will be about our experiences working with this technique, which suggest that on a green-field project, it is extremely difficult to know enough about your application to fully embrace SGDD out of the gate. We found that waiting for the UI patterns to emerge from your application and then creating a style guide was a better approach. Key to this recommendation is to develop and build all your UI components (style guide or not) with discipline, using known best practices.
Setting the scene
We began work on a new project for a client who wanted to build an extendable platform that they could customize for their users without doing complete re-writes. We felt this was a perfect fit for SGDD because the implementers of the custom solutions would benefit from having an authoritative source of reusable UI components they could turn to when they needed to build a new page in the application (long after our part had ended). We therefore committed to doing SGDD. Any component we thought could be reusable at some point would not go into the app as plain old HTML/CSS. We would be disciplined and make sure we do it in the style guide first.
Trouble in paradise
Things started out, as they always do, nice and fast. We had our style guide scaffolding built in no time, and configured our project to pull its SCSS directly (using Webpack). We took our mockups and wireframes and deconstructed UI components into our style guide. We then reconstructed those components into the app with the CSS and HTML from the style guide! Great success! At first we kept our components small. We kept it to things like buttons, panels, and the like.
But then… things started to get more difficult. The first sign of this was trying to decide what went into the style guide and what didn’t. How much of our layout CSS should go into the style guide? Was this particular piece of UI a stand-alone component, or a one-off? We had a concept of a ‘card’ component, but in our guide, how much of the content should go in the UI guide and how much was just customization?
As our designer built more pages, this problem got worse, and we encountered new ones. As we learned more about the application, we realized the the initial set of components wouldn’t do the job, so newer pages often weren’t able to reuse the existing components in the style guide, but at the same time, the existing components were close enough that it was uncomfortable. The designs often didn’t share the same UI components we built at first. This wasn’t the fault of the designer. It would have been a mistake to force ourselves into reusing components that didn’t meet the design criteria that was appropriate. But as developers trying to do SGDD, we realized that in the end, we had no idea what would end up becoming an official reusable component and what would be a one-off customization for a particular view in the application. The root of the problem was that we just didn’t know enough about the application to create a style guide for it
Stop, take stock
We decided to put SGDD on hold. We went back to just implementing the pages our designer provided to us without worrying about whether it was a UI component and where in the style guide it should go. Development continued as before like it does on all our other projects, and it wasn’t bad. We didn’t throw away good practices such as SUIT for our CSS, we just didn’t make it a style guide component. As we continued work, though, we began to notice more and more UI patterns appear throughout the app. This was what we were missing before.
About that style guide…
We continued this way for several months, but all projects end and ours was no exception. As our end was approaching, we talked with our customer about re-dedicating ourselves to the style guide. Our customer was on board, so we took another look at where we stood.
At this point, we had built a large portion of the application and those patterns we had begun seeing as we worked as normal had crystallized nicely. Our designer did a review of the application and found items that were similar but slightly different between different pages. She standardized these and let us know. We then went back to the style guide, and created a UI component for those items, then replaced the custom code in our application with the style guide UI component.
Great success
The result was not only a crisper and more consistent UI experience, but also a style guide full of components that other developers could use. For example: we realized we had 3 different type of panels for showing more information. They were all very similar but they simplified very nicely into a single component with some variations.
The feedback from our customer was very positive. They really liked the style guide and could see the benefits it will provide going forward in terms of maintaining consistency for their application. Without it, as with all other apps, one-off changes and ‘tweaks’ would have slowly made the application look less cohesive and more difficult to change.
As a deliverable product, it was exactly what our customer was hoping for and expected for their platform.
Their developers also liked having a ready-made set of components to go to when building out other functionality.
Conclusion:
If you’re looking to start up SGDD on your project, I’d argue that at least one of these criteria must be met before jumping in with both feet.
- The application already exists in some form, even if you’re doing a re-write / re-skin.
- You have a really solid idea of what the application is going to do and what it will look like.
- Application development has been ongoing and the project is already up and running.
These are intentionally mushy, because as usual it will depend on your circumstances.
We had to wait for #3 to progress to a certain point before we felt comfortable going back to SGDD. Perhaps a better ultimate solution is to get a super basic style guide set up. Just put your color variables, maybe some layout pieces in, and then just wait until things solidify a little more before jumping into deciding which components become official style guide components.
We often say in Agile that you can’t know what the final product will look like, and we mean the behaviors, interactions, layout, etc… But the literal interpretation is also correct. Even with the amazing designers we have here at @aviture, you just can’t know how the end product will look on the screen. That’s why you deliver early, get feedback and change often.
SGDD is a great methodology, but I’d argue that it requires a certain level of application maturity to provide real benefits. Spend some time standing up your application, never abandon doing your CSS well, but wait until patterns emerge before pulling them out into a style guide. After your guide is stood up and is a repository of your patterns, it becomes much easier to use it as a guide, much faster to develop with it, and produces better results in your final product.
