Skip to main content

Get aquainted with Omega's SASS file structure

Sass and Compass in Drupal Omega theme

One of the most useful features of Sass is being able to separate your styles into separate partial sass files (prefixed with an underscore). You can then use the @import directive to include the source of your partial files into one master stylesheet.

How you structure these files is up to you - Drupal's Omega theme has its own approach that I think makes a lot of sense, certainly as a guideline.

SASS file roadmap

sass/              
|
|- abstractions/             # Partials for custom mixins and extends.
|              
|- base/                     # Partials for base styles of raw HTML elements.
|  |-- _forms.scss           
|  |-- _lists.scss           
|  ...
|
|- components/               # Partials for individual components of your site.
|  |-- _navigation.scss      
|  |-- _search.scss          
|  ...
|
|- variables/                # Partials for sass variables.
|  |-- _colors.scss          
|  |-- _typography.scss      
|  ...
|
|- themename.hacks.scss      # Can be used for temporary hot-fixes.
|- themename.no-query.scss   # Re-renders themename.styles.scss without any media queries.
|- themename.normalize.scss  # Provides CSS reset based on the legacy variables.
|- themename.styles.scss     # Primary stylesheet aggregates the partials into a single file.
sass/              
|
|- abstractions/
|              
|- base/
|  |-- _forms.scss           
|  |-- _lists.scss           
|  ...
|
|- components/
|  |-- _navigation.scss      
|  |-- _search.scss          
|  ...
|
|- variables/
|  |-- _colors.scss          
|  |-- _typography.scss      
|  ...
|
|- themename.hacks.scss
|- themename.no-query.scss
|- themename.normalize.scss
|- themename.styles.scss

The import process

The themename.styles.scss file first imports the external libraries and then imports our partials.

@import "compass";
@import "breakpoint";
@import "singularitygs";
@import "toolkit-no-css";

@import "variables/**/*";
@import "abstractions/**/*";
@import "base/**/*";
@import "components/**/*";

You can see from the asterisks that sass globbing is being used - this is really handy, it means the sass files inside these folders (and any subfolders within them) will automatically be imported.

This does mean however that you won't have any control over the order in which the files inside each folder are imported - they will be imported in alphabetical order. This shouldn't bother us though, because we still at least have control over the order the folders are imported, and files within the same folder should be self contained enough to not depend on one another.

Categorising the SASS partial files

Variables

One of the best things about SASS is that it allows you to define variables. Using variables makes it much easier to ensure consistency throughout your stylesheets for values such as colors and numeric values. The variables folder is imported first, and for good reason - all of your other sass files will likely need to access these variables.

You can categorise your variables how you like, they give you example files for things like color and typography but depending on how many variables you will actually have, you could have them all in one file if you prefer.

Abstractions

The abstractions folder is for all of your custom mixins and extends. These can safely be imported second because your variables will not need to access your abstractions. A good example of a file you might want in here is _buttons.scss for mixins and extends relating to the style of buttons. For a good guide on effectively using mixins and extends check out this post: should you use a Sass mixin or @extend?

Base

The base folder is for defining the default style of raw HTML elements such as headings, paragraphs and lists. Common Drupal elements, such as basic form items, should be covered as well. Keep in mind that this is purely the plain, default style of these elements and any context dependant styles should be put into a component file. A good rule of thumb also is to not use any classes in these files - except for perhaps super basic Drupal classes such as .form-text.

Components

With all of that said, the components folder is actually where you will be spending most of your time. Loosely speaking, this folder contains files for all the "components" of your site. "Components" in this context can mean whatever you want really, it's basically all of the styles of your site, broken down and categorised into these files. Each component has its own file - these could be for things like content types, menus, views, whatever.

Because there is so much room for customisation and categorisation here, and it largely depends on the size and scope of your project, here is an example of how you could structure the components folder:

components/
|- article/
|  |- _defaults.scss
|  |- _full.scss
|  |- _teaser.scss
|
|- product/
|  |- _defaults.scss 
|  |- _full.scss
|  |- _teaser.scss
|
|- views/
|  |- _product-listings.scss 
|  |- _blog-listings.scss 
|
|- forms/
|  |- _user-register.scss
|
|- blocks/
|  |- _related-content.scss
|
|- _menus.scss
|- _layout.scss
|- _search.scss

This level of categorisation is pretty thorough and obviously wouldn't be necessary for all projects but it does give you an idea of the kinds of things you might want components files for.

Extra sass files

themename.normalize.scss

This file is included by default and provides a CSS reset/normalize. If you don't already know, normalize makes browsers render all elements more consistently and in line with modern standards.

themename.no-query.scss

This file works with the breakpoint mixin and re-renders the same contents as the styles.scss file but without any media queries. It can be used as a fallback for for older browsers that don't support media queries. You can find more information about this on the github repository of the breakpoint Compass gem.

This will actually work with any sass file ending in .no-query.

themename.hacks.scss

This file may be used to provide temporary hot-fixes for style issues that you plan to properly implement as components at a later point in time or simply don't have a proper solution for yet.

Read the Omega documentation

Omega's documentation is really great and a lot of the stuff I have written in here more-or-less comes directly from Omega's readme files so if you need more information I definitely recommend checking them out.