Version 0.40.0

Code Guidelines

SCSS


SCSS structure

The SCSS is splited following the Atomic Design method.

Undescore prefix

Every folders or files that start with an underscore (_) never output CSS and only output variables, functions or mixins.

SCSS folders

Following the Atomic Design, folders in the scss directory are:

_functions  // Global functions (no CSS output here)
_mixins     // Global mixins (no CSS output here)
_settings   // Global variables (no CSS output here)
@fonts      // @font-face declarations
base        // All CSS resets (no classes here)
animations  // All CSS animations (no classes here)

atoms       // Standalone small components
molecules   // Composition of atoms
organisms   // Composition of (or containers for) molecules and atoms
layouts     // Generic ui parts
pages       // Specific ui parts

helpers     // Helper classes

SCSS files

CSS

Each SCSS file in the Atomic folders is named after the block name (see below) of the class .

block.scss

This file must be imported in the saagie.components.scss file.

Variables

If you need some settings (variables) for a component, there are stored in a folder _settings at the same level in a filed named after the block name (see below) of the class:

_settings/_block.scss
block.scss

This file must be imported in the _saagie.settings.scss file.

Mixins

If you need some mixins for a component, there are stored in a folder _mixins at the same level in a filed named after the block name (see below) of the class:

_mixins/_block.scss
block.scss

This file must be imported in the _saagie.mixins.scss file.

Example

// Files
saagie-ui
    atoms
        _settings
            _button.scss
        _mixins
            _button.scss
        button.scss

// SCSS _settings/_button.scss
$sui-a-button-my-variable: black;

// SCSS _mixins/_button.scss
@mixin suiButtonMyMixin {
    ...
}

// SCSS button.scss
.sui-a-button {
    color: $sui-a-button-my-variable;

    @include suiButtonMyMixin();
    ...
}

SCSS syntax

We are using a slightly modified version of BEMIT.

Difference from BEM

Our SCSS syntax use the following modified version of BEM for writing the modifiers.

// With BEM
.block--modifier {}

// With our syntax
.block.as--modifier {}

BEMIT prefixes

The BEMIT syntax adds some prefixes to the BEM syntax. In our case, we are using the following prefixes:

  1. Each css class is prefixed by the general prefix: sui- (Saagie UI).
    It's prevent all conflicts with external CSS.

  2. Following the general prefix, there is the folder prefix: a- for atoms, m- for molecules, o- for organisms, l- for layouts, p- for pages and h- for helpers.
    It's allow to know quickly where the SCSS code of a CSS class is.

Our SCSS syntax

So, our Blocks, Elements and Modifiers are written as follow (x represent the folder prefix):

.sui-x-block {}
.sui-x-block__element {}
.sui-x-block.as--modifier {}
  • block represent the root of the component.
  • block__element represent a child of a block.
  • as--modifier represent a variation of a block. A modifier is never prefixed.

Example

We take, as example, a card (molecule) witch contains a primary button (atom) and a secondary button (atom).

HTML
<div class="ui-m-card">
    <div class="ui-m-card__title">
        Card title
    </div>
    <div class="ui-m-card__desc">
        Card description
    </div>
    <div class="ui-m-card__buttons">
        <button class="ui-a-button as--secondary">
            Secondary action
        </button>
        <button class="ui-a-button as--primary">
            Main action
        </button>
    </div>
</div>
SCSS atoms/button.scss
.sui-a-button {
    ...
    &.as--primary {
        ...
    }
    &.as--secondary {
        ...
    }
}
SCSS molecules/card.scss
.sui-m-card {
    ...
    &__title {
        ...
    }
    &__desc {
        ...
    }
    &__buttons {
        ...
    }
}

Responsive modifiers

Some modifiers can have a responsive suffix as follow:

.as--modifier       // Regular modifier
.as--modifier@xxs   // Modifier only for screen 450px wide or more 
.as--modifier@xs    // Modifier only for screen 600px wide or more 
.as--modifier@sm    // Modifier only for screen 800px wide or more 
.as--modifier@md    // Modifier only for screen 1000px wide or more 
.as--modifier@lg    // Modifier only for screen 1200px wide or more 
.as--modifier@xl    // Modifier only for screen 1400px wide or more 
.as--modifier@xxl   // Modifier only for screen 1600px wide or more 
Screens size Suffix name
All -
450px + @xxs
600px + @xs
800px + @sm
1000px + @md
1200px + @lg
1400px + @xl
1600px + @xxl

To generate responsive modifiers follow this example:

SCSS folder/_mixins/_block.scss

// A mixin with all your modifiers (with a $suffix param)
@mixin suiMyModifiersMixin($suffix: '') {
    &.as--modifier#{ $suffix } {
        ...
    }
}

SCSS folder/block.scss

.sui-x-block {

    // Include without prefix for default modifier
    @include suiMyModifiersMixin();

    // Loop over media query modifiers to generate 
    // your modifiers for each breakpoints
    @each $breakpoint in $sui-breakpoint-modifiers {
      @include suiMediaMin(nth($breakpoint, 1)) {
        @include suiMyModifiersMixin(nth($breakpoint, 2));
      }
    }
}

Pixel vs REM

For better accessibility and better integration for all devices we use rem (or em, or percent) and never pixels for all sizes.

To use rem with simplicity, there is a rem() function loaded into the project that convert a pixel value into rem.

// Bad
.block {
    font-size: 12px;
    border: 1px solid rgba(0, 0, 0, .1);
    padding: 10px 20px;
    max-width: 300px;    
}

// Good
.block {
    font-size: rem(12);
    border: rem(1) solid rgba(0, 0, 0, .1);
    padding: rem(10) rem(20);
    max-width: rem(300);    
}

Sizes abbreviations

To express some sizes in your modifier classes you can use the following abbreviations.

Abbr Size
xxs Extra extra small
xs Extra small
sm Small
ms Medium small
md Medium
ml Medium large
lg Large
xl Extra large
xxl Extra extra large