Let’s have a closer look at the Sass setup within
explain how we structured the code in there. These principles can be
expanded to other preprocessors options such as Less or HAML.
Every folder within
/private/sass has a file called _all.scss.
This file ultimately gets imported by
/private/sass/base.scss which gets
/static/css/base.css. Update the _all.scss file to include
additional modules. To keep the file simple, do not include files directly
Let’s cover the folders individually:
If a component is plug-and-playable, it probably belongs in here. Good examples
are jQuery plugins or Aldryn addons. Sometimes larger application such as a
shop might also be pluggable. If this is not the case, they belong in
You will always encounter the question whether to place a component within
/sass/sites. In case of doubts, use the
We consider the general look and feel as the layout of a website or
application. This might include the typography, header and footer, icons or
the printable version. The layout can be broken down into further parts if a
website gets very large. We advise in general against this strategy and rather
prefer to use
/sass/sites to create specific layouts and derive from a
global common style guide.
Everything that targets a specific element, such as custom styles for
Bootstrap components or a specific form error, belongs in
All independent files are placed within this folder. This implies that the
order of inclusion does not matter within
Libraries are, in their very core, plug-and-playable. The main difference between libraries and other plug-and-play components is, that if a library is removed, things will break.
This folder is used to store additional functions or mixins which are not part of the default bootstrap eco-system.
We provide already some helper functions such as
em(12px, 16px) that
calculates the pixel values from a given size in relation to the parent size.
Additionally we have mixins for managing z-index layers and hide-content.
It is very useful to store values, that are used more than twice, within their
own variable. We even encourage storing all colour values within the
settings. Don’t repeat yourself. Create a sub-structure, similar to
/sites if the structure becomes more complex.
Do not add additional variables to
This file is reserved for Bootstrap-only variables. Use
Besides /addons you will work mostly within the
folder. All custom elements that are in general not plug-and-playable,
fixed into the website somewhere or specific components, get thrown in here.
This will force you to devise and adhere to structure patterns. Here are some examples depending on the requirements for your project:
Let’s assume you create one style guide sharing different marketing websites or applications - your structure might look something like:
sites/ ├─ application/ │ ├─ _all.scss │ ├─ _general.scss │ └─ _wizard.scss ├─ marketing/ │ ├─ _all.scss │ ├─ _layout.scss │ └─ _addons.scss ├─ _application.scss (imports application/_all.scss) └─ _marketing.scss (imports marketing/_all.scss)
If you are using different themes for the same markup, your structure might look something like:
sites/ ├─ dark_theme/ │ ├─ _all.scss │ ├─ _header.scss │ └─ _footer.scss ├─ white_theme/ │ ├─ _all.scss │ ├─ _header.scss │ └─ _footer.scss ├─ dark_theme.scss (imports dark_theme/_all.scss) └─ white_theme.scss (imports white_theme/_all.scss)