I've finally created UI documentation for my blog with 11ty!
It's been on my todo list for about 6 years but I finally created documentation for the iambacon pattern library.
TL;DR
Not interested in reading the post, just want to see it? Here's the link, enjoy!!
What do you call it?
Is it a style guide, pattern library or a design system? I wasn't too sure myself. Based off the explanations given in this post, I'm calling it a pattern library. My CSS is structured into base styles, utility classes and components, this seems to fit the explanation. At the end of the day you can call it what you want along as everyone in your organisation uses the same terminology.
Given that the naming of things constantly change, I've named the pattern library Styles.
Motivation
There were a few motivations for creating a pattern library.
- These types of systems are a relatively new concept to me. I wanted to better understand how to build them, how to use them and the benefits they bring to development and design. No better way to learn than to build one.
- Better documentation. I built the UI for this site a long time ago. Even though I commented the stylesheet well, coming back to it after so many years it still wasn't good enough. This is the perfect way to improve that.
- Redesign. I want to start making changes to the UI. Having a dedicated space to do that with static templates seems like an easy lightweight approach, rather than having to run the real site locally. Hopefully this will make UI changes much easier to do.
Building the docs
The goal of v1.0, was to document all the existing CSS and to create a template for each page on the site. This would give me a platform to further build upon.
I was heavily influenced by Stacks, the design system for Stack Overflow. The source code for Stacks is on GitHub, which made an excellent reference. You can read more about their design system here.
Repository
I created a new repo to contain the source Sass files and the documentation site. Moving the CSS out of the blog repo has simplified my Kudu deploy script. Previously I was compiling Sass when deploying to Azure. As a result deployment time has reduced. When there is a change to the CSS I simply commit the file to the blog repo and update any HTML if needed. I really like having the two separated.
Framework
When building the docs I didn't want the framework to slow me down or get in the way of progress. My time is better spent on the content of the docs not building it. The framework needed to be low friction, suited to documentation pages, flexible and simple to build and deploy. A static site generator (SSG) seemed like an obvious choice. I went with 11ty. I actually didn't do too much research into which to use. I had seen a fair bit of praise for 11ty and Stacks was also built with it, so I went for that. Again, it was useful to have a working example for reference.
I'm pretty happy with my choice. I was able to get going quickly and I didn't have to learn to much too use it. It's really straightforward.
Build and deploy
I'm using Grunt, mainly because I'm familiar with it and I didn't want to be slowed down learning a new tool. I have 3 Grunt tasks that cover everything I need to do.
default. Compiles Sass and rebuilds the docs. Then watches for any file changes and re-compiles. This is for dev work.
build. Compiles and minifies Sass, then outputs to the
distfolder. I use this to create the CSS file to be used on the blog site.deploy. Builds the docs and creates a ZIP file ready for deployment. I use this when I want to deploy the docs site.
The site is hosted on Azure, and I deploy it to an Azure App Service with a ZIP file. I love the simplicity of this, no set up required, just drag and drop a ZIP file.
Testing
I'm using BackstopJS for visual regression testing. Whenever I update the CSS I run this to check for any unexpected changes. This is such an important tool to have. I now have complete confidence that I understand the effects of any styling changes I make. One example of this was updating normalize.css to the latest version. A couple of <table> resets were removed and effected my table layouts. Backstop picked this up and I was able to fix it. I didn't pick it up when I did a visual scan, this is why you need visual regression testing!
Summary
The goal was to get something functional out which documented all existing styles and components. I'm super happy with how quickly I could build it using a static site generator. I have everything I need so far automated, I have visual regression in place and deployment is straightforward and simple. This means I can concentrate on improving the documentation and working on design changes and themes (hello dark mode). Have a look and see what you think!
Icon made by Freepik from www.flaticon.com