Implementation of the Home Office design system for use in projects

HTML components are shipped as nunjucks macro functions for maximal compatability with the GDS prototype kit.

Authenticate with GitHub packages

To use a component inside a nunjucks template, first import the component, then call as a function:

{% from "components/header.html" import header %}
{{ header(title='Frontend toolkit') }}

Include the components in your app's views stack:

app.set('views', [require('@ukhomeoffice/frontend-toolkit').views, '<your app views directory>']);

This will allow simple reference to the components when using them in templates.

If you are not using express, and so cannot make use of its views stack, then you will need to provide a full path when importing components. The easiest way to do this is to expose a componentPath property to your templates.

{% set componentPath = '/path/to/frontend/toolkit/templates/' %}
{% from componentPath + "components/header.html" import header %}
{{ header(title='Frontend toolkit') }}

The following components are available:

• header
• footer

The default css styles are provided as sass files. To include these in a project add the following line to your project's sass:

@import "@ukhomeoffice/frontend-toolkit";

Note: you will need to set the includePaths option in your sass compiler to include your project's local node_modules directory.

The header and footer styling is automatically included with the core styles. For all other components, including the proxies to govuk-frontend components, you will need to import each sass file individually:

@import '@ukhomeoffice/frontend-toolkit/assets/styles/components/breadcrumbs';
@import '@ukhomeoffice/frontend-toolkit/assets/styles/components/error-summary';
@import '@ukhomeoffice/frontend-toolkit/assets/styles/components/phase-banner';

Note: please be aware that the $govuk-font-family variable must be set in order to prevent govuk-frontend components injecting their own 'nta' font-face declarations into your compiled CSS. This is done by default in index.scss and can be overridden. If you choose to bring components directly into your project from govuk-frontend rather than via the proxies provided here, then you must make sure that $govuk-font-family is declared before those includes.

A number of colour variables are defined in sass as shortcuts

• $ho-brand - #8F23B3 (alias $purple)
• $background - #F3F3F3 (alias $light-grey)
• $black - #0B0C0C
• $white - #FFFFFF
• $green - #3D5C00
• $blue - #005EA5 (alias $ho-link)
• $dark-grey - #3B3B3B
• $mid-grey - #DADADA
• $ho-focus - #FFBF47
• $ho-link-visited - #4C2C92
• $ho-link-hover - #2B8CC4 (alias $ho-link-active)
• $ho-link-focus - #005798

This is automatically published to the GitHub packages npm repository using GitHub Actions.

When opening a pull request add a label major, minor or patch (or skip-release) and the version field in package.json will be updated by the pipeline using npm version.

It is published once the pull request is merged if there is no skip-release label on the pull request, the SHA is also tagged with the SemVer value at that point.