back to top

CSS at BuzzFeed

I have always loved learning how people work. So let's see how we take care of CSS at BuzzFeed.

Posted on

I have always been really interested in learning how people worked. (I recommend Lifehacker's "How I Work" series or Slate's How Does X Work podcast.) So when Mark Otto first wrote about GitHub's CSS, followed by Ian Feather's description of Lonely Planet's CSS, Chris Coyer's of CodePen's CSS, and many others, it was Christmas before Christmas.

So it's my turn to explain how we take care of our CSS at BuzzFeed.

Quick facts

* This is still a work in progress. We are in the middle of a code refactoring operation.

* Not everything that's described below is in use now. It's more a "this is where we are heading" type of post.

* We use SCSS. (Indented syntax. Two spaces. Haters gonna hate.)

* We have currently over 100 individual source stylesheets.

* The compiled CSS is split into two separate stylesheets, front.css and buzz.css (and then once again based on the platform you are using).

* The average weight of these two files is around 15kb (gzipped).

* We have currently 9,000+ selectors — that's pre-refactoring. Once done, we're aiming at 5,000 selectors.

* We use BEM for our classes. Our very own version of SMACSS for the file structure.

* We recently installed rem for typography. The rest uses pixels.


I fell in love with Sass (and later SCSS) as soon as I was introduced to it almost four years ago. It was then very natural to pick SCSS over other preprocessors when we decided to refactor CSS. An easy choice too when you see the community out there building fantastic stuff. (I highly recommend following Hugo Giraudel, Sass Wizard!)

We rely on SCSS features a lot. We have a large collection of mixins and functions, and use variables often. We break down elements in the smallest chunk of code possible. This also allows us to easily replicate the way the HTML partials are structured. It also helps us debug with source maps enabled.

We don't use any external libraries, or dependencies, and I don't think this will change in the near future. So far, we have managed to build our own set of tools without the need for Autoprefixer, Compass, or others.



Our CSS has quite a bit of coding debt. The company has grown so fast over the past couple of years that there's *a lot* of code in *a lot* of CSS files. Of course, it doesn't help that BuzzFeed works like a lab where employees (engineers and writers alike) are encouraged to constantly experiment.

The need to have a set of defined rules quickly became evident. That's why we started to build a team dedicated to sorting stuff out, building a style guide, killing our darlings, and making our code a piece of heaven.


Our file structure is loosely inspired by SMACSS.

As rules regarding components, we tend to follow these ones:

* Our architecture is based on BEM. Combined with OOCSS, it has helped us build reusable components. If you're interested, Harry Robert's is a pretty awesome place to start.

* We recently switched to normalize.css. The switch from Eric Meyer's reset was not easy, mainly because on top of our SCSS file we wrote * { box-sizing: border-box}. (There's now a better way to use border-box.)

* Each component is broken down and has its own SCSS file.

* No IDs in the CSS.

* Don't use classes used in the CSS as JS targets. Add classes with the js- prefix (that should never be styled).

* Avoid unnecessary nesting.

* We currently use two mixins to build elements and modifiers of blocks. But when a block gets a little complex, it's very hard to follow what does what. So I would advise against adding them to your toolset.


Currently linting is done manually during code reviews. We maintain a set of rules that we try to use and enforce. We currently don't lint BuzzFeed's SCSS. We have a SCSS-Lint file ready though. 😐



As mentioned above, we serve two different files:

* front.css for the homepage

* buzz.css for post pages

This makes sense for us since the majority of our traffic goes directly to our post pages. These files are split between large screens and smaller screens: front.{desktop|mobile}.css and buzz{desktop|mobile}.css.


We comment code a lot.

When we were a small group of developers, we didn't comment nearly as often. But we now have over 30 front-end developers, spread in different offices and countries, who interact with the front-end code on a daily basis. Commenting was not only useful, it was necessary.

To display this documentation, we tried many different options (mostly Style Guide Generators like KSS or Hologram). But repeating the code felt so heavy and slow. We quickly realized that that if each one of us skipped on commenting here and there, the doc would be quickly out-of-date, which would limit use. Therefore, not commenting made our code out-of-date even quicker. See where I'm going?

So following Lonely Planet's fantastic approach and Rizzo, we built our own pattern library framework: WAFFLE (Web Application Framework For Livin' Easy). It became our go-to place for all front-end matters. It works as a component library, a documentation wiki, etc. It's still a very young project, but everybody is super enthusiastic about it. I'll talk more about Waffle in a future post!

The future

BuzzFeed's CSS is far from perfect. But a lot has evolved in the past few months and it's really encouraging. In the future, we'll keep strengthening our workflow, keep narrowing the gap between product and developers, focusing on performance. We really want to lower the barrier to entry for new developers here and create a common language for all stakeholders, add linting and building tests to keep production lean and bug free, and build graphs to help us monitor our code and react with data. (We love data in case you didn't know 😉 .)There's a lot to do and it's exciting!

If you want to join the adventure, well… we're hiring!

PS: BuzzFeed Product is hosting its second Sketch Meetup in NYC. You should stop by!