Refining The Way We Structure Our CSS At Trello

Trello CSS

Have you been reading all the blog posts about the CSS architecture at various companies out there? No? Check out the ones for GitHub, CodePen, Lonely Planet, Medium, and Buffer. I can’t get enough of them.

We’ve slowly been refining the way we structure our CSS at Trello. I can firmly say it’s pretty okay now, nearing on good. This is our whole deal with CSS, broken up into the following sections.

  1. The Tools
  2. File Structure
  3. Modules
  4. What about JavaScript?
  5. Styles Style
  6. Numbers
  7. Other Junk
  8. The Future…

Warning: this post assumes you make websites and know some things about CSS. If you don’t, that’s okay. You might still enjoy the peek behind the curtains.

1. The Tools

We use LESS for trello.com. I like it because it’s close to vanilla CSS and intuitive. I’m a simple person with simple needs. I don’t know what I would do with loops and guards and math in CSS but I doubt it would be good. We mostly use imports, data-uri, variables, shallow nesting, and some mixins (primarily for vender-prefixed stuff).

We don’t use Grunt or Gulp. I don’t think anyone is strongly against the idea, but LESS has been good enough.

For a new release, we import all the CSS files into a single core.css file using LESS, then CSSshrink and gzip it, and ship it to our CDN. I wrote a post about our whole design, development, and release process in this blog post, which is only tangentially related but I’m going to plug it anyway.

2. File Structure

How are the files broken down? Here’s a really real look at our core CSS file which has all the imports. It has some organizational warts and inconsistencies, but I hope you’ll appreciate the honest view. I tried to break them into sections a few months ago and they only half make sense. I never looked back.

// bootstrapping
@import (less) "variables_mixins.css";
@import (less) "reset.css";
@import (less) "typography.css";
@import (less) "forms_buttons.css";
@import (less) "icons.css";
@import (less) "content_list.css";
@import (less) "editing.css";

// layout
@import (less) "header.css";
@import (less) "woof.css";
@import (less) "dialog.css";
@import (less) "popover.css";
@import (less) "profiler.css";
@import (less) "boards_sidebar.css";
@import (less) "tabbedpane.css";

// board
@import (less) "board.css";
@import (less) "list.css";
@import (less) "powerup.css";
@import (less) "calendar.css";

// card
@import (less) "card.css";
@import (less) "quickCardEditor.css";
@import (less) "attachments.css";
@import (less) "badges.css";
@import (less) "checklists.css";
@import (less) "labels.css";
@import (less) "datepicker.css";
@import (less) "stickers.css";

// member
@import (less) "member.css";
@import (less) "announcements.css";

// organization
@import (less) "organization.css";

// phenom - acions, notifications, invites
@import (less) "phenom.css";

// pages
@import (less) "manual.css";
@import (less) "account.css";
@import (less) "search.css";
@import (less) "ads.css";

// window sizes
@import (less) "lg.css";
@import (less) "md.css";
@import (less) "sm.css";
@import (less) "touch.css";

// utils
@import (less) "spinner.css";
@import (less) "utils.css";
@import (less) "jquery.crop.css";
@import (less) "tooltip.css";
@import (less) "clipboard.css";

// print
@import (less) "print.css";

We try and keep the files as small and modular as possible so that when there is an occasion to delete a bunch of them, like we did with our meta pages, it’s really easy. There is separate CSS for the meta pages and other packages, but those tend to be small and self-contained.

3. Modules

We try and namespace our CSS. What’s that mean? Instead of using descendant selectors, like .header img { … }, we create a new top level, hypen-separated class for descendant selectors, like .header-image { … }.

I’ll give you a complex example. Descendant selectors would look like this:

.global-header {
  background: hsl(202, 70%, 90%);
  color: hsl(202, 0%, 100%);
  height: 40px;
  padding: 10px;
}

  .global-header .logo {
    float: left;
  }

    .global-header .logo img {
      height: 40px;
      width: 200px;
    }

  .global-header .nav {
    float: right;
  }

    .global-header .nav .item {
      background: hsl(0, 0%, 90%);
      border-radius: 3px;
      display: block;
      float: left; 
      -webkit-transition: background 100ms;
      transition: background 100ms;
    }

      .global-header .nav .item:hover {
        background: hsl(0, 0%, 80%);
      }

