Building AVR, Part 4: CSS Architecture

Once AIM was built, we needed a product to display the inventory that had been managed. The AutoConX Vertical (Responsive), or AVR, is a white-label product that allows publishers (newspaper or magazine) list inventory from sellers in their area. It’s a digital classified system that offers a lot of customization and flexibility.

This project was trickier than AIM because AIM was a brand new product. AVR, however, had to be a modern and responsive site that met all the publishers’ expectations from the legacy product. Publishers wouldn’t switch unless they saw real value in the new system. We had to build a product that we would put our own products on.

This is the story of the CSS architecture for AVR.

Note! If you’ve read my post about AIM CSS Architecture, this will mostly be a repeat. Skip to the difference.

For most of the CSS work I do, I serve as web designer and front-end developer. However,
given the scale of this project (and the number of stakeholders behind it), a dedicated web designer began the process with mockups. I worked closely with our web designer to produce dozens of Photoshop mockups for review and revision that would nicely translate into HTML and CSS. Mobile and desktop versions were produced of nearly every screen in the web site so that the design language was consistent, visible and mobile-focused.

What CSS methodology do you use? AVR builds on AIM’s ABC (AutoConX Block CSS) methodology, so HTML is styled as blocks containing elements and modifiers. I take my CSS seriously. As a result, I use Stylelint to ensure that all CSS is written in the same manner. This methodology makes creating a living Style Guide very easy, because all of the styling is already written in a way that is very isolating and encapsulated.

What preprocessing do you use? We preprocess using cssnext, a bundle of PostCSS plugins that provides future-facing CSS for developers. The CSS you write comes from bleeding-edge specs (custom properties, media query ranges, color()), and it gets processed into styling that browsers understand today.

I fell in love with the idea for a couple reasons. First, I can CSS using some of the killer features that other preprocessors boast. Second, the syntax is familiar, because it’s still CSS. No one on the team has to learn a new language to write or read AIM styles. In fact, developers don’t have to know about cssnext at all. They can still write CSS as they always have. It’s even possible that one day the processed file will look identical to the source file.

How do you handle regressions? Just as it was important to me to test the CFML in the application, it was also important to test the styling. I had gone through the work of creating parameterized views, so it was easy to stitch them into a living Style Guide. The guide showed me at a glance all the different design patterns in use. When planning a new feature, I could consult the guide to determine what existing elements could be utilized. This, on its own, was extremely helpful.

Using PhantomCSS, I developed a task in Gulp that would ensure visual regressions were checked and discrepancies were reported. Every UI update or addition would very clearly illustrate any side effects. Regressions were rare due to using shallow specificity, but this task greatly increased my confidence with each new deployment. It also made refactoring HTML and CSS nearly bullet-proof. By tying this task into my precommit and prepush hooks, I further protected myself against deploying code that broke existing UI. This has become my gold standard for CSS development going forward.

What special considerations did you have to keep in mind? AVR has the unique requirement of being powered and customized by a content management system. We give our publishers as much configuration and customization as possible, from page titles to the homepage layout to the stylesheet.

When a customer starts adding rules to their custom stylesheet, we create a physical file called “custom.css.” Then we link this stylesheet after our core styles. This gives custom styles a slight precedence in the cascade since custom rules come after our own. We had already adopted a methodology that kept the specificity of each style rule very low. This was very much for our own sanity, but it had the side effect of making it easy for even novice CSS writers to customize their site without needing complex rules. Our dual stylesheet approach also keeps the custom.css file size down to the fewest necessary changes.

To help customers with their styling, we produced a wiki page dedicated to explaining the available customizations. To simplify the process for customers, I added some special classes aimed at making the styling process even easier. By adding classes like `color--bold` and `color--accent`, I could give our customers a very short rule that would affect UI elements throughout the site, even if they were part of different blocks. In fewer than 25 rules, a customer can give their site an entirely unique coat of paint and be on to bigger and better things.