CSS Style Guide

CSS Style Guide

As an application matures the codebase grows... grows... and grows. As a result, the pieces become more tightly coupled and increasingly complex to work on and tune. Our CSS had fallen victim to this before I had joined the company and this was one immediate area I'd identified to tackle.


The first thing I did was some research and aggregate some basic information. We were loading around 100kb of CSS, 2 libraries, and variables were fragmented at best. Additionally, the selector's developers we were writing required specificity that we didn't want.

With these pain points in mind, I then set off exploring the bleeding edge. You see, paying debt down is one thing but having a path with the next 3 years in mind will continue to pay off. It's here that I found PostCSS and CSSNext which laid a strong foundation to build on, over time.

With these tools in place, the last piece of the puzzle was getting around the specificity requirements. CSS modules solve exactly this, at that point, it simply became a process of integration, although in 2017 supporting server-side-rendering is easier said than done.


Now, this is all great, but in the world of front-end development it's often too easy to update things that we might not need to, or simply should not. With this in mind, I collaborated with our lead designer to begin formalizing a style guide. Together we created the 1.0 Style Guide which was abstracted to an NPM package for use across multiple consumer applications.

In addition to formalizing this style guide, I wanted to ensure we learned from our mistakes and put in place automated safeguards. This resulted in adding in StyleLint and tightening things down by limiting the selector specificity, applying auto-prefixer, and enforcing consistency.


A branded, scalable, and customizable base CSS package coming in at around 7kb. This package has since been adapted over the last 3 years and one full re-brand. Unfortunately, this package is not public, however much of the implementation was inspired by my own abstraction @visormatt/style-guide.

CSS Style Guide overhaul and abstraction