acl-1.0.10

SCSS Guidelines

Things around us are changing quickly, this is why we want our code to be written with “change” in mind. We are following very strict sets of SCSS writing rules to ensure a clear, maintainable and redundant-free codebase. Basically we want:

“Every line of code should appear to be written by a single person, no matter the number of contributors.” —@mdo

Folder Structure

For our folder structure, we’re applying the 7-1 pattern, which means 7 directories and 1 main file. Check out the structure below to see what it means.

sass/
│
├── base/
│   ├── _reset.scss
│   ├── _typography.scss
│   └── ...
│
├── components/
│   ├── _buttons.scss
│   ├── _carousel.scss
│   ├── _cover.scss
│   ├── _dropdown.scss
│   └── ...
│
├── layout/                 # Can be named as "partials"
│   ├── _navigation.scss
│   ├── _grid.scss
│   ├── _header.scss
│   ├── _footer.scss
│   ├── _sidebar.scss
│   ├── _forms.scss
│   └── ...
│
├── pages/                  # Styles for specific pages
│   ├── _home.scss
│   ├── _contact.scss
│   └── ...
│
├── themes/
│   ├── _theme.scss
│   ├── _admin.scss
│   └── ...
│
├── utils/                  # Can be "helpers"
│   ├── _variables.scss
│   ├── _functions.scss
│   ├── _mixins.scss
│   ├── _helpers.scss
│   └── ...
│
├── vendors/                # Vendor including the version
│   |– bourbon-4.2.4        # Bourbon
│   |– neat-1.7.2           # Neat
│   └── ...
│
└── main.scss               # Main file
Main File main.scss

The main.scss should only be used to import all the other files inside the directories. Below are bad and good examples of importing in SCSS.

Bad example

@import 'utils/_variables.scss';
@import 'utils/_functions.scss';

Good example

@import 'utils/variables';
@import 'utils/functions';
@import 'utils/mixins';
@import 'utils/placeholders';

@import 'vendors/bourbon-4.2.4';
@import 'vendors/neat-1.7.2';

@import 'base/reset';
@import 'base/typography';

@import 'layout/navigation';
@import 'layout/grid';
@import 'layout/header';
@import 'layout/footer';
@import 'layout/sidebar';
@import 'layout/forms';

@import 'components/buttons';
@import 'components/carousel';
@import 'components/cover';
@import 'components/dropdown';

@import 'pages/home';
@import 'pages/contact';

@import 'themes/theme';
@import 'themes/admin';

or

@import
    'utils/variables',
    'utils/functions',
    'utils/mixins',
    'utils/placeholders';

@import
    'vendors/bourbon-4.2.4',
    'vendors/neat-1.7.2';

@import
    'base/reset',
    'base/typography';

@import
    'layout/navigation',
    'layout/grid',
    'layout/header',
    'layout/footer',
    'layout/sidebar',
    'layout/forms';

@import
    'components/buttons',
    'components/carousel',
    'components/cover',
    'components/dropdown';

@import
    'pages/home',
    'pages/contact';

@import
    'themes/theme',
    'themes/admin';
Component-Oriented Thinking

Here’s a very good explanation of the advantages of components.

Component driven development offers several benefits when reading/writing HTML and CSS:

Few things to keep in mind about components:

Naming Convention</code>

The basic of naming convention for SCSS class names:

We also adapted our naming convention from rscss

Color

Bad example

.item {
    background-color: black;
    color: #FFFFFF;
}

Good example

.item {
    background-color: #000;
    color: #fff;
}
Sorting
.item {
    @extend %general-item;
    @include align-items(center);
    @include display(flex);
    @include size(300em);
    @include transform(translateY(3em));
    font-size: 1em;
    font-weight: 300;
    text-align: center;
}
Vendor Prefix

The reason why we often use @include is because we want to avoid the hassle of putting vendor prefixes for a lot of properties. Here’s how you should be doing it.

Bad example

@mixin transform($value) {
    -webkit-transform: $value;
    -moz-transform: $value;
    transform: $value;
}

Good example

.item {
    @include transform(translateY(30em));
}
Zeros

Bad example

margin: 0px;
opacity: 0.3;
padding: 20px 0px;

Good example

margin: 0;
opacity: .3;
padding: 20px 0;
Selectors

Bad example

#home-page {
    ...
}

.profile-view .profile-header .avatar-placeholder .user-nameholder .username {
    ...
}

a {
    ...
}

Good example

.home-page {
    ...
}

.link {
    ...
}
References