GOV.UK frontend toolkit

You can help us improve the GOV.UK frontend toolkit by completing our 5 minute survey.

A collection of Sass and JavaScript files for using as part of your application's frontend.

This project is not tied to a specific language and is designed to be used as a dependency in as many different languages as needed.

There's a Gemfile and a package.json in this directory, but they are only for running tests and are not an indication that this project prefers Ruby or Node.js.

Installing

Ruby on Rails

We recommend you use the govuk_frontend_toolkit_gem and follow the installation instructions.

Node.js

govuk_frontend_toolkit_npm is an NPM package that can be installed or included in your package.json.

If you are using a build tool that depends on Libsass then you may need to upgrade to a more recent version to use the grid helpers. Minimal compatible versions include node-sass 1.0.0, grunt-sass 0.16.0, gulp-sass 1.2.0 and libsass 3.0.0.

Composer

govuk_frontend_toolkit_composer is an composer package that can be added to your composer.json

Other projects

Using the tagged versions

Each version of the toolkit is tagged with the version number in this format:

v*version number*, for example v4.1.1 for version 4.1.1.

If your dependency management tool allows the use of Git repositories as dependencies, you can point to a version by using its tag.

For example, if you are using bower, you can add the toolkit to your bower.json like so:

"govuk_frontend_toolkit": "git://github.com/alphagov/govuk_frontend_toolkit#v4.1.1" (assuming you want version 4.1.1)

Using git submodules

You can include the toolkit as a [git submodule][https://git-scm.com/book/en/v2/Git-Tools-Submodules].

To add the submodule to your project run the following command substituting the path to a subdirectory in your project's assets directory:

$ git submodule add https://github.com/alphagov/govuk_frontend_toolkit.git ./path/to/assets/govuk_frontend_toolkit

We recommend you use https rather than ssh for submodules as they don't require key exchanges when deploying to remote servers.

If you clone a project with the toolkit submodule installed you will need to initialise the submodule with the following command:

$ git submodule init

To update the toolkit to the latest version you can use:

$ git submodule update

Running tests

Tests for this project use Jasmine for the JavaScript and Ruby's scss and scss-lint to check the stylesheets.

The requirements are Node.js 0.8 or higher and PhantomJS, and Ruby:

bundle install
npm install
npm test

Using the local test runner

The test suite can be run by opening the ./spec/support/LocalTestRunner.html file in a browser for a more detailed trace of errors.

The files for unit tests and any supporting JavaScript should be added to ./spec/manifest.js file.

Usage

At the top of a Sass file in your project you should use an @import rule to include the file for the mixins you require, eg if you want the conditionals and typography mixins you should add:

@import '_conditionals';
@import '_typography';

You may need to include the relative path to the toolkit if it is installed as a submodule:

@import '../toolkit/_conditionals';

If you are compiling Sass from the command-line tool, here are some options we recommend.

In development:

sass --style expanded --line-numbers --load-path [path to]/govuk_frontend_toolkit/stylesheets input.scss output.css

In production:

sass --style compressed --load-path [path to]/govuk_frontend_toolkit/stylesheets input.scss output.css

Documentation

Licence

Released under the MIT Licence, a copy of which can be found in the file LICENCE.

mtsweir/govuk_frontend_toolkit