NIBC

Get started on how to use and implement the brandplatform in your system. Read on about what principles are used to create the styling of the components and pages.

Assets
Comments
Javascript
Markup
Principles
Styling
Versioning

Build

There are two ways to make use of the CSS and JavaScript created for this brandplatform:

using the latest build
using a build by version

Latest build

This build always links towards the most recent and updated released version of the brandplatform.

https://cdn.brandplatform.be/nibc/releases/latest/...

Build by version

This refers to an older build, based on the given version number. In order to use a more updated version, you have to replace the version number 0.0.1 by another one.

https://cdn.brandplatform.be/nibc/releases/0.0.1/...

Package.zip

We offer a package.zip that contains all the assets needed to by the styleguide: CSS, Javascript, Images & fonts. Use this to easily download all the assets and host them on your own server.

https://cdn.brandplatform.be/nibc/releases/latest/package.zip

CSS

This is the link to the stylesheet of the latest release. Replacing latest by a version number lets you use an older version of the build. Copy and paste this link of the stylsheet within your <head> tag of your HTML page to apply the styling.

<link rel="stylesheet" href="https://cdn.brandplatform.be/nibc/releases/latest/css/general.min.css">

JavaScript

This is the link to the script file of the latest release Load the JavaScript files just before closing the <body> tag. This is done so that your markup is completly loaded and rendered before you start adding interactions or other functions.

<script src="https://cdn.brandplatform.be/nibc/releases/latest/js/general.min.js"></script>

Intro

Commenting or documenting your code is very important so everyone know what kind of wisdom you have applied to the brandplatform. Sharing you knowledige is awesome!

Snippets

Nunjucks

Section:

