Private¶
Note
Let’s have a closer look at the Sass setup within /private
and
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
compiled into /static/css/base.css
. Update the _all.scss file to include
additional modules. To keep the file simple, do not include files directly
within base.scss.
Let’s cover the folders individually:
addons/¶
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
the /sass/sites
directory.
Warning
You will always encounter the question whether to place a component within
/sass/addons
or /sass/sites
. In case of doubts, use the
sites folder.
layout/¶
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.
Warning
Everything that targets a specific element, such as custom styles for
Bootstrap components or a specific form error, belongs in
/sass/addons
or /sass/sites
.
libs/¶
All independent files are placed within this folder. This implies that the
order of inclusion does not matter within /sass/libs/_all.scss
.
Hint
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.
mixins/¶
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.
settings/¶
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.
Warning
Do not add additional variables to /private/sass/settings/_bootstrap.scss
.
This file is reserved for Bootstrap-only variables. Use
/private/sass/settings/_custom.scss
instead.
sites/¶
Besides /addons you will work mostly within the /private/sass/sites
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:
Note
Multisite Setup
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)
Note
Theme Setup
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)