EvoToolkit - v2.3.0 (Changelog)

Configuring EvoToolkit

Using variables and helper functions built into the framework, you can override EvoToolkit defaults so it can be tailored towards your project needs. The variables described in this section represent the Settings layer of the ITCSS methodology.

To configure variables, you have 3 options:-

  1. Change them in your page manifest SCSS file to apply to that stylesheet only, which if using EvoToolkit Boilerplate, starts life as sample.page.scss.
  2. Change them in overrides.scss to apploy globally across all stylesheets. This is useful to enable styles which you know are on all pages (Headers, footers etc).
  3. For theming, there is a seperate theme-overrides.scss containing all related variables and settings.

Here's everything you can do:-

  • Enabling Functionality
  • Global Settings
  • Theming

By default, only a barebones EvoToolkit is compiled on npm run build. This encourages an 'enable as required' approach, where only the CSS and JavaScript parts in use are included in the compiled files; keeping them lean and small in filesize.

By default:-

  • SASS - All object, component and utility are imported by default, but won't be enabled unless commented in within the $imports map, which is available in your pages SCSS manifest file (To enable on that page) or overrides.scss (To enable on all pages).
  • JavaScript - Element, object and component logic imports in sample.page.js are commented out. Duplicating this manifest file for every page allows you to only include the JavaScript you need to.

To enable functionality, the first step is to enable the part in $imports. If the part has a JavaScript component, that too must be imported in your JavaScript manifest file.

That's it for JavaScript logic. However, for SASS there are more ways to control what is compiled.

SASS Class Filtering

EvoToolkit parts across the object, component and utility layers are composed of various classes which follow the BEM (Block Element Modifier) methodology. In a typical project, not all of these will be used, so it would be wasteful to include them in the compiled stylesheet.

To prevent this, variables exist in your page manifest file and overrides.scss, which allow you to pick and choose what is compiled:-

Global Filter Variable

What if you only want to use one or two modifier classes from an Evotoolkit part? It would be waste to compile an entire group of classes when you only need a few.

Enter $global-filter. This variable allows you to specify which optional classes should be compiled for a particular part. For example, the box object has lots of spacing modifiers. Rather than compiling them all, using the $global-filter, you can pick and choose what to compile:-