And so forth. With namespacing, it looks like this:

.global-header {
  background: hsl(202, 70%, 90%);
  color: hsl(202, 0%, 100%);
  height: 40px;
  padding: 10px;
}

  .global-header-logo {
    float: left;
  }

    .global-header-logo-image {
      height: 40px;
      width: 200px;
    }

  .global-header-nav {
    float: right;
  }

    .global-header-nav-item {
      background: hsl(0, 0%, 90%);
      border-radius: 3px;
      display: block;
      float: left; 
      -webkit-transition: background 100ms;
      transition: background 100ms;
    }

      .global-header-nav-item:hover {
        background: hsl(0, 0%, 80%);
      }

This is very efficient because of the low specificity of the selectors. Why? Because browsers read selectors from right to left, meaning the rightmost selector (the key selector) is interpreted first. So you may think everything is all-good-thumbs-up when you write .foo div because there are only a few .foos, but actually you are asking the browser to look up all the tens of millions of divs first, then all the .foos and exponentially more with more descendant selectors. Yipes. For more, check out the CSS Tricks article about efficiently rendering CSS.

I used namespacing in a few places when I spent a week speeding up Trello. It made a noticeable difference, particularly for boards with lots of cards (meaning lots of DOM elements). It might not matter much for smaller sites, but it’s a good practice to get in to.

I also think this makes the CSS more maintainable and readable. It’s obvious that selectors are related. It’s easier to search for selectors and delete them when necessary.

4. What about JavaScript?

I bet your website uses JavaScript. Lots of websites do. We separate our style and behavior concerns by using js- prefixed classes for behavior. Take the following example:

<!-- HTML -->

<div class="content-nav">
  <a href="#" class="content-nav-button js-open-content-menu">
    Menu
  </a>
</div>

// JavaScript (with jQuery)

$(".js-open-content-menu").on("click", function(e){
  openMenu();
});

How does this work? The .js- class makes it very clear to the next person changing this template that it is being used for some JavaScript event. “Hey, you need me to open the content menu!”, the class says. “Don’t worry, template! I wouldn’t want to mess up the content menu! I’ll make sure you work.” *cheering*

Be sure to use a descriptive class that won’t conflict with other classes. The intent of .js-open-content-menu is more clear than .js-menu which is the wrong kind of lazy. You should never see style classes, like .header-nav-button, in your JavaScript, or behavior classes, like .js-open-header-menu, in your stylesheets. Real talk: we sometimes use style class related to state in our JavaScript, but I’ll get to your proposed fix for that later. But if I see someone put .js- classes in a stylesheet? Noooo. I’ll find you, even if you’re half-way across the world. And when I do, I’ll probably… calmly point to this blog post. I don’t want to start any trouble. Not worth it.

5. Styles Style

There are a hundred million different ways to write CSS and many of them are bad, despite being perfectly valid. Take a little time to format it in a way that makes it easy to work with. Take this example:

.global-header-nav-item {
  background: hsl(0, 0%, 90%);
  border-radius: 3px;
  display: block;
  float: left; 
  -webkit-transition: background 100ms;
  transition: background 100ms;
}

Here are some key rules we try and stick to…

  • Use a new line for every parameter. Use two new lines between declarations.
  • Add a single space between parameters, for example param: value; and not param:value;.
  • Indent nested rules so it’s obvious they’re related. You’ll be able to identify and skip sections more easily.
  • Alphabetize parameters. I could probably look up how parameters are semantically categorized by position, dimension, typography, color, etc., but I gave up and used the alphabet.
  • Use 2 spaces, not 4 spaces and not tabs.
  • Use hyphens for class names, not underscores or camelCase.
  • Don’t use 0px when 0 will do. Use shorthand when appropriate, like padding: 15px 0; and not padding: 15px 0px 15px 0px;.
  • When using vendor prefixed features, put the standard declaration last. For example… -webkit-transition: all 100ms; transition: all 100ms;. Browsers will optimize the standard declaration, but continue to keep the old one around for compatibility. Putting the standard declaration after the vendor one means it will get used and you get the most optimized version.
  • Use hsl(a) over hex and rgb(a). If I’m twiddling with colors, it’s easier with hsl, especially when making things lighter or darker. If I’m writing hex or rgb, I have to change all the values and it’s harder to guess what the result will look like. I get a better mental picture of a color when I can say “it’s blue, it’s this saturated, and this light” rather than “it’s this much red, this much green, and this much blue.”
  • Comments rarely hurt. If you find an answer online (read: on Stack Overflow) then add the link to a comment so future people know what’s up.

