Here’s the Official Trello CSS Guide

Back in September, I published a post about the State of the Trello CSS. I talked about our mishmash of practices, what we’ve learned, and the size and nature of our CSS. It had some ideas about writing and structuring CSS scattered throughout, but it didn’t have a list of hard rules that you could follow. So I thought it over a bit then distilled everything into a real guide.

CSS guides are a big deal, hugely important. If you don’t have a CSS guide, you should be panicking. If writing a CSS guide isn’t your department, send an email to the appropriate team asking them to write one. Did you know you can type “URGENT” in the subject to give it more priority in a lot of email clients? You’ll want to use that. Use BCC so it seems like everyone needs to respond (which they should). Email is the best way to keep track of important tasks like this.

The hysteria is over for us, thankfully. Today, I present to you the official Trello CSS Guide.

The Big Takeaways

I tried my best to explain each of the sections and the rationale behind them. The key idea is at the top of each section. Important ideas are highlighted. There is elaboration. I like to think it’s pretty scannable and readable. But if you’re in a rush, like maybe you need to respond to some emails, here are the big takeaways:

• Be leery of preprocessor features. Use only imports, variables, and mixins.
• Use the .component-descendant-descendant pattern.
• Use the .component-descendant.mod-modifier pattern for modifier classes. No bare .mod- classes.
• Use the .component-descendant.is-state pattern for state. Manipulate .is- classes in JavaScript (but not presentation classes). No bare .is- classes.
• Don’t use global media queries. Include media query variables in your component.
• Separate presentation and behavior concerns by using .js- prefixed classes for behavior. No presentation classes in JavaScript. No JavaScript classes in stylesheets.
• Prefix mixins with .m- and only use them for browser polyfills.
• Prefix utility classes with .u-.
• Use lots of components and files.
• Use normalize.css.
• No ids, element, or universal selectors. Use kebob-cased classes.
• Use a consistent style.

Again, I got into the reasoning for each in the actual guide so I won’t elaborate on it here. Give it a read!

State of the Trello CSS, February 2015

Since the last post, I spent some time applying this guide. I split it up into 63 files from 44 files. I untangled some components and cut out some body classes. I got away from global media queries. I started using normalize.css. I even cut the file size down by 3%, but that was mostly because we found a lot of old cruft while auditing our CSS. There’s still a lot of work to do, but it’s in a much better state.

Like any good guide or documentation, this is a living document. I’m sure we’ll update the guide as we continue to implement it. It may even change in fundamental ways. That’s perfectly fine. I think it’s a solid starting point.

A CSS guide should save you a lot of confusion, debate, and maintenance costs. It will make it easy for newcomers to understand your conventions and contribute. You should write one. It doesn’t have to look anything like ours, but it should be something that people can easily find and something they actually use. You won’t regret it.