The 5th Project: Semantics

I wanted stricter semantics for our code base because for a team of our size I felt like it would be easier to have rules for us to lean on. And I’d rather have something a bit more complicated if that also meant people had to be more mindful when creating new CSS classes. At all costs, I wanted to avoid the run-on classname, or at least make it harder to create.

I began talking at length about it with Daryl Koopersmith and my good friend Nicolas Gallagher.

Nicolas and I have an interesting relationship in that Nicolas always tells me something, I say he’s wrong, call him names in french (Va te faire foutre, enculé), and dance around for a few weeks, before inevitably realizing he’s right, and taking his idea as my own.

This time was no different, and after a few late nights, I was eventually convinced of a style similar to the one Nicolas outlined in SUITCSS. Similar, but ~slightly~ better.

So I began by plagiarizing the hell out of Nicolas. I threw away our old style guide and copy pasted large portions of his, editing a few things here and there.

Eventually I came up with our current guide, which you can read in its entirety below, the main additions being:

• .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-

It’s one thing to copy paste a style guide, it’s another to rewrite all of your CSS application.

Thankfully I was able to convince the company of the importance of this project, if only for my sanity, and was given 2½ weeks to rewrite all the CSS on Medium.com — which if you’re following along, is a fraction of the amount of time it took for us to fix CSS underlines.

That said, this rewrite was not only cathartic, it cleaned up loads of dead styles, tightened up and generalized implementations across the site, broke files out into smaller subcomponents, and to my surprise, only caused a handful of rollbacks.

Of course, refactoring CSS meant also refactoring our templates — adding more encapsulation and stricter semantics across the board. Now today, rather than having hundreds of one off <IMG> tags with random avatar classes for example, we have a single centralized avatar template, which accepts boolean options to trigger different modifiers like size, style, etc. This makes updating styles easier and implementation detail bugs much less frequent.