$global-filter: set-filter($global-filter, // Box Object 'o-box--spacing-large', 'o-box--spacing-regular@md', 'o-box--spacing-horizontal' );

With this $global-filter, only these spacing modifiers would be compiled, whilst the others wouldn't. There's no use compiling 20+ classes when you only require 3.

With the global filter, the object, component and utility must first be enabled in $imports for any filtered classes to compile.

Enabling Everything

In settings/_overrides.scss, comment in the $enable-all-classes: true; variable and on build, all SCSS classes will be compiled. This is best used for debugging purposes, where there isn't a need to filter unused CSS classes for performance reasons.

There are high level options which trickle down to multiple parts across the framework:-

Name
Name $container-size
Description
Description

The maximum width of the container object, which together with the layout object and width utilities form a grid system.

Default
Default 1170px
Name
Name $enable-all-classes
Description
Description

Enables all the objects, components and utilities CSS classes which are disabled by default. See 'Class Filters' for more details.

Default
Default false
Name
Name $global-body-color
Description
Description

Sets the colour of the document text.

Default
Default color('very-dark')
Name
Name $global-body-font
Description
Description

The font used for every non-heading text in the framework.

Default
Default 'Roboto', sans-serif
Name
Name $global-body-font-size
Description
Description

The standard px size for every non-heading text in the framework.

Default
Default 16px
Name
Name $global-body-weight
Description
Description

How thick all non-heading text is by default. 300 is quite thin, whilst 700 for example would be essentially bold.

Default
Default 300
Name
Name $global-border-radius
Description
Description

Many components have rounded corners. This determines how round.

Default
Default 5px
Name
Name $global-border-radius-large
Description
Description

A larger variant of global-border-radius which is used for certain components with more rounded corners.

Default
Default 10px
Name
Name $global-filter
Description
Description

Enable individual disabled object, component and utility CSS classes as required by including them in a comma seperated list using the set-filter function. This keeps stylesheets small, containing only CSS in use.

Example
Example
$global-filter: set-filter($global-filter, 'o-box--spacing-small', 'o-box--spacing-regular@md', 'c-badge--small', 'u-width-6/12@sm', 'u-width-grow' );
Name
Name $global-font-path
Description
Description

The directory where custom Moderat and Roboto fonts are located for import in /generic/_typography.scss.

Default
Default ../fonts/
Name
Name $global-header-font
Description
Description

The font used for headings in typography header classes (c-type-alpha, c-type-beta etc).

Default
Default 'moderat', sans-serif
Name
Name $global-header-weight
Description
Description

The thickness used for headings in typography header classes (c-type-alpha, c-type-beta etc).

Default
Default normal
Name
Name $global-line-height
Description
Description

The default line-height value, which is essentially how much space should be between lines.

Default
Default 1.5
Name
Name $global-transition-duration
Description
Description

The transition speed in seconds for any component CSS animations.

Default
Default 0.25s
Name
Name $global-transition-duration-fast
Description
Description

A faster variant of global-transition-duration which is used by certain components with transitions which need to be a little speedier.

Default
Default 0.1s
Name
Name $gutter
Description
Description

The amount of spacing between columns in the grid system.

Default
Default 20px
Name
Name $imports
Description
Description

A global manifest of EvoToolkit objects, components and utility parts. All are disabled by default. To enable, simply comment in as required. If you enable a component (eg: Calendar), and that component requires another part to display correctly (eg: Layout), that part will also be imported, even if it's current still disabled in $imports.

Example
Example
$imports: ( object: ( 'box', // 'container', // 'cover', // 'icon', // 'layout', // 'list-bare', // 'media' ), component: ( // 'badge', // 'box', // 'button', 'calendar', // 'checkbox', // 'expander', // 'inputs', 'modal', 'switch', 'table', 'tabs', 'tooltip', // 'typography' ), utility: ( // 'alignments', // 'breakout', // 'colors', // 'heights', // 'hide', 'spacing', 'widths' ) );
Name
Name $set-breakpoint()
Description
Description

A function allowing you to add or edit breakpoints in $mq-breakpoints, which are used by SASS-MQ to make media queries easier.

Example
Example
@include set-breakpoint(( 'md' : 800px, 'lg4' : 1920px ));
Name
Name $set-spacing()
Description
Description

A function allowing you to add or edit spacing values in $spacing, which are used to programatically generate many spacing oriented classes throughout the framework (o-box--spacing-small, u-margin-bottom-huge etc).

Example
Example
@include set-spacing(( 'large' : 60px, 'small' : 10px ));

EvoToolkit supports theming, so you can easily change the colours used by the framework to suit the needs of your project.

This theming functionality is split between a number of key/value pairs and mixins (getters/setters etc). These can be set in theme-overrides.scss. Here's the run down:-

Colours

The first key/value pair is called $colors, which is simply an archive of colours where the theming system can draw from, so we don't have to remember any hex codes. By default, there is a mixture of Evolution Funding brand colours and other more generic colours to fulfil certain UI roles (success messages, errors etc):-

Greyscale

These are greyscale colours named after their opacity, which allows for easier management. Read Color in Design Systems for a good overview of this approach.

Brand Colours

These are Evolution Funding Brand Colours.

Supplementary Colours

These are original colours which are required to perform various roles in a UI which grayscale and brand colours aren't suited towards.

Theme

The second key/value pair is $theme, where the contents of $color are given user interface oriented roles.

For each $theme colour, a dark and light shade is programatically generated for things like hovers and focus styles.

Setting Colours

If you need to add or edit any colours in $colors or $theme, you can do so using set-color and set-theme.

If required, you can also define how dark or how light $theme shades are with the set-theme-shades tool.

In addition, with set-theme-dark-text-color, any $theme colour names you pass here will have very-light text colour (default: very-dark) when its respective theme utility class is a applied to an element.

@include set-color(( 'green': #00ff00, 'orange': #ffa500 )); @include set-theme(( 'accent': #cccccc, 'info': color('green') )); @include set-theme-shades(( 'info': ( 'dark': 5%, 'light': 23% ) )); @include set-theme-dark-text-color(('accent', 'info'));

Getting Colours

To retrieve colours from either $colors or $theme, you can use the color tool.

.c-my-component { background-color: color('primary'); }

Component Theme Variables

For each component, variable exists where $theme colors are assigned roles specific to that component. For example:-

$component-input-border-color: color('medium'); .c-input { border: rem(1px) solid $component-input-border-color; }

These generally shouldn't need to be edited unless you're introducing a lot more theme colours to the mix and would like to add more colour depth to components.

You can find a full list of theme variables in each component's respective documentation pages.

Why?

The reason behind this $colors and $theme split is one of scalability and maintainability.

If we only had $colors, this would make theming a more complicated process. For example, if components had border colours set to $grey and you wanted to change them to red, you would have 2 options:-

  1. Change the value of $grey to red, which would do the job, as the variable would trickle down to the component styles. The problem here is with semantics, in that the variable $grey is now actually red, which is just unnecessary confusion.

OR

  1. Add a new colour called $red and then go through every single component and override their theme variables. A time consuming process.

Because $theme contains colours named according to their role, we can assign them any colour and have it still make sense semantically. And because these $theme colours are the ones already referenced in the component styles, we don't have to go through and edit any component theme variables at all.