Got Messy Spaghetti Stylesheets? 4 Techniques for Managing CSS Complexity
Tags: css, webdev
Published: 2022-04-29 19:31:58

Last week, I wrote about [the definition of CSS complexity](https://blog.shimin.io/understanding-css-complexity/) and how CSS features have inherent complexity – that is, complexity outside of a web designer's control.

This week, I want to take a look at some tried and true techniques for unwinding your spaghetti CSS. The techniques are covered in their general form – with links to framework level implementation examples.

This is not a 'list of CSS methodologies' post – there are enough of those. Nor will I try to convince you to use 'The One Framework / Process' – every team is different and every project's needs are unique.

My goal for this post is to provide a few metrics to analyze CSS technologies, which will hopefully help you (and myself) choose the right one for a new project.  

### Complexity Recap

Here's a quick summary of CSS complexity:

> CSS complexity is anything related to the CSS of a project that makes it hard to understand and modify.

CSS complexity shows up in 3 forms:

-   _Change Amplification_: making a style change require multiple edits.
-   _High Cognitive load_: a large amount of context is needed to make a change_._
-   _Unknown unknowns:_ when it is not clear where to make a change.

Ok, on to the techniques!

### Limit Selector Combination

One of the biggest source of CSS complexity is selector explosion and the resulting specificity escalation – where an `n`th level element with a single class on the page has >`2^n` possible combination of potential class based selectors. CSS's machine friendly specificity score calculations only adds to this problem. (See example from [last post](https://blog.shimin.io/understanding-css-complexity/))

This problem affects all 3 symptoms of complexity: In order to make a style change, you now have to remember all selectors targeting the element (_high cognitive load_) track down the right ones (_unknown unknowns_), and potentially change multiple files (_change amplification_),

Because this is a foot-gun, all CSS frameworks and best practices **_imposes limits to the selector space_**_._ The the advice 'don't use elements in your selectors' as an example, it removes a substantial subsets of potential selectors.

_Framework examples_:

-   [Tailwind](https://tailwindcss.com/) sticks to a single level of class based specificity – not including normalizing CSS.
-   [Block Element Modifier (BEM)](http://getbem.com/introduction/) takes a similar approach and recommends against using [combined selector for variations](http://getbem.com/faq/) – limiting selector space to class based selectors with at most 2 levels.
-   [Scalable and Modular Architecture for CSS (SMACSS)](http://smacss.com/) does not restrict selector type, instead opting for limiting depth. It allows for layout ids and modules can potentially [double up on class selectors](http://smacss.com/book/type-module).
-   The example of never using elements in your selector came from [Object Oriented CSS (OOCSS)](https://www.slideshare.net/stubbornella/object-oriented-css).

The exact number of allowed selectors isn't as important as the need to have a principled way to limit selector depth.

The difficulty of limiting selectors is it needs to be both documented and enforced. It's easy to slip up when 'design needs this change done yesterday'.

### Reduce Property Overlap

Source order is another major source (sorry) of CSS complexity. The same component on different pages might have different styles due to different import orders – especially if selector specificity is flattened.

This leads to both _unknown unknowns_ (which file to change?) and high _cognitive load_ (remember to always include `foo.css` before `bar.css`).

The best way to combat this is _**ensuring overlapping selectors do not overlap in CSS properties**_. And if they have to overlap, make sure their relative specificity is unambiguous.

_Framework examples_:

-   Atomic frameworks like [Atomic CSS](https://acss.io/) and Tailwind takes a single purpose approach to selectors, so CSS properties are naturally never overlapping – this is also why Tailwind's `@apply` is an anti-pattern when overused.
-   BEM is [against global modifiers](http://getbem.com/faq/#can-i-create-global-modifier) for this reason also, and modifier styles should always be declared after the block.
-   When global utilities are encouraged, as is the case with [ITCSS](https://itcss.io/), utility classes are encouraged to have `!important` applied to all values. So the property value is always clear.
-   [CUBE CSS](https://cube.fyi/) gets around to this problem by [separating layer concerns from visual properties](https://cube.fyi/composition.html#why-macro-level-thinking). Layout classes and blocks should not share properties.  

When not using a utility first approach, it can be difficult to keep track of all classes' overlapping properties in a project. I think this is an area with a need for better tooling.

### Restrict Selector Scope

CSS is global in scope – at least pre [cascade layers](https://css-tricks.com/css-cascade-layers/). As with code, global CSS leads to name conflicts in large projects. When creating a new component, you need to keep in mind every class name used in the project along with potential 3rd-party classes.

This imposes a _cognitive load_ penalty that scales with the size of the project and the number of developers working on it.

The solution to this problem is the same as in programming, you _**reduce selector scope to eliminate possibility of collision**_.

_Framework examples:_

-   Component based CSS frameworks originating with [OOCSS](https://github.com/stubbornella/oocss/wiki) inherently limits selector scope to only elements inside the 'CSS object'.
-   ITCSS / BEMIT introduces a [Hungarian notation of class names](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/) to aid in reading – this reduces cognitive load when reading CSS.
-   Taking the idea to somewhat of an extreme, [CSS modules](https://github.com/css-modules/css-modules) explicitly makes all CSS locally scoped by default.

There's not much downside to limiting CSS scope, although when taken too far you'll end up with larger stylesheets than needed. You can prevent this through planning out sensible global default styles, I especially like CUBE CSS's approach to [progress enhancement](https://cube.fyi/css.html).

### Style Colocation

The last problem I want to take a look at is the inherent complexity of using class name based CSS hooks.

Image you have a large, existing e-commerce site. One day, your designer asks you to add a purple decorator to female gendered product category headings and another for male ones. Assuming this was not an abstraction previously included in your site's markup, now you need to come up with a semantic and non clashing class name for gendered heading variation. Then you need to update the code that generates the reusable heading template to add logic for `heading--male` and `heading--female`. _Side Note: there are lots of other ways to do this, but for this example I'm limiting it to a BEM modifier._

In my opinion, this is 'play-pretend separation of concerns', a style-only update now triggers a 'semantic' html rabbit hole. I'm not the only one to feel this way, I first came across a clear description of this problem in this [Adam Wathan post](https://adamwathan.me/css-utility-classes-and-separation-of-concerns/).

This pattern leads to _change amplification and unknown unknowns_, you have to find the right HTML template and its corresponding CSS file, make the same modification in both places at the same time, and if you make a typo in either case, check two files to find it.

This problem is best mitigated by **placing style information right next to HTML templates**. This way, even if you have to invent a new 'semantic classname', you at least can do it in the same file.

_Framework examples:_

-   Some leave out style hook class names all together, instead use aria attribute and semantic HTML elements to separate style from markup. See this [Heydon Pickering Smashing Magazine Article](https://www.smashingmagazine.com/2012/06/classes-where-were-going-we-dont-need-classes/) and [Enduring CSS chapter](https://ecss.benfrain.com/chapter6.html).
-   Atomic approaches ([ACSS](https://www.smashingmagazine.com/2013/10/challenging-css-best-practices-atomic-approach/), [Tailwind](https://tailwindcss.com/docs/utility-first)) get around this by using only style based hooks, reading the class is looking at its style – no need to cross reference.
-   CSS-in-JS category of tooling ([JSS](https://cssinjs.org/?v=v10.9.1-alpha.2), [Styled-Components](https://styled-components.com/), etc.) does 'inline++' styling, which also has the added benefit of placing style information right next to template.
-   Lastly, JS frameworks like [Vue](https://vue-loader.vuejs.org/guide/scoped-css.html) and [Svelte](https://svelte.dev/) provide an all in one experience, where template, style, and functionality all live in the same file.

The largest drawback of this approach is it violates the traditional concept of separate JS, CSS and HTML files, each responsible for its own domain of the web experience.

### Take Aways

Next time you read about 'the next big CSS paradigm', you can map its features to one of the general techniques above. And if you are looking to create your own CSS workflow / framework, I hope you will take these general patterns into your consideration.

I finished the initial draft of this post feeling like I've only made a dent in the topic – serves me right for trying to cover an area as broad as 'how make CSS less complex'. So please let me know if I've missed one – or a dozen – of your favorites. Leave a comment below or ping me on Twitter [@ItsTrueInTheory](https://twitter.com/ItsTrueInTheory).