Jono Herrington

Build A Strong Sass Architecture: Part 3

In part 1 and part 2 of this blog series, we looked at the components and principles that make up a strong Sass architecture. As we wrap up this series, I would like to conclude by sharing some practical examples.

As I have stated in all posts within this series, I think it is very important to say that I do not believe there is a one-size fits all. Therefore as I share what I have found to be helpful, it is not me saying "this is the way you must do it!" My hope is that this serves as a spring board to help you and your team think through why you have the architecture that you have, and to investigate if there are ways that you can improve it.

Before we dive into showing any examples, let us give a high level overview of the components and principles that make up a strong Sass architecture. First off the components. A strong architecture should have the following sets of components:

Components

  1. Solid and sturdy
  2. Useful and pleasing

Principles

  1. Define clear coding methods
  2. Develop with patterns in mind
  3. Utilize name spacing
  4. Create a sense of hierarchy
  5. Create naming conventions that make sense
  6. Account for states and themes
  7. Abstract patterns from layout
  8. Account for responsive

Now as we begin to look how to apply this practically, I think its worth bubbling the principles up into two main groups:

  1. Coding Standards
  2. Structure

Coding Standards

Setting up coding standards is extremely important when creating a strong Sass architecture. The main reason for this is that it gives us a foundation that will guide others who participate in the project. It also keeps us honest when we are writing code ourselves to uphold the principles we lay in the beginning. The way that our team approaches this is by:

  1. Creating documentation around what our coding standards are.
  2. Making sure that we use comments aggressively to provide clear direction.
  3. Building generators that will automatically scaffold out barebone partials.

Creating Documentation

This is extremely important when establishing coding standards, if not the most crucial thing. Taking the time to document your standards displays that you care about the code you are writing so much that you are willing to put in the effort to document it. If there are CSS methodologies you are applying, document it. If there is a certain way that patterns should be broken up, document it. If there are certain ways people should order properties, document it. If there is certain naming conventions you are following, document it. If you are requiring name spacing, document it. Document everything!

I know this is no small task. I am not going to lie to you. Writing technical documents can be one of the most mundane and boring activities one can do. Now I know ... I know ... you may love it. You may live for it. However for the sane people in this world, we would rather be writing code than writing about code. This takes us back to the point that if you are willing to spend your time on it, what you are trying to accomplish is important.

With this said it is not good enough to just document your standards. You also must make them easily and readily accessible. We have found this to be true on our own team as we work with resources in house as well as offshore resources. Also our in house resources sometimes work remotely. Therefore it is crucial for us to have the ability to easily share these standards with everyone, no matter where they are. The way that we approach this is that we have created a repository that holds all of our coding standards documentation. With that said, this could be done a number of ways. It could be in Google, Word, Confluence, etc. However you want to do, it doesn’t matter to me. All I’m saying is do it.

Use Comments Aggressively

Another way to ensure coding standards is to use CSS comments aggressively. Document everything that you can possibly document inside your Sass partials. One great example of using comments effectively is intuitcss. Harry Roberts, the wizard of CSS, along with some contributors have assembled a framework that utilizes CSS comments like no one else's business. The reason these are so important is because:

  1. It keeps you honest.
  2. It keeps others honest.
  3. It gives others clear markers of why you made the decisions you made.

Build Generators

Building generators is a great way to save you time when working on a project. It also is a great way to set yourself up for success when attempting to adhere to your coding standards. An example of this is that our team has a very particular way that our Sass partials should be written. By creating generators, when developing a new pattern, we are able to quickly scaffold out barebone templates that establish a clear path to sticking to our coding standards.

Structure

Naming Conventions

"you give a dog a bad name, and that dog is bad for life." - Eleanor Catton, The Luminaries

Naming things is one of the most difficult things that we have to do when developing. When you name things, the name usually sticks for the life of the application. Bad names can lead to confusion and complications. When you name things well, you strengthen the project. Your code is more clear and simplistic. It makes developing easier. Therefore we must spend the time to come up with strong naming conventions for our Sass architecture that make sense to those we are currently working with, as well as those we will someday onboard.

The team I work am a part of has spent hours upon hours solidifying and coming up with naming conventions that make sense to our company as a whole. This process has not only included developers but also our user experience design team. The reason this is is because we find it extremely important to be able to have a vocabulary that we are all comfortable with and understand, no matter what phase of the project. Since we have spent the time, we can use it when speaking to design patterns during design critiques as well as to establish the structure for our Sass architecture.

The great thing about naming conventions is that others have spent more time than you and I to fully think through and come up with ideas on how things should be named well. Therefore do not feel like you have to reinvent the wheel. I know for myself the following articles and applications have heavily influenced the way that I name and structure things. They are:

  1. Atomic Design - Brad Frost
  2. SMACSS - Jonathan Snook
  3. More Transparent UI Code with Namepaces - Harry Roberts
  4. Fabricator - Luke Askew

After applying thoughts from all of these, the naming convention that our team currently uses is:

  1. Base - This talks to anything where you are directly styling an HTML element.
  2. Components - This speaks to foundational design patterns. This could be a button, a form row, a navigation block, etc
  3. Structures - Structures are like a super component. They are anything where you have to combine two or more components together. An example might be a global header or footer.
  4. Objects - Objects are what make up the core layout of the overall project. They are things that once you create, you should be very cautious at changing as it could effect your project in ways you may not fully understand.
  5. Scopes - These partials are used to wrap up blocks of html elements where you want to style them a particular way, but do not have control over the classes that get applied. The most generalized case is anywhere where content is being populated through a WYSIWIG.
  6. Utilities - Utilities are complete single responsibility rules which have a singular task. They might be used to set a particular margin or give text a certain color.
  7. Themes - These account for any stateful themes that might be applicable within a project.

Directory Structure

Once we established a naming convention that made most sense for our team, we used that to influence our directory structure. Therefore our directory structure looks like this:

Sass Directory Example

The main difference that you might see from our naming convention to our directory structure is that there are two additional directories. These are resets and helpers.

Summary

At the end of the day, it is crucial that we take the time to think through the way we approach our Sass architecture. We can do this best by applying core principles to the thought process of what we create. There are many places where we might end up; however, we cannot compromise on anything less than an architecture that is strong and sturdy, and useful and pleasing.

Take the time to document your processes. If they are truly important to you, then they should be important enough for you to want to communicate them clearly to all parties.

Do not create architectures in your own individual bubble. Work with cross disciplinary teams to ensure you have a vocabulary that is understood by all parties no matter the phase of the project.

Go and build. Build strong Sass architectures.