Of course, these are preferences and you don’t need to use any of them. However, your team should stick to your own conventions.

6. Numbers

  • File size: core.css is 43.3kb gzipped and 202kb raw. It still seems like a lot, but maybe not for a single page app? It’s worth noting that we still use an icon font and that it’s embedded in the CSS. It’s about 8kb raw.
  • Lines of LESS: 14,236. That’s across all of our files. I’m using find static/css/ -name '*.css' | xargs wc -l here. We use new lines liberally, though.
  • Number of CSS Files: 44. We import these into a single core.css in the end, but it’s a show of our modularity. Some of those are really big and we should probably break them down. The biggest file is board.css with 1105 lines of LESS. That feels crazy long to me.
  • Number of Selectors: 2,426. How does that stack up? According to Mark Otto, GitHub has around 7,000 selectors, Bootstrap has 1,900, Twitter has 8,900, The New York Times has 2,100, and SoundCloud has 1,100. This is all according to cssstats.com, which you should check out.

7. Other Junk

  • We tend to avoid body classes. We fell prey to this easy hack early on and we’ve been slowly cutting them out. It leads to more descendant selectors, poor browser performance, and it’s a bad replacement for componentizing your stuff.
  • If there’s a small image, say under 10kb, we save a request by embedding it into our CSS using LESS’s data-uri. We replace the urls of images and font assets with our CDN versions before using data-uri.
  • We don’t actively support IE9. That means we can use stuff like flexbox, which we have.
  • Eventually I want to switch from a font over to inline SVGs for icons. We can safely switch because we don’t offer IE9 support. It’s just a big project.
  • We don’t use normalize.css but we probably should. In fact, we don’t use any frameworks or have other external dependencies. Our meta pages use normalize.css and most of HTML5 Boilerplate as a starting point.
  • We don’t lint our CSS, but our LESS compiler fails fast and loud with the slightest deviance. For some reason, I type “displaY” a lot and it blows up on that. We catch a lot of stuff early this way.
  • Autoprefixer sounds good, but we don’t use it. Probably should.

8. The Future…

One downside of our namespacing convention is that we end up with really long selector names that are hard to mentally parse. Modifier and state-related classes, like .global-header-dark, get easily confused for psuedo-descendant classes like .global-header-logo. There’s a more formal technique called BEM, “Block, Element, Modifier”, that addresses this. This CSS Wizardry article does a good job explaining it.

@fat at Medium ran into the same problems. He has a BEM-like technique that’s a little more approachable. Here are the main points…

  • .js- prefixed class names for elements being relied upon for javascript selectors
  • .u- prefixed class name for single purpose utility classes like .u-underline, .u-capitalize, etc.
  • Introduction of meaningful hypens and camelCase — to underscore the separation between component, descendant components, and modifiers
  • .is- prefixed classes for stateful classes (often toggled by js) like .is-disabled
  • New CSS variable semantics: [property]-[value]–[component]
  • Mixins reduced to polyfills only and prefixed with .m-

The whole Medium guide is listed here and it’s full of great tips. We’ve been happy with js-classes and polyfill-only mixins. I plan to use the .is-, .u-, .m-, and –modifier conventions in the future. They seem semantically clearer to me. Thanks, @fat!

I’m also intrigued by the recently proposed Attribute Modules for CSS outlined by Glen Maddern. I wonder what the performance implications for those types of selectors are, though. More food for thought.


That’s our CSS today. If you look at our CSS file (not recommended) you’ll find that we don’t always stick to these conventions. They’ve evolved over time and there’s still some cruft, but we convert things over as we find them. You know how it goes.

Oh, and if you love this kind of stuff as much as I do then you should apply to our Front-End Developer position!

Share this on:

Related Posts

Trello on various platforms

Using Trello at Work

Sign up for Trello Business Class to learn how your entire team can maximize productivity.

Learn More