Sass linting is used in the UI Toolkit to maintain good and unified coding standards. The same sass lint config should be used across all our products and can be installed via NPM here.

BEM is being used throughout as the naming convention. For more info about bem see here.

Media queries in EM

Breakpoints are defined in EMs to cater cross browser for users who zoom in or change their font size settings. There are various articles explaining conclusions to these experiments such as zellwk.com and cloudfour.com.

Fonts and icons in REM

Fonts and icons are defined in REMs for users who change their base font size settings.

To make it easier, a helper function is available to convert pixel values to REMs by passing a pixel value in the rem function like so px-to-rem(24);

Font spacing in EM

To keep the spacing relative to the size of the font, the EM unit is being used. If the font size changes, the spacing around the text doesn't need to be altered.

Note only padding is used for vertical spacing.

Everything else in PX or %

Widths and spacing should not be altered based on font size. For example if the text increases, the horizontal spacing and widths of content boxes and images should not be altered since the screen width remains the same.

If the font increases it should flow vertically therefore the height of a text container should never be rigidly set to allow for text changes (a min-height could be used).

0. Utilities Required

Standalone functions and mixins or external imports

The utilities are made up of functions and mixins that are all utilised throughout the UI Toolkit SCSS from the very beginning so they need to be included first.

Note: no CSS will be compiled from the utilities files, so it will not add to the size of your built CSS file to include all the files.

Utilities SCSS imports

To include all utilities: @import 'path/to/file/0-utilities/_all';

To include an individual utility file: @import 'path/to/file/0-utilities/_utilities.colours';

---

1. Settings Required

Global variables config switches

The option is available to reasign variables in your own SCSS, so it may be useful to include all the settings files individually so that you can override/reasign directly after each file import. The main settings file has all the individual file imports, so the order of importing should be followed from there.

Note: no CSS will be compiled from the settings files, so it will not add to the size of your built CSS file to include all the files.

Settings SCSS imports

To include all settings: @import 'path/to/file/1-settings/_all';

To include an individual setting file: @import 'path/to/file/1-settings/_settings.palette';

---

2. Tools Required

Functions and mixins

The tools are helpers made up of mixins, placeholders and keyframe animations that are all utilised throughout the UI Toolkit SCSS and also available for you to use. See here for available mixins.

Note: no CSS will be compiled from the tools files, so it will not add to the size of your built CSS file to include all the files.

Tools SCSS imports

To include all tools: @import 'path/to/file/2-tools/_all';

To include an individual tools file: @import 'path/to/file/2-tools/_tools.headings';

---

3. Generic Recommended

Ground-zero styles

Includes a normalize file which will reset base elements.

Generic SCSS imports

To include all generic: @import 'path/to/file/3-generic/_all';

To include an individual generic file: @import 'path/to/file/3-generic/_generic.normalize';

---

3. Elements Recommended

Styling for bare HTML elements (with some helper classes)

Includes all the base styles for the main elements.

The elements are loosely based on ITCSS, however there are also some helper classes to another element look like that element eg. an <a> also has the class .a available to use which the styles are applied to both. Same applies to tables .table, headings .h1, .h2, .h3, .h4, .h5, .h6 and typographical formatting .p, .small etc. see more formatting classes here.

Elements SCSS imports

To include all elements: @import 'path/to/file/4-elements/_all';

To include an individual elements file: @import 'path/to/file/4-elements/_elements.tables';

---

5. Objects

Class-based selectors which define undecorated design patterns eg. layouts.

This folder contains structure and layout styles, eg. grid system, form layout, containers etc. Each file can be imported individually based on the requirements of your project.

Objects SCSS imports

To include all objects: @import 'path/to/file/5-objects/_all';

To include an individual objects file: @import 'path/to/file/5-objects/_objects.grid';

---

6. Components

Specific UI components

This folder contains components that can be imported individually based on the requirements of your project. However there are components such as _components.buttons, _components.icons, _components.lists all the form elements and various others that are commonly used.

Components SCSS imports

To include all components: @import 'path/to/file/6-components/_all';

To include an individual objects file: @import 'path/to/file/6-components/_components.cards';

---

7. Trumps

Utilities and helper classes with ability to override

This folder contains overrides and really useful helpers. Documentation for most of the helper classes can be found here

Trumps SCSS imports

To include all trumps: @import 'path/to/file/7-trumps/_all';

To include an individual trumps file: @import 'path/to/file/7-trumps/_trumps.spacing';