{# ========================================================================= #}
{# :: Default #}
{# ========================================================================= #}

Comment:
```
{#
  Here goes the comment
#}
```

SCSS

Section

// ============================================================================
// :: Button
// ============================================================================

Multiline comment

/**
 * This is a mulitline comment within CSS, used when we have more than one line
 * to comments, ususally after more or less 80 characters we create a new line
 * to keep it readable :D nobody likes looooooooooooooooong lines of comments
 */

One line comment
```
// one line comment in CSS
```

JavaScript

Section, class or standalone function

/**
 * Imports, Class, Function
 * Here I am saying what the class or function does
 * ============================================================================
 */

Section within class

/* ======================================================================= *
 * Inits, helpers or handlers
 * ======================================================================= */

Function within class

/**
 * Here I am explaining what this function does within
 * the class
 * ------------------------------------------------------
 */

Multiline comment

/**
 * This is a multineline comment within JavaScript. It is actually the same
 * as in CSS!
 */

One line comment

// one line comment in JavaScript, same as in CSS

When to comment?

Comments say why something is being done this way, not what is being done:

Document hacky code:

If you find a tricky solution for an issue, be sure to describe how you fixed it or include a URL to the fix.
Document clever code:

If you find an ingenius, but non-obvious way to do something, be sure to share your knowledge and describe what and why something is happening.
Document magic numbers:

When you have done a brilliant calculation through the use of magic numbers, make it easy to find and understand when they break or where they com from.
Document related styles:

Each and every component can work independetly from each other, but some components rely on one another or manipulate each other, write a comment to note the relationship.
Document obscure properties, values or selectors:

If you find yourself using an unknown or rather new property, share your knowledge with the people who don't know anything about it.
Document PR questions:

If you are doing Code Reviews and let your code get checked by your awesome colleagues and they ask a question. Make sure to provide an answer in the form of a comment.

Intro

We add JavaScript to add interactivity to the components. All is written in ES6, which makes writing and reading JavaScript more clear. This is not yet the standard in webbrowsers, that's why we use Babel as a compiler. This converts our JavaScript to code that the browser can read and execute.

Structure

Within the folder src/js/ you can find the JavaScript setup. Each styleguide is represented by a folder with the same name. When creating the JavaScript for a new styleguide, the same structure should be kept.

brandplatform:

Contains all the JavaScript related to the functionalities of the brandplatform.
styleguides:

Contains the JavaScript from each styleguide seperated from each other. But this does not mean one styleguide cannot each the functions of another.
- general:
  
  Represents the JavaScript of the general styleguide
- vendors:
  
  Contains all minified JavaScript files from vendors or other libraries
- general.js:
  
  The starter file of the general styleguide which should contain the intialisation of the different components

Styleguide

constants:

Contains global values or data that do no change and are used within multiple components
extends

Classes used to contain reusable functionality like Toggle. These classes are used in the modules folder to get inherited from.
managers:

Classes, mostly singletons, used to manage certain tasks.
modules:

Classes, representing the different components within a styleguide like collapsables.
utils:

Functions that gets parameters passed and return a modification based on the passed parameters, simple tasks that are not linked to a certain component.

Component

When defining a component within the modules folder we try to maintain a certain structure:

Each component is a folder containing more parts of that component, each is its own class
The main file within the component folder is defined as index.js and is executed when the component is imported
Everything is class based within these files
Functionality of a certain part is placed in its corresponding file

For example, when we have a collapsable component, we create the folder collapse within the modules folder.

index.js

This contains the main content of the component, where everything gets initialised. When the component is imported, this is the first file to get executed. It initialises the Header and the Content of the collapsable and manages the communication between the two classes. It will execute methods that affect the entire component.
Header.js

Contains the functionality that is purely linked to only the Header part of the collapse: detecting a click, triggering a callback. It will only execute classes that affect this part of the component and trigger callbacks to the parent if necessary.
Content.js

Contains the functioanlity that is purely linked to only the Content pat of the collapse: calculation the height of the content and toggling it when it receives a command from the parent class in index.js. It will only execute classes that affect this part of the component and trigger callbacks to the parent if necessary.

Nunjucks

To get the most functionality and structure out of the markup or HTML, we use Nunjucks. The entire markup is build and renderd using the templating engine, which is based on JavaScript. It allows the use of conditional statements, loop, variables, includes, imports, ... .

Structure

The markup is located within the src/templates folder. There you can find how the brandplatform is build up and how we define components per styleguide.

brandplatform:

Contains all the markup for rendering the brandplatform, this can be seen as the core or the engine. Making adjustments in here will affect the entire brandplatform.
changelog:

Contains a collection of markdown files, each representing a version's log.
manual:

Contains a collection of markdown files, used to build up the user manual that your are reading right now!
styleguides:

Contains the folders representing the different styleguides. Standard there is just one styleguide "general".

Styleguide

Each styleguide within the src/templates/styleguides folder has the same structure and should not deviate from it because the server makes use of the structure do create the content of the brandplatform.

atoms:

Contains all components that fall under the atoms category
molecules:

Contains all components that fall under the molecules category
organisms:

Contains all components that fall under the organisms category
layouts:

Contains the different structure used to style the relationship between components within a page
quarks:

Contains the visualisation of colors, typography and icons
pages:

Contains the different pages listed, this can be done through files or folders representing a group of pages

Component

Intro

Each component can be seen as a folder, which contains several files. Each file has its own role within the component and this structure should be kept when creating a component. When creating a component you do not have to create each file yourself, we provide certain scripts to create the files and its structures for you.

Create

Open up your terminal or console and use the command to create a component: gulp add [--styleguide general] [--atoms button]

[--styleguide general]:

This is optional, when creating a component and this is left out it is added to the general styleguide. This can be replaced by another styleguide like marketing: --styleguide marketing. If this styleguide does not yet exist, it will create the folder for you.
[--atoms button]:

is required, when creating a component you can define in which type it falls under. Other types can be used by replacing --atoms by --molecules, --organisms or --layout. The name of the component is appended at the end and can be anything, but avoid the use of the same name within the same type.

Other examples:

gulp add --atoms button
gulp add --molecules button
gulp add --organisms button
gulp add --layouts grid
gulp add --styleguide general --atoms button
gulp add --styleguide marketing --molecules button
gulp add --styleguide portal --organisms button
gulp add --styleguide awesome --layout grid

Structure

[component-name]-page.njk:

Represents the page of the component. Each block has to contain a certain type of content
- info:
  
  General information about the component, in a markdown format
- Modifiers:
  
  The modifiers classes listed underneath each other in a markdown format
- States:
  
  The states classes listed underneath each other in a markdown format
[component-name]-macros.njk:

Contains the actual code of the component split up in different macro's. Here all the imports from other components are used and defined on top of the file.
[component-name]-usage.md:

Contains text, images, lists used to document the components usage, all done in a markdown format
_[component-name]-default.njk:

Contains an import of the macros file where the macro is executed and given parameters

Settings

component

Within each variation of a component like _button-default.njk is a section place where you can define the settings of the component. This is done within the params object.
- isFullWidth:
  
  Define the if the component is represented within a container or over the entire viewport true or false. This is interesting when you for example create a header or a footer which need the entire viewport width.
- styleVendors:
  
  Stylesheet vendors containing only css, these will be placed before loading your own brandplatform stylesheets within he . When using the sandbox there values are used as the vendors.
- scriptVendors:
  
  Script files containing only js, these will be placed before loading your own script files, right before closing the . When using the sandbox there values are used as the vendors.
page

Within your page Nunjucks file there are pageParams to be defined. This is an object where settings related to the page are placed.
- bodyClass:
  
  Classes to be added to the of a page.
- styleVendors:
  
  Stylesheet vendors containing only css, these will be placed before loading your own brandplatform stylesheets within he .
- scriptVendors:
  
  Script files containing only js, these will be placed before loading your own script files, right before closing the .

Intro

When creating the markup of a page it is important that the classes make the component readable and understandable. Someone who does not know anything about the project can know what a component is, what it does and in what context it is applied without looking at the styling.

In order to achieve such a dream we follow certain principles to markup a page and eventually style it.

Atomic design

Atomic design is a methodology for creating design systems by Brad Frost. In short you start dividing your pages in different type of components. You divide these components based on their usage, repeatability, scale and structure.

Atoms:

The most basic buildings blocks of your design system like a button
Molecules:

A repeatable stand alone block component, made up of several atoms in a certain context like a newsletter subscription
Organisms:

A big section of the website, made up of several molecules, which appear only once on a page like a header
Templates:

Templates consist mostly of groups of organisms to form the pages. These contain placeholder content
Pages:

Pages are the instances of templates where the placeholder content is replaced by content that the user will see homepage

BEM (Block - Element - Modifier)

BEM is a naming convetion to describe and link classes in HTML and CSS. It improves the readability and helps unfamiliar developers understand what a component does. We define which classes are responsible for what and how they depend on one another.

Block:

The root or the top-level abstraction of a component like .btn
Element:

The child elements that are placed inside the Block and are denoted by __ (two underscores) following the name of the child like .btn__icon
Modifier:

Classes that modify or adjust the Block and its children. This is shown by appending -- (two hypen) to the name of the block or the child-element like .btn--dark or .btn__icon--dark

BEMIT

By further expanding the BEM naming convention we have BEMIT by Harry Roberts. BEM tells us how classes are related to each other, but they don't show how things behave. We don't add any other types but we instead use namespaces that tell developers what kind of job a component has. Prefixing the components tell a developer so much more!

a-:

Define a component as an atom
m-:

Define a component as a molecule
o-:

Define a component as an organism
l-:

Define a layout to create structure
u-:

Define a utility which contains one styling property and is not tied to any specific UI
s-:

Define a new styling context or scope. Used to overwrite libraries or third party styling
is- or has-:

Indicate state or condition, show that a DOM has a temporary or optional style applied
js-:

Indicate that DOM has JavaSript linked to it

Intro

For styling the UI we make use of CSS. To get more functionality and structure out of the CSS we make use of SASS/SCSS. In general, this is a diry language, if not maintained. It is up to the developers to keep it clean and documented.

Structure

Within the folder src/scss/ you can find the SCSS setup and how we create the styling for the brandplatform and its styleguides. Each styleguide is represented by a folder and a file with the same name.

general:

The general styleguide, where the styling of components, layout and settings is located. If creating multiple stylguides within the brandplatform, this can be seen as the basis. When creating a new styleguide, this structure must be inherited. This folder and has a file that imports all the components and makes sure that all the styling can be used when linking this file in the <head>of your site: general.scss.
brandplatform

The styling related to the look and feel of the brandplatform itself. When delivering a stylguide, this should not be linked within the <head> tag. It is only useful for the brandplatform itself. Outside of the folder is a file called brandplatform.scss which is used to import the components and create one CSS file.
_vendors

Folder containing third party or minified libraries used to create certain components like a carousel, to overwrite this property a file must be placed within the corresponding styleguide vendors folder.

Styleguide

Standard there is one styleguide present in the brandplatform: general. If there is need to add more, a new folder carrying the name of the styleguide should be added into src/scss. To make use of the components created within that folder a file containing all the imports should be added as well, carrying the same name, but with the file extension .scss. Each folder contains the same structure to keep everything consistent and familiar:

components:

Contains all the atoms, molecules, organisms and quarks to create the different type of building blocks like a button or header
layout:

Contains the layout needed to create the pages like grid or container
settings:

Contains all the global variables used throughout each component like colors, typography or layout
tools:

Contains helper mixins, functions and extends to make our lives in the wonderfull world of SCSS easier and more enjoyable
utils:

Contains helper classes, not related to any UI, with one specifc role like creating spacing or hiding elements
vendors:

Contains styling used to overwrite third party libraries, this does not contain the minified files
scopes:

Is an optional folder that is likely not to be used within each brandplatform. These are not components, but represent a scope used in a certain context. For example: when the HTML or parts of it gets generated by a third party like Mendix or other plugins. A scope can be defined to style regular HTML tags and overwrite classes.
_shame.scss:

Hacks or dity CSS, which is temporarliy and is only implemented to fix an unsolvable issue

Component

Each component is represented by one file: _button.scss, _grid.scss, ... . The styling of the initial component does not leave this file. The structure within this file should be consistent and similar to each component file within the its folder. Each selector should be nothing more than a simple class, selecting them through tags must only be done within the quarks folder in order to keep the specificity low and avoid the use of !important.

Name of the component

Contains simply comments explaining what the component is and what it contains
Settings

Private or internal variables used within the component, each variable should have a clear name to what it does, comment is if its too complex.
Root

The B** or the **Block when using the BEM principle. In general it is the root of the component, containing the different children.
Elements

The E** or the **Elements when using the BEM principle. These are the children of the root of the component.
Modifiers

The M** or the **Modifiers when using the BEM principle. These are the adjustments or modified versions of the Block or Elements defined above.
States

These are the temporarily states defined on the Block, Elements or Modifiers. As stated before, these should always start with is- or has-.


// ============================================================================
// :: Button
// ============================================================================

// ============================================================================
// :: Settings
// ============================================================================
// ============================================================================
// :: Root
// ============================================================================
.a-button {}
// ============================================================================
// :: Elements
// ============================================================================
.a-button__icon {}
// ============================================================================
// :: Modifiers
// ============================================================================
.a-button--dark {}
.a-button__icon--disabled {}
// ============================================================================
// :: States
// ============================================================================
.a-button {
  &.is-active {}
  &.has-icon {}
}

Sorting

A very important thing, that is just as difficult as naming a component is keeping the code consistent and familiar. This can be done by sorting the CSS properties. Here we sort our properties based on type so that every developer know where the properties are located within a selector. Every group of properties should be seperated by an enter.

Position

position: absolute;
top: 0;
left: 0;
z-index: 10;

Display and box model

display: flex;
justify-content: "space-between";
align-items: "center";
width: 10rem;
height: 10rem;
padding: 1rem;
margin: 1rem;

Text or font

font-family: "awesome";
font-size: $font-size-base;
font-weight: bold;
line-height: $line-height-2x-small;
letter-spacing: 1;
text-align: center;
text-transform: uppercase;

Decorators

color: yellow;
background-color: black;
box-shadow: 0 0 20px rgba(0, 0, 0, 0.08);
border: 1px solid white;
background: url("awesome.png") no-repeat center;
opacity: 1;

Transforms

transform-origin: center;
transform:
    translateX(10px)
    translateY(10px)
    scale(1)
    rotate(10deg)
    skewX(10deg)
    skewY(10deg);

Animations

transition: opacity 0.3s ease-in-out;
animation: awesome 0.3s ease-in-out infinite alternate;

Other

cursor: pointer;
pointer-events: none;
list-style-type: none;

Specificity

This determines which CSS rule is applied by the browsers, based on how the selector is build up. When your CSS-rules don't apply, this means that another selector has higher specificity and will be applied. Based on how one is build up, it is easy to overwrite one. This is the reason why we try to limit our selector by just one simple class. We also avoid the use of !important.

Specificity determines, which CSS rule is applied by the browsers. Specificity is usually the reason why your CSS-rules don't apply to some elements, although you think they should. Every selector has its place in the specificity hierarchy.27 jul. 2007

low specificity:
```
.a-button {}

.l-grid {}
.o-header {}
```

high specificty (avoid this):

.a-button > a:first-child {}

.o-header .o-header__content .m-list .m-list__item:first-child {}

Intro

Whenever a new build is made for the brandplatform. We must make clear what has been added, what has been updated or fixed. We do this by creating a version number with each release. To annotate different versions of the styleguide we make use of semantic versioning.

Types

Patch:

Used when making a backwards-compatible bug fix
Minor:

Used when we add functionality in a backwards-compatible manner
Major:

Used when we make breaking changes

Update

Before updating it is recommended to create a file [new-version-number].md within src/changelog containing a title and a list explaining what has changed. Updating a version of the brandplatform can then be done with the command: npm version [patch || minor || major || <x.x.x>]. A script will, be based on your choice of type, check if you have created this file representing the version update.

There is no file:

If there is no file containing the new version number, it will create one for you. Therefore, it is recommended to create the file beforehand so you don't have to output the same command twice.
There is a file:

You should feel very proud because the script will update without any issues to the new version.

Build

Latest build

Build by version

Package.zip

CSS

JavaScript

Intro

Snippets

Nunjucks

SCSS

JavaScript

When to comment?

Intro

Structure

Styleguide

Component

Nunjucks

Structure

Styleguide

Component

Intro

Create

Structure

Pages

Types

Structure

Settings

Intro

Atomic design

BEM (Block - Element - Modifier)

BEMIT

Intro

Structure

Styleguide

Component

Sorting

Specificity

Intro

Types

Update