User Manual

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.



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.

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.

We offer a 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.


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="">


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=""></script>



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!



  • Section:

    {# ========================================================================= #}
    {# :: Default #}
    {# ========================================================================= #}
  • Comment:

      Here goes the comment


  • 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


  • 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.



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.


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


  • 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.


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.



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, ... .


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".


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



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.


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


  • [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]

    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



The pages folder has two different ways it can be build up, you can only use one type within the same folder:

  • Files

    A simple collection of Nunjucks files, where each name of the file represents the name of the page

  • Folders

    Represents a group of pages, each folder must a name that defines the category and nested within are the Nunjucks file that are the pages of the styleguide


  • _base:

    Contains the basis of a page like loading stylesheets, scripts, header, navigation, footer, body, main, ... . Every page should only need to inherit this structure. That which every page has the same of should be defined here.

  • _partials:

    Contains folders that carry the name of the pages, each folder has their own Nunjucks files representing the sections of that page. You are basically splitting up your page in sections and placing those sections in different files. These files get included in the actual pages.

  • home.njk, about.njk, contact.njk, ...:

    These are the actual pages where the inheritance, page parameters and inclusion of the partials is defined.


  • 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 .



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


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



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.


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.


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


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 {} }


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;
  • 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;


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 {}



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.


  • 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


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.