Autobutler style guide / kitchen sink

The Automic Design Methodology

This is the methodology used within Autobutler when structuring front-end code and defining design elements.

It is an amalgamation of Brad Frost's Atomic Design methodology and this article about using said methodology in a Sass codebase.

I have chosen to name it Automic Design and for that, I am truly sorry.

Let's get started with the various types of elements that we'll be working with in this methodology.

Utilities

Before we can start building anything, we need a foundation and basic plumbing in place. This is where utilities come in.

This is a place for global variables, colors, mixins, functions, extensions, grid systems… anything Sass-y that we will be using throughout the project.

Quarks

The smallest entity that Brad Frost describes is the atom, but we are going to go one step further and use quarks as our most basic building blocks.

From Wikipedia:

Quarks are one type of matter particle. Most of the matter we see around us is made from protons and neutrons, which are composed of quarks.

Quarks is what we use to describe basic HTML elements like headers, paragraphs, inputs etc. The styles applied to these elements are meant to override default / browser-specific styles and will apply to all elements of their given type.

Atoms

Compared to Brad Frosts description of atoms, we are going to get a little more specific. According to his definition, atoms would encompass both colors, fonts, animations, plus default and non-default HTML elements. Our definition of atoms will only include classified elements, but these will still be very basic and have a global scope.

A good example would be buttons. In our codebase, a button is an atom that can be used in many places, and in many contexts, but it doesn't do much on its own. Our buttons need to have consistent basic styles applied to them in order to unify the overall impression of the site. Therefore any basic button styles would have to be defined on an atomic level.

Molecules

In chemistry, molecules are groups of atoms bonded together, which take on new properties as a result.
In interfaces, molecules are groups of elements that function together as a unit.
– Brad Frost

This time our definition is very much in line with Brad's.
Any molecule is a combination of two or more atoms that, when put together, form an element that may act and / or look different than the atoms do on their own. A molecule should be a reusable interface element that does one thing and does it well.

Organisms

Organisms are groups of molecules joined together to form a relatively complex, distinct section of an interface.
– Brad Frost

Once again we must deviate from Brad's original definition.
Agreed, organisms are groupings of molecules and maybe a few atoms, but his scope is too wide. An organism doesn't necessarily have to take up a distinct section of an interface, i.e. be a top level element; it can just be a more complex element that ties together some existing molecules and atoms in a new context.

Organisms allow us to create more complex interface elements which are still modular enough to be reusable, as they should be.


This is where we stop following Brad's methodology and start applying our own naming conventions and structure. Originally the next two types of elements would be Templates and Pages, but we only have one: Partials.

In closing

I hope the concept of Automic Design (once again, so sorry) is clear and that you find it to be a reasonable way to structure our code base.

Moving our existing code to this new structure will be an ongoing process. I therefore encourage anyone who touches old front-end code to consider, how this particular piece of code might be split up and structured in a way that would conform to our new methodology.

Any new code should of course adhere to the rules set forth by this document, but if you're in doubt, talk to your fellow developers about it. As much as we want it to be, code structure is not an exact science, and we should always look for better ways of doing things. We can only figure out what's best for all by working together.

Thanks for reading!