CSS Rearchitecture

Less, CSS architecture, refactoring
When I joined StudyBlue, all the CSS for the logged in experience was contained in a single file, called sb.less. After a few initial months of learning the code and self teaching myself CSS, it became clear to me that a single file for all of the company's CSS was not sustainable, both in terms of the development process and the performance of the site. At its peak, our primary css file was 19450+ lines long. So I aimed to rearchitect the CSS to separate, more manageable files.

I began the process by reading some books on the best practices for CSS architecture. With this basic understanding, I began the transformation by placing some universal styles, such as color variables, in separate files and then adding them to the original sb.less file with an @import.

Gradually over time, I then began placing styling for specific pages in separate files and again importing them into sb.less. While moving this code, I also often took advantage of the opportunity to either partially or fully refactor the code. I frequently found less-than-ideal CSS practices and unused code that could be replaced or removed. For example, for one particular modal I started the cleanup by moving all the original code to a separate file and bringing it in to the original Less file with an @import.

If possible, I then generally try to immediately get that commit out in release to minimize the risk of any merge conflicts with other developers. After the styling is in a separate file, I revisit the code and look for opportunities to use global styles by adding styleguide classes and for opportunities to minimize styling. By doing this on the styling above, I was able to reduce the styling down to the following:

Through this process though, I've had to make sure none of the existing functionality was broken by my changes. Since CSS classes can be pervasive throughout a code, this required a good amount of code digging.

I was concerned thoughout this process that the @import's I used could possibly create bigger performance issues. After discussing this issue with our frontend leads, we agreed it was worth the potential performance risk to allow for more code organization. With the code cleanly organized, we could later move towards possibly only serving up the CSS necessary for a given page, which would dramatically improve perfomance.

At this point, I've been able to pair down our primary less file from 19,450+ lines to 5,150- lines. I've also instituted the following changes to the file organization to make files easier to find:


While this work is still in process, I have learned to date that an architecture of this kind requires a good amount of communication, planning, and patience. While I would love to simply rearchitect the work in one fell swoop, that tactic would be likely to cause too many conflict issues for my teammates. Many of them are working on projects that rely on the existing code so changes must be discussed with them to prevent chaos. In addition, implementing the rearchitecture incrementally allows QA to limit the testing to one specific area rather than the entire app. Larger projects such as this require communication and perserverance.