Writing Maintainable CSS and Discovering the Patterns in Our Front-End

There doesn’t seem to be a golden standard to the way we author CSS in this industry, and I like it that way. There are common best practices, guidelines and a myriad of naming structures but at the end of the day it falls on you to decide what makes sense to you, and what works for the current project. Do what works for you at the time and refactor, refactor, refactor. Failure to take into consideration the importance of organization in your code can and will make you question your sanity at times.

When you’re a dev revisiting old unorganized CSS…

Pirates of the Caribbean: At World’s End (2007)

Make semantic decisions

I utilize the BEM(Block Element Modifier) methodology to write my classes. Naming things in this way encourages a more semantic front-end and sets the stage for reusable components and patterns.

“Where there is consistency, efficiency will shortly follow.”

Semantic front-end in this instance means that you organize your HTML and class structure in such a way that would make sense to other developers. This means not using divs for every single tag. Sometimes it just makes more sense for something to be a ul or something like figure . HTML5 has given us access to a few tags including but not limited to header , main and footer . Use these and others to compose your HTML as semantically as possible.

Writing reusable components

In a perfect world all the CSS we write would be perfectly ported to each subsequent project, saving us time and energy. Yet with each new project comes a whole new set of problems. The solution? Break things up into small reusable patterns that exist without any dependencies. Components, that when properly authored define themselves clearly and still make sense if you were to revisit them months later.

Two questions I ask myself at each stage of a project are…

• What are the common reusable patterns here?
• Can I simplify things more?

There are usually some red flags that indicate whether or not a component should be refactored. I’ve noticed that often times in order to solve a particular layout, especially more complex ones involving multiple layers, positioning attributes are sometimes added to classes that shouldn’t be making those kinds of decisions. If you mix layout and styling you’ll most certainly run in to all sorts of problems.

Best practice for me would be splitting up those layout styles into a separate grid component, or letting the section of UI the component is in dictate it’s children’s positioning. For example, if you have a .btn class for each button in your layout and in one instance in requires margin-top: 50px to fit into a piece of the design. Rather then adding that directly to the .btn class and making the assumption that margin top will always be needed, split that out into a utility class called .mtl with a value of margin-top: 50px . Now you have a utility class you can add anywhere that extra margin is needed and your buttons are free of that constraint.

The “Single Responsibility Principle”

TFW your components have to multitask.

Every component you write should have a single responsibility. I find the principle especially useful when trying to organize your front-end code and build a scalable architecture. Heres an example.

Without the Single Responsibility Principle(SRP).

The .card is responsible for both it’s styling and layout.

.card {
  color: black;
  margin-top: 100px;
  box-shadow: 0px 0px 30px rgba(0,0,0,.3);
  background-color: white;
  font-size: 30px;
  position: relative;
  display: block;
  width: 50%;
  padding: 30px;
}

With the SRP.

You can see that all attributes relating to positioning and size have moved into separate classes. This means the .card now only cares about being a styled block and does not care where or how it’s positioned. The card now has a single responsibility and is much easier to use, maintain and reason about.

.card {
  color: goldenrod;
  box-shadow: 0px 0px 30px rgba(0,0,0,.3);
  background-color: silver;
  font-size: 30px;
  padding: 30px;
}
.half {
  position: relative;
  display: block;  
  width: 50%;
}
.mtxl {
  margin-top: 100px;
}

That was just a simple example but I hope it illustrated the importance of separating concerns in your CSS. Using the SRP as a basis for simplifying your components will ensure that as the project scales, the classes you wrote at the start of the project can still be used and applied to different scenarios.

Sanity preserved.

Folder organization and the config file

Borrowing ideas from MVCSS—a sass based architecture I’ve been heavily influenced by—there are two main ideas I think anyone could benefit from immediately.

1. Always organize your CSS folder.
2. Always have a config file.

An organized folder structure means keeping each layer of your site/application separate. For me this means keeping three distinct folders. Components, Structures, and Foundation.

Components are where I try to put all of my reusable, “these might work in other projects”, components.

Structures are the home of components that became too complex or too dependent to still be qualified as a component. This could be considered the “Refactor Zone”. They probably can’t be reused at the moment and that’s okay. I personally try to be good about splitting my structures up into smaller bite sized pieces, but it’s not always easy to do. A nav menu for example might vary from project to project and be better served as a completely separate entity. If we’re being realistic with ourselves, you’ll almost always have structures throughout your project. As long as you organize them and follow the same principles you would when composing CSS components, you’ll be fine.

The foundation folder is the heart of it all and home to the config file. Using a config file was a big change for me and I don’t think I would start a new project without it. Here is an example.

Only part of a CSS config file, but you get the gist of it.

The config file allows me to define my easing, shadows, spacing, etc. all in one convenient location. It also encourages strategy meetings and collaborative decision making with the designer much earlier on in the project. Together we makes sure to outline things early on that have a huge impact on the overall look and feel of the project like easing, spacing, color and typography.

Wrap up

Every project you work on is going to have different requirements. All you can do is exercise sound principles and refactor, refactor, refactor. Always try to simplify things as much as possible where possible. If the CSS you write feels too complicated or dense, that’s probably a good sign that it’s time to split it up into smaller parts. Staying organized always feels good, and the code you write shouldn’t be an exception.

I’ve found that the way I think about my CSS has translated well into other aspects of my work. One example of this is how I write and manage React components, which encourages a similar mindset. Our brains are wired to recognize patterns. If you listen to your intuition you’ll usually know what path to take when creating a scalable and organized front-end. Remember to have fun and see you next time!

Learn more about Big Vision here, and if you’re curious about working together let us know!

A modern creative agency.