GOV.UK elements is three things:

1. an online design guide, explaining how to make your service look consistent with the rest of GOV.UK
2. an example of how to use the code in the GOV.UK template and the GOV.UK frontend toolkit
3. an npm package of the Sass files

The guide can be seen here: http://govuk-elements.herokuapp.com.

To preview the latest relase of govuk-elements-sass: http://govuk-elements-sass-release.herokuapp.com/ This is the most recent tagged version.

It can be used as a base of frontend code.

GOV.UK elements has the GOV.UK frontend toolkit and the GOV.UK template as dependencies.

The toolkit provides Sass variables, functions and mixins, they must be imported before any of the GOV.UK elements Sass files.

Take a look at the top of /public/sass/_govuk-elements.scss to see how the GOV.UK frontend toolkit's Sass files are imported.

Choose the Sass files you need to build on top of those provided by the frontend toolkit.

Ignore the /public/sass/elements-page.scss files, these exist to style the page furniture of GOV.UK elements (for example, the HTML example boxes and colour swatches).

To install the govuk-elements-sass package, use:

`npm install govuk-elements-sass`

This installs the package as well as the packages it depends on to the local /node_modules/ folder.

To import all of the govuk-elements-sass files, first import the _govuk-elements.scss partial.

@import govuk-elements;

If you are not using Rails or Compass, then you will need to define a $path variable in your main application stylesheet.

In public/sass/main.scss there is an example of this:

// Path to assets for use with the file-url function
// in the govuk frontend toolkit's url-helpers partial
$path: "/public/images/";

You can pick and chosoe partials from the govuk-elements-sass package.

The GOV.UK frontend toolkit scss dependencies listed below must be imported first.

// GOV.UK frontend toolkit
// Sass variables, mixins and functions
// https://github.com/alphagov/govuk_frontend_toolkit/tree/master/stylesheets

// Settings (variables)
@import "colours";                                // Colour variables
@import "font_stack";                             // Font family variables
@import "measurements";                           // Widths and gutter variables

// Mixins
@import "conditionals";                           // Media query mixin
@import "device-pixels";                          // Retina image mixin
@import "grid_layout";                            // Basic grid layout mixin
@import "typography";                             // Core bold and heading mixins
@import "shims";                                  // Inline block mixin, clearfix placeholder

// Mixins to generate components (chunks of UI)
@import "design-patterns/alpha-beta";
@import "design-patterns/buttons";

// Functions
// @import "url-helpers";                         // Function to output image-url, or prefixed path (Rails and Compass only)

You can find these at the top of the _govuk_elements.scss partial.

If you're not using the GOV.UK template, you'll also need to uncomment the base partial in _govuk_elements.scss, or create your own.

// @import "elements/base";                       // HTML elements, set by the GOV.UK template

Take a look at this project's Gruntfile.js.

Add the node_modules/govuk_frontend_toolkit and node_modules/govuk-elements-sass directories to the includePaths property of your Sass plugin - if you're using a task runner like Gulp, to reference the location of these files.

- index.html
-- node_modules
    -- govuk-elements-sass
    -- govuk_frontend_toolkit
-- assets
    -- scss
        - main.scss
    -- css
        - main.css

Import _govuk-elements.scss into your main.scss file.

'use strict';

var gulp = require('gulp');
var sass = require('gulp-sass');

var repo_root = __dirname + '/';
var govuk_frontend_toolkit_root =  repo_root + 'node_modules/govuk_frontend_toolkit/stylesheets'; // 1.
var govuk_elements_sass_root =  repo_root + 'node_modules/govuk-elements-sass/public/sass';       // 2.

// Compile scss files to css
gulp.task('styles', function () {
  return gulp.src('./assets/scss/**/*.scss')
    .pipe(sass({includePaths: [
      govuk_frontend_toolkit_root,
      govuk_elements_sass_root
      ]}).on('error', sass.logError))
    .pipe(gulp.dest('./assets/css'));
});

In the example above includePaths uses two paths to resolve the scss @import statements.

1. The location of the directory containing the govuk_frontend_toolkit sass files
2. The location of the directory containing the govuk-elements-sass files

gulp styles

To compile the govuk-elements-sass files.

If you would like to clone the repository and run it locally, you will need Node.js (at least version v0.10.0).

Clone this repository

git clone [email protected]:alphagov/govuk_elements.git

Install the required node modules

npm install

Run the app

npm start

Go to localhost:3000 in your browser.

GOV.UK elements uses govuk-lint, which uses scss-lint as its scss linter.

GOV.UK elements uses standardjs, an opinionated JavaScript linter. All JavaScript files follow its conventions.

Both linters run on CI to ensure that new pull requests are in line with them.

To check the whole codebase, run:

npm test

GOV.UK elements uses Wraith so that regressions can be easily spotted.

This needs to be run from the Wraith directory /tests/wraith and some dependencies need to be installed on the local machine first.

gem install wraith
brew install phantomjs
brew install imagemagick

Take a baseline of the current version. On master run:

wraith history config.yaml

Switch to your feature branch and make changes. On feature branch run:

wraith latest config.yaml

Here are examples of service-specific pattern libraries using GOV.UK elements.

• Rural Payments style guide | Source Code
• Land Registry pattern library | Source Code
• Digital Marketplace frontend toolkit | Source Code

You can find contribution guidelines in CONTRIBUTING.md