Styleguide
© 2020 All rights reserved.

MAGIS UI Styleguide

Introduction

Welcome to the styleguide.

It provides base styles and all the HTML (HBS) / CSS (SCSS) components used in the website.

A styleguide fosters and offers many advantages :

  • consistency and logic in visual identity, leading to a better UX;
  • fast and easy component testing and prototyping;
  • better and more methodical workflow with easier modular components design and faster view assembly;
  • extensible and scalable as much as you want, for improved functionalities or new views;
  • common system vocabulary and basis definition, facilitating communication to all the actors, team members as well as clients;
  • facilitate the arrival of new designers and developers in the project.

The styles use a customised Bootstrap4 theme to do most of the heavy lifting. The Bootstrap4 CSS is then cascaded through further style rules to enhance and increase the amount of elements, as well as bring them further inline with the brand

Links to the examples of all interactive Pages, Blocks, and Widgets can be found the Sidebar.

Guidelines

Use the technique of Mobile First to create the components/widgets and pages.

Always start with the classes relates do the smaller screens, Example

Correct: .col-12.col-md-6

Incorrect: .col-md-6.col-xs-12 .col-xs-12.col-lg-6.col-md-4

Avoid mixing elements with grid classes and other component classes

Start using elements already created on bootstrap instead create new ones

Use the grid classes to orders and change the orders of the elements, but avoid too many changes in the same page.

Naming Convention

This project uses SUIT CSS with camelCased naming pattern.

SUIT CSS relies on structured class names and meaningful hyphens (i.e., not using hyphens merely to separate words).

This helps to work around the current limits of applying CSS to the DOM (i.e., the lack of style encapsulation), and to better communicate the relationships between classes.

General Formatting

One of the simplest ways of writing readable and maintainable code is using proper, consistent formatting. For all CSS, use:

  • four (4) space indents or tabs with distance set to 4 spaces;
  • include a single space before the opening brace of a ruleset;
  • for color hex codes, always use 6 values. e.g. #ffffff;
  • use double quotes (no single quotes) consistently e.g. content: “”;
  • don’t specify units for zero values eg margin: 0;
  • include final semicolon in a rule set;
  • Separate each ruleset by a blank line and separate each section by 3 blank lines;
  • Never use ID’s in CSS. IDs carry with them a specificity that is too large, causing bloated CSS.

This results in our code appearing identical across platforms.

Add CSS through external files, minimizing the number of files, if possible. It should always be in the "head" of the document. Use the "link" tag to include, never the @import. Don’t include styles inline in the document, either in a style tag or on the elements. It’s harder to track down style rules.

!important

The general rule for !important tags is that they should never be used, unless for utility classes where the rule will never change. Don’t use !important tags to trump specificity. If needed for hot-fixes, include all CSS in the _shame.scss partial and refactor the right way when time permits.

UI Colors

Source: src/global/scss/_colours.scss

Black
Color: #000000
Var: $black
White
Color: #ffffff
Var: $white

Validation Colours

Source: src/global/scss/_colours.scss

Red Error
Color: #DB0000
Var: $red-error
Green Success
Color: #00693c
Var: $green-success

Typography

Source: src/global/scss/elements/_type.scss

Typography and font styles used in the project

This project uses Google Fonts

Typefaces

Source: src/global/scss/elements/_type.scss

This project uses Google Fonts. Default font is Open Sans. Here are some examples on how to use it:

aAzZ
400
Weight: Base Font Normal
Sass var: 'Open Sans', sans-serif
aAzZ
600
Weight: Base Font Semi Bold
Sass var: 'Open Sans', sans-serif
aAzZ
900
Weight: Base Font Bold
Sass var: 'Open Sans', sans-serif

Headings

Source: src/global/scss/elements/_type.scss

Heading styles responsive

Heading 1 text

Size - Desktop:36px, Mobile:36px, class:"h1"

Heading 2 text

Size - Desktop:32px, Mobile:32px, class:"h2"

Heading 3 text

Size - Desktop:28px, Mobile:28px, class:"h3"

Heading 4 text

Size - Desktop:24px, Mobile:24px, class:"h4"
Heading 5 text
Size - Desktop:20px, Mobile:20px, class:"h5"
Heading 6 text
Size - Desktop:16px, Mobile:16px, class:"h6"

Icons

Source: src/global/scss/elements/_icons.scss

This icons are generated using Icomoon app. SVG files are stored within "/src/global/svgs folder"

Here are some examples:

.icon-phone
.icon-youtube
.icon-twitter
.icon-vimeo
.icon-tick-o
.icon-tick
.icon-map
.icon-pdf
.icon-facebook
.icon-heart
.icon-heart-o
.icon-close
.icon-plus
.icon-ellipsis
.icon-search
.icon-chevron-up
.icon-chevron-down
.icon-chevron-left
.icon-chevron-right
.icon-menu
.icon-edit
.icon-attachment

Forms

Source: src/global/scss/elements/_forms.scss

Form, input elements, radio buttons, checkboxes, and validation styles

We'll never share your email with anyone else.
Field is required.

Field is required.

Please select an option.

Validation classes will be added using a js validation library. Add .has-error to the form-group or form-check The error message appears before the .form-group or .form-check closing tag in a div with .error-message

Node-kss

This styleguide is powered by node-kss along with custom property names when parsing KSS comments.
The scss comments are processed via node-kss and parsed into a json file - ./src/models/cssStyleGuide.json, which is then injected into the styleguide page and used as modal to feed the handlebars template.
It currently doesn't support OOTB node-kss templating thus needs to be used carefully.
There are custom handlebars helpers('./src/helpers/sg*.js') in place to support the custom KSS properties.