EvoToolkit - v1.2.1

Overview

The Brand Toolkit is a pattern library which documents EvoToolkit, a collection of user interface components build on top of our EvoCSS framework.

It acts as a central resource for developers working on internal systems who require ready-made, reusable UI components which they can easily drop into their projects.

The brand toolkit also documents undecorated patterns belonging to EvoCSS, aswell as a number of helpful patterns. It's split up into a number of categories:

  • Objects - These are undecorated design patterns which belong to EvoCSS. You would typically use these as a part of existing components or when building your own.
  • Components - Ready made UI components which you can drop into your project. These represent EvoToolkit, the core of what is documented here.
  • Patterns - A repository of helpful code snippets to help save time and enforce best practices.
  • Utilities - High-specificity, very explicit selectors. Typically small, single use helper classes.

Why

Having a collection of ready-made UI components and patterns provides a number of advantages when working on projects:

  1. It saves time because you don't have to create the component from scratch.
  2. Because all developers are using pre-built components, it improves design consistancy across all of our systems, which is better for usability than having a new interface for each system.
  3. Each component has been fully tested and has good cross-browser compatibility.

For a more thorough breakdown of what makes pattern libraries great, be sure to read How to create a pattern library and why you should bother.

Using EvoToolkit

There are a few different ways to use EvoToolkit, depending on your project.

New Projects

If you're working on a new project where you have the opportunity to implement a build system, with nodeJS installed, run npm init in the console to create a new node project and generate a package.json file.

Once set up, in the console, install EvoToolkit as a npm dependency using:

npm install evotoolkit --save

For EvoToolkit's SASS, copy node_modules/evotoolkit/sample.main.scss to your project directory, rename the file to `main.scss` and edit each @import path so it correctly links to each respective file in node_modules.

For EvoToolkit's JavaScript, copy node_modules/evotoolkit/sample.main.js to your project directory, rename to `main.js`, then edit each import path so it also correctly links to each respective file in node_modules.

Then it's just a matter of compiling the SASS into CSS, and building the JavaScript modules using Browserify. These can be done in a variety of ways.

You can do so through third party build systems such as Gulp or in what is probably the quickest way, you can copy EvoToolkits build system, as per the instructions below.

  1. Run the below command in the console to install the necessary dependencies:

    npm install --save-dev babel-core babel-preset-env babelify browserify node-sass onchange parallelshell rimraf uglify-js

  2. In package.json, replace the scripts object with the one below. This gives you a full suite of build tasks to handle the toolkits SASS and ES6 JavaScript. Make sure to replace the paths to match your project, otherwise you'll get errors.

    "scripts": { "clean": "rimraf dist", "mkdir": "mkdir -p dist", "build:css": "node-sass src/assets/css/main.scss dist/main.min.css --output-style=compressed --precision=8.0", "watch:css": "onchange 'src/assets/css/*.scss' 'src/assets/css/*/**.scss' -- npm run build:css", "build:js": "browserify src/assets/js/main.js -t [ babelify ] | uglifyjs -o dist/main.min.js", "watch:js": "onchange 'src/assets/js/*.js' 'src/assets/js/*/**.js' -- npm run build:js", "watch": "parallelshell 'npm run watch:css' 'npm run watch:js'", "build": "npm run clean && npm run mkdir && npm run build:css && npm run build:js" }, "babel": { "presets": [ "env" ] }

  3. In the console, it's then just a matter of running npm run build to compile the SASS and JavaScript into a dist directory. You can also run npm run watch to have the tasks automatically run when files are changed.

This basic build system will generate a compiled main.min.css and a main.min.js into a dist directory, which you may change as you wish to fit the directory structure of your project. All you then need to do is include these in your HTML:

CSS

Place in the head element.

<link rel="stylesheet" type="text/css" href="/dist/main.min.css" />

JavaScript

Place just before the closing body tag.

<script src="/dist/main.min.js"></script>

Existing Projects

With existing projects where it may not be possible to implement any kind of build system, you can use EvoToolkit by including its compiled CSS and JavaScript directly in your project.

To do this, copy/paste the contents of https://toolkit.evolutionfunding.com/source/evotoolkit.min.css into your own CSS file and https://toolkit.evolutionfunding.com/source/evotoolkit.min.js into your JavaScript.

You can also include EvoTookit CSS & JS directly through a style and script tag as per the below snippet. Though make sure to replace the version numbers with the actual latest version, which can be found under the 'releases' tab of its Github repository. This is to prevent your code from being changed post release as EvoToolkit is developed.

CSS

Place in the head element.

<link rel="stylesheet" type="text/css" href="https://toolkit.evolutionfunding.com/source/evotoolkit.X.X.X.min.css" />

JavaScript

Place just before the closing body tag.

<script src="https://toolkit.evolutionfunding.com/source/evotoolkit.X.X.X.min.js"></script>

Installing Icons

Some components require SVG icons as a part of their design, so we need to make these available in our HTML. Copy the below snippet into your page, placing it just after the opening body tag.

This is the root svg element which contains our icon system. When a component requires an icon, its symbol will be included so it's just a matter of copying it into the svg and then everything should just work.

For more information on this approach, see here and then here.

Contributing

The more reusable components EvoToolkit contains, the more useful it will be, so if you have an idea then feel free to open a pull request in the EvoToolkit repo.

If that gets accepted, it's then just a matter of adding its documentation to this pattern library, which is contained in the EvoToolkitLibrary repo.