There’s a lot of talk about scaling apps for growth. Scaling server architecture, writing code that will handle millions of requests etc. but I rarely hear about scaling HTML/CSS. By this I don’t mean performance, I mean maintainability. Let’s take a look at this fact: Facebook currently has 6498 color declarations! You don’t get there unless there wasn’t a plan for maintainable markup from the beginning. Since that sounds like a big ol’ mess, I’m dedicated to avoiding that problem at RJ.

The solution, quite simply, is to start forming a set of rules, nomenclature and workflow to form an architecture.

The Goals:

  • Create a worflow for creating and understanding new markup.
  • Give developers who aren’t experts in CSS, a logical and consistent way to markup HTML without having to ask a designer.
  • Impose markup standards within a growing organization.
  • Make it obvious when something strays from being consistent with an organization’s style, and publicly shame us into correcting it. It’s an experiment, and hopefully generates feedback.
  • Save time, and thus, save $ for beer.

The Strategy:

1. Break UI components into objects conceptually. (Buttons, notices, pickers, etc)

2. Address those components in a unified stylesheet: common.scss (We use Sass with Compass, and it’s pretty awesome).

3. Drop common.css into the app and play whack a mole with the style inconsistencies that crop up.

This part ended up being WAY easier than I anticipated. The reason being that there wasn’t much semantic markup. Nearly everything was a div or span with a class on it. I love semantic markup, but this was a case where a lack of it had an unintended positive outcome. This alone deserves its own post. The biggest issue actually ended up being typography since there were so many declarations. We’re still sorting this out.

4. Isolate more objects and add them to common.css until all commonly used objects reside in one place. I like to think of common.css eating the other style sheets.

5. Create a living style guide that outlines what each object looks like, its class structure, and its markup. It’s using the same common.css that’s deployed in our app, so if it works in the style guide, it will work in the app.

Take adding a notice for example. All the developer needs to do is go to the style guide, copy the HTML, add the classes they need, and paste into the app. They can even add classes that don’t exist yet, and have someone like me go back and add the CSS later.

The style guide was inspired by and is based on Kyle Neath’s KSS and more recently takes a play from by SimpleBits. Nomenclature and organization are inspired by Nicole Sullivan’s OOCSS and Jonathan Snook’s SMACSS.

Check it out, and let us know what you think.

Update: If you’ve got an opinion on this, maybe you’d like to work with us! Apply here.

  • Derek Pennycuff

    There’s a video of Nicole giving that talk or one very similar (from Velocity, I think) and if I’m remembering the context of the video properly the ~6,500 color declarations were from before she worked with them on a 6 month project to abstract out their CSS into objects. Since then she’s blogged about the very abstract media object being used all over the place on Facebook and saving hundreds of lines of code. I think those are lessons learned from her time working with Facebook and some of those hundreds of lines of code shaved off included some of those ~6,500 color declarations.

    Personally I feel like we should default to keeping our markup as semantic as reasonably possible documenting the hows and whys of not-so-semantic work-arounds as they crop up. But perfect semantics are a pipe dream and I can’t come up with a solid argument against Doctorow’s Metacrap as it applies to getting dogmatic about semantic markup. We all have to find where we’re comfortable drawing that particular line in the sand.

  • Thomas Davis

    Hey guys, love the initiative and agree with all the sentiments. I’m working on a pure javascript styleguide piecing together the best parts of all the living style guides out there.

    Love the color palette idea!

    p.s. Kalei doesn’t support pre-processors just yet =(

    • Matt Monihan


      Awesome, good work.