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 Widgets and Pages 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.

JELD-WEN AL UI Colors

Source: src/global/scss/_colors.scss

Notifications Colours

Source: src/global/scss/_colors.scss

Grey Colours

Source: src/global/scss/_colors.scss

Grid

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

Buttons

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

Select

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

Forms

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

Forms Standard

Pagination

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

Badges

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

Icons

Source: src/global/scss/fonts/araIcons/_classes.scss

Icon font: 'jeld-wen-al-icons'

Technical details

This project uses - Metalsmith, Handlebars, Gulp, ES2015(latest), Plop.js, Webpack3, Bootstrap4, sass and postcss.

Features

This project uses a number of great software (in the words of their creators):

• - Gulp - a task automation tool.
• - Plop - Plop is a little tool that saves you time and helps your team build new files with consistency.
• - Browsersync - time-saving synchronised browser testing, keep multiple browsers & devices in sync when editing files.
• - EditorConfig - a config file for maintaining consistent coding styles.

Assets

• svgo - a Node.js module for optimizing SVG vector graphics files.
• svg-sprite - a Node.js module for takes a bunch of SVG files, optimizes them and bakes them into SVG sprites.
• Favicons - a Node.js module for generating favicons and their associated files.
• imagemin - a Node.js module for minify images seamlessly.
• assets-manager - a Node.js module for transfer the required files from your registry distributions to the target.

JavaScript

• Babel - a JavaScript compiler for es5 to es6/7.
• Webpack - a bundler for JavaScript.
• ESLint - the pluggable linting utility for JavaScript and JSX (with preconfigured ruleset by Google.
• UglifyJS – A JavaScript parser, minifier, compressor or beautifier toolkit.

Styles

• Sass - CSS with superpowers.
• PostCSS - a tool for transforming styles with JS plugins.
• Autoprefixer - adding vendor prefixes by the rules of Can I Use.
• csso - a CSS minifier with structural optimizations.
• Stylelint - a mighty, modern CSS linter (with preconfigured ruleset by Hugo Giraudel).

HTML

• Metalsmith - a simple, pluggable static site generator.
• handlebars - a javascript template engine.
• handlebars-layouts - a handlebars helpers which implement layout blocks.
• HTMLHint - a Static Code Analysis Tool for HTML.

Directory Structure

The src directory contains your entire application code, including CSS, JavaScript, HTML.

The rest of the folders and files only exist to make your life easier, and should not need to be touched.

Below you can find full details about significant files and folders.

├── README.md                           # Readme file
├── .babelrc                            # Babel config file
├── .gitignore                          # Git ignore rules
├── .htmlhintrc                         # Settings for HTMLHint
├── .stylelintrc                        # Settings for stylelint
├── .accessibilityrc                    # Settings for access-sniff(accessibility checker)
├── postcss.config.js                   # Post-css config for scss files
├── plopfile.js                         # The Plop scaffolding tool configuration
├── config.js                           # Config for build tools
├── kss-config.json                     # Kss-node configuration file
├── metalsmith.js                       # Metalsmith config - used to compile HB templates to html
├── package.json                        # Dependencies for node.js
├── plopfile.js                         # The Plop scaffolding tool configuration
├── /plop-templates/                    # Plop templates
├── /build-scripts/                     # Build tooling, scripts and utility helpers
├── /public/                            # Build static html and assets for development
├── /webpack/                           # Webpack config for dev and prod env
├── /production/                        # Minified, optimized and compiled files
│   ├── /assets/                        # Assets folder
│   │   ├── /css/                       # CSS files
│   │   ├── /js/                        # JS files
│   │   ├── /fonts/                     # Fonts folder
│   │   ├── /images/                    # Images folder
│   │   ├── /svgs/                      # Svg files
│   │   └── /favicon/                   # Browserconfig.xml, manifest and favicon files compiled for supported devices.
│   └── *.html                          # Rendered and compiled HTML files for integration.
└── /src/                               # Development source directory.
    ├── /global/                        # Global project assets.
    │   ├── /assets/                    # Static assets files copy to dist ex. sketch files.
    │   ├── /data/                      # Metadata associated with the site.
    │   ├── /favicon/                   # Favicon image transparent png file(500px x 50px).
    │   ├── /fonts/                     # Font files.
    │   ├── /helpers/                   # Global handlebars helpers.
    │   ├── /images/                    # Uncompressed image files.
    │   ├── /js/                        # Javascript source.
    │   ├── /layouts/                   # Metalsmith handlebars layout templates for pages.
    │   ├── /models/                    # Global json models.
    │   ├── /partials/                  # Global partials used in layouts.
    │   ├── /scss/                      # Global styles for the project includes Bootstrap.
    │   ├── /sprite/                    # Svg files to be converted into an svg-sprite.
    │   ├── /svelte/                    # Svelte portable components that are compiled into javascript.
    │   └── /svgs/                      # Uncompressed svg files.
    └── /views/                         # Styleguide pages, for widgets, blocks and templates.
        ├── styleguide.hbs              # Main index page for the project styleguide.
        ├── /blocks/                    # Blocks folder that contains all the blocks in the project.
        │   └── /someBlock/             # Individual block folder that contains required files.
        │       ├── index.hbs           # Block's styleguide page.
		│	    ├── js
        │       │   └── someBlock.js   # Javascript class for block.
        │       ├── model
        │       │   └── someBlock.json  # Block's model data to be passed.
        │       └── scss
        │           └── _someBlock.scss # Block specific styles.
        ├── /pages/                     # Pages folder that contains all the page templates in the project.
        │   └── /somePage/              # Individual page folder that contains required files.
        │       ├── index.hbs           # Page's styleguide page.
        │       ├── model
        │       │   └── somePage.json   # Page specific model data to help over-ride block/widget default data.
        │       └── scss
        │           └── _somePage.scss  # Page specific styles.
        └── widgets                     # Widgets folder that contains all the page templates in the project.
            └── someWidget              # Individual widget folder that contains required files.
                ├── index.hbs           # Widgets's styleguide page.
                ├── js                  
                │   └── someWidget.js   # Javascript class for widget.
                ├── model
                │   └── someWidget.json # Widget specific default model data.
                ├── scss
                │   └── _someWidget.scss # Widget specific styles.
                └── tmpl
                    └── someWidget.hbs  # Widget's Handler partial
		

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.