Setup guides

Production

This guide explains how to set up your project so you can start using the styles and coded examples in the GOV.UK Design System in production.

If you’ve used GOV.UK Elements, GOV.UK Template or the GOV.UK Frontend Toolkit before, you might also find it useful to read the guide on updating your code.

Include GOV.UK Frontend in your project

To start using GOV.UK styles, components and patterns contained here, you’ll need to include GOV.UK Frontend in your project.

There are 2 ways to include GOV.UK Frontend in your project. You can either install it using node package manager (npm) or include the compiled files in your application.

Option 1: install using npm

We recommend installing GOV.UK Frontend using npm.

Using this option, you will be able to:

  • selectively include the CSS or JavaScript for individual components
  • build your own styles or components based on the palette or typography and spacing mixins
  • customise the build (for example, overriding colours or enabling global styles)
  • use the component Nunjucks templates

Option 2: include compiled files

If your project does not use npm, or if you want to try out GOV.UK Frontend in your project without installing it through npm, you can download and include compiled stylesheets, JavaScript and the asset files.

Using this option, you will be able to include all the CSS and JavaScript of GOV.UK Frontend in your project.

You will not be able to:

  • selectively include the CSS or JavaScript for individual components
  • build your own styles or components based on the palette or typography and spacing mixins
  • customise the build, for example, overriding colours or enabling global styles
  • use the component Nunjucks templates

Start using the GOV.UK page template

You can set up a basic page that is consistent with GOV.UK branding by using the GOV.UK page template.

Styling page elements

The Design System provides CSS classes for styling content, instead of global styles.

The class names follow the Block Element Modifier (BEM) naming convention. This can look a bit daunting at first, but it makes robust code that’s easy to maintain.

Explore the Styles section of the Design System to see what classes are available.

Using components

The components in the Design System are designed to be accessible and responsive - there are 2 ways to implement them in your application.

You can either use HTML or - if you’re using Nunjucks with node.js and you installed GOV.UK Frontend using npm - you can use a Nunjucks Macro.

You can get the code from the HTML or Nunjucks tabs below any examples:

<button type="submit" class="govuk-button">
  Save and continue
</button>
{% from "button/macro.njk" import govukButton %}

{{ govukButton({
  text: "Save and continue"
}) }}

You can configure this component using the Nunjucks macro arguments.

Using Nunjucks macros

A Nunjucks macro is a simple template that generates more complex HTML.

Nunjucks macros save you time by managing repetitive or error-prone tasks, like linking form labels to their controls.

Nunjucks macros also make it easier to keep your application up to date. You can run a command to update component code instead of having to manually update your HTML.

To use Nunjucks macros in your application, you’ll need to setup Nunjucks views to point to the location of GOV.UK Frontend components, which is node_modules/govuk-frontend/components/.

To include a specific component macro in your page template, you need to import the macro.

For example, to use the breadcrumb macro, use the import statement {% from "breadcrumbs/macro.njk" import govukBreadcrumbs %}.

If you’re using Nunjucks macros in production be aware that using html arguments, or ones ending with Html can be a security risk.

There are various way to mitigate against that. One example is described in the Nunjucks documentation.

Get in touch

If you’ve got a question, idea or suggestion share it in #govuk-design-system on cross-government Slack (open in app) or email the Design System team on govuk-design-system-support@digital.cabinet-office.gov.uk