Living style guide is an essential tool for designers and developers to create re-usable components. It is a central place to demonstrate base styles, components, and modular patterns. Creating a living style guide might sound easy — it is just a HTML web page, right? Not entirely correct :) In this article I will list some of the challenges and possible solutions at a high level.
Maintenance
It might be surprising that the most outstanding challenge that I observed in many style guides I created is how to manage maintenance cost. Everyone loves style guide, but when it comes to maintaining one, nobody wants to do it. Why? Because it sounds like tedious and extra work :)
Naturally, I believe developers should be responsible for maintaining style guides. However, the developers who created a style guide might not be the same ones who developed components displayed in a style guide. Or simply, the developers forgot to update components in a style guide. A common scenario is like this — a style guide is showing a Button component created several months ago, even after its styles have long been changed.
For all kinds of reasons, there is high chance that components displayed in a style guide don’t reflect their latest state from development. And this single challenge is going to either make or break a style guide. If a style guide is not showing components in their high fidelity, what good use is it for?
Many of the following points I’m going to make are related to this topic — how to lower the maintenance cost.
Demo Page
9 out of 10 cases, if you ask developers to create demo pages in a style guide, the developer will just copy the same code from a component’s test page to the style guide. This might sound sloppy, but actually makes sense to developers. Because the component test page and the style guide demo page both serve a similar purpose — demonstrate a component’s functionality.
So if they are doing similar things, why not combine these two into one — having one single demo for a component that is used as both development sandbox and demonstration in a style guide? Popular frameworks such as Storybook provides developers APIs to create sandboxes for developing components. And the storybook itself resembles a style guide. This combined effort comes with two major advantages:
- When developers are developing a component, they are also creating a style guide demo page at the same time. Hey, no “extra work”!
- The style guide demo will always be up to date. Awesome!
This is huge for reducing development and maintenance cost. A component’s demo file is used for both purposes — development and demonstration. Kill two birds with one stone, you say? Whenever a component is created or updated, its style guide page is automatically created and updated, due to the fact that the component’s test page and style guide demo page are actually the same file.
Auto Discovery
In my project, the style guide and the components are in one single repo. They share sources. However, how a style guide knows which component has demo and where the demo file locates?
These two lines of magical code reveals the secret:
require.context
is a Webpack API which dynamically resolves import paths using regex patterns. In the above code, we are starting from the parent directory (the ..
part), and recursively looking for any file ending with .demo.jsx
, or any index.jsx
file under a demo
directory. The second line imports the resolved paths.
For component developers, there is no need to register component demo page with style guide. As long as the demo pages are named after the pattern, they will be automatically loaded by the style guide. This is convention-over-configuration at its best!
Testing
In the “Demo Page” section, I mentioned that a demo page can be used for both development and demonstration. Actually, the same demo page can also be used for visual test (browser test).
In my project, I set up visual tests to spin up Node Express that serves the style guide pages, and run test scripts (e.g. Mocha and Chai) to automate testing components in browsers. This approach is great for two reasons:
- QA (or developers) are also using the same style guide.
- The style guide itself is frequently tested.
Now, if you hook up the visual test in a Continuous Integration (CI) pipeline, you will have high-confidence checks if anything goes wrong in a style guide.
With this single-demo-multi-usage approach, we achieved something like the following chart:
Multi Use
A style guide is serving 3 areas at the same time — development, design, and test. It plays an essential role in web development cycles. Because of style guide’s multiple usages, it serves a shared platform for different departments to work together. To deliver a successful UX, technology is only able to achieve the 50% of the work; the other 50% depends on the collaboration among people of different roles. A living style guide brings together all involving parties as stakeholders, and speaks a common language understandable to all.
Publishing
Style guides need to be accessible to a wide audience. Its assets should be hosted somewhere. A Continuous Integration (CI) pipeline can be used to automate the publishing process. Having a nightly job to pull component code, generate static assets, and upload them to a central place can be a sound solution. However, what if the change is not in a master branch? What if a developer just wants to use the style guide to demonstrate a bug fix for a component?
If developers follow the GIT workflow — creating Pull Requests (PR) for each feature request or bug fix, then each PR branch should contain a set of changes related only to a feature or bug fix. To demonstrate such changes in a style guide, the guide should allow publishing component changes for a specific PR branch.
I would suggest a living style guide providing developers a command line tool. The tool does the following things:
- Build the code in a branch.
- Bundle the static assets.
- Upload the assets to a central place (e.g., AWS S3 or Github pages).
- Store the assets by branch names. This allows style guide to retain changes relevant to a specific branch.
Bundlers such as Webpack can handle point 1 and 2. For AWS S3, you can use AWS CLI to upload assets to a specific directory; for Github, the gh-pages node module can be used to publish files to Github pages.
Developers now are able to publish their component work to a style guide on demand. This can be very handy for UI Acceptance Test — a developer can send designers an URL to the style guide which has the requested changes, and the designer will be able to play with the updated component in action. No more screenshot or video recording.
Versioning
Components can go through rapid development cycles. For the same component, its look and feel might change due to feature requests or bug fixes. How will a style guide evolve along with components?
In my project, I set CI pipeline to build, bundle, and publish style guide assets for each release tag. Whenever the CI detects a GIT commit tagged with a release version, e.g. v3.4.0 or v4.0.0-alpha.1, the CI will run the following steps:
- Build the code in a branch.
- Bundle the static assets.
- Upload the assets to a central place (e.g., AWS S3 or Github pages).
- Store the assets by tag names.
As you can already tell, these 4 steps are almost identical to the previous steps mentioned in the “Publishing” section, except for the 4th point where we now store the assets using tag names. All these steps allow style guide to track different versions.
The follow Jenkinsfile snippet checks if a commit is tagged with a release version:
Conclusion
A living style guide is not just a HTML page. It has a whole set of tools behind it to automate the development and maintenance process. It is a cross-department effort to ensure consistent look and feel across products.
Many tools can be used to reduce the friction from different roles involving in creating a living style guide. Tools like Storybook is able to re-use a single demo for multiple purposes — design, development, and test. For complicate projects, you can definitely roll your own storybook-like framework with aforementioned techniques. Actually, in my company, we use Storybook as a reference but create our own framework that gives us full control of the styles and build setup.
In our experience, a low-cost and highly automated style guide is the crucial tool to ensure high-quality components. If you are developing components, take some time to adopt a living style guide strategy. You won’t regret it!