CSS Architectural Overview
The main principals of the Workarea CSS architecture were modeled after OOCSS and ITCSS best practices. You will find that the architecture is layered. Each layer has a specific purpose and is naturally more specific than the layer it proceeds. This allows a developer to think about the purpose of the CSS he or she is writing before dropping it in a corresponding layer, keeping the application manifest direct and to the point.
Cascading Style Sheets
Stylesheet manifests take your referenced CSS files and produce a concatenated, production-ready file. It's important to note that the order of these files is honored during the concatenation process. This just means that the contents of the files at the top of your manifest will be output before those listed at the bottom of the manifest.
A main pillar of the Workarea CSS architecture is to harness and reinforce the natural cascade of CSS. CSS files are parsed top-to-bottom and precedence is given to CSS rules that appear lower in the code, as seen in this very simple example:
`.component { background: red; }
.component { background: blue; }`
When this code reaches the browser the component is blue, because of the cascade.
Therefore, your most general CSS rules should be found at the top of the manifest, and your most specific CSS rules should be found at the bottom. By always keeping this in mind, you enable yourself to write scalable, purposeful and technically correct CSS.
Layers
To reinforce the cascade of increasing specificity, the Workarea platform defines specific various CSS layers. All of the CSS files that you write should live in directories named after the file's intended layer. For example, if you create a component for the Storefront called toggle-button
, that file should live within workarea/storefront/components/_toggle_button.scss
. This files reference should then be added to the Components layer of the manifest.
I've listed the main layers below. By "main layers" I mean they are the layers that define the core architecture. There are a few plugin-specific layers offered (which I'll cover in a bit), in addition to the following:
- The Settings Layer
- The Tools Layer
- The Generic Layer
- The Base Layer
- The Objects Layer
- The Typography Layer
- The Components Layer
- The Trumps Layer
The Settings Layer
This layer contains variables which are meant to be globally available. They are considered safe for general use and you'll find them peppered throughout the proceeding Sass files.
Each carry a !default
flag, allowing Theme plugins or multi-site configuration to override their values, if necessary.
The Tools Layer
This layer contains only functions and mixins. They're helpers that let you dry up your code or perform more complex calculations.
The Generic Layer
This is the first layer where we start to see some CSS. The Generic Layer is the most global CSS you'll find in the project. We start off with including the Normalize library, which we tweak the configuration of just a bit in our own reset.css file.
Here is where we set up our global page box-sizing and whatever fonts we'll be using for the project.
The Base Layer
Now that a sane foundation has been laid, we can begin to apply some default styling to element selectors.
The biggest element we style is the html
element (in _page.scss
). Then we ask ourselves what should specific elements look like if we were to just drop them on a page, devoid of classes. This is where your default table
element and ul
element styling lives. Each file is grouped thematically, by usage. So the _forms.scss
file contains default styles for form
, input
, and textarea
tags, for example.
The Objects Layer
Objects are probably the hardest part of the architecture to grasp. They are intended to be design-free classes and placeholder selectors that allow you to DRY up your codebase. An inline-list
should remove the bullets of a list and make it's children display horizontally rather than vertically. A button-reset
should remove all browser styling of a button, so that a component class can start applying design styles in a clear an direct manner.
The Typography Layer
Here we find all of the text-based styles in the app. All headings are defined here. Utility classes to easily allow a developer to left, right, or center-justify some text are defined here. Links and paragraphs are defined here as well.
The Components Layer
All of the styles leading up to this layer have ensured that our document looks just like a well formatted document. The Components layer takes that document and makes it into a real website. It provides each of the building blocks needed to achieve layout, the design, and the pleasurable user experience your customers will enjoy.
The Trumps Layer
Lastly we have the Trumps layer. Trumps are the law. When their classes are applied to an element they are expected to react accordingly. There is no ambiguity in this layer. It contains styles that must be applied, at any cost. If you need to use the !important
flag on a value, feel free, but you shouldn't have to, since these styles are naturally the most specific.
Plugin-Specific Layers
In addition to the aforementioned layers, there are a few layers used only by Plugins.
The Theme Config Layer
Theme Plugins are a special type of plugin who's primary purpose is to make the default Storefront look vastly different. These plugins make use of the Theme Config layer, which appears just before the Settings layer. Theme Plugins can override any Sass variable that carries a !default
declaration which, out of the box, is every declared variable.
The Theme Layer
Theme Plugins use this layer to further augment the styling of the system. The Theme layer appears directly after the Components layer, and right above the Trumps layer, to allow increased specificity beyond that of the Components layer.
Help Us Improve this Doc
Was this helpful? Open a GitHub issue to report a problem with this doc, suggest an improvement, or otherwise provide feedback. Thanks!