Skip to main content

Migrate from our old frameworks

You should migrate to GOV.UK Frontend if you’re using one of the following old frameworks:

  • GOV.UK Elements
  • GOV.UK Template
  • GOV.UK Frontend Toolkit

We’re no longer updating our old frameworks, and they do not meet the Web Content Accessibility Guidelines (WCAG 2.1 level AA).

After you include GOV.UK Frontend in your project, your service should look and behave the same as before. This means you can migrate one component at a time in your live service.

Your service might be slightly slower until you’ve finished migrating, because your users’ browsers will download CSS and JavaScript from both GOV.UK Frontend and the old frameworks.

You can read about how the GOV.UK Pay team migrated their service.

Audit your service’s components

To help you migrate, you should work with a designer to make a list of the components in your service, and compare it to the components in GOV.UK Frontend.

You can use your list to see where you can replace similar elements in your service with one GOV.UK Frontend component. For example, if you have a range of similar buttons, you might be able to replace them all with the button component.

Choose a template engine

We recommend using a template engine like Nunjucks to abstract each component into a reusable macro (also called a ‘partial’ or ‘template’). You can do this before or during your migration.

Macros will help make your project easier to:

  • migrate, because your project will be organised the same way we organise the GOV.UK Design System
  • update when new versions of GOV.UK Frontend are released

If you’re using Node.js, you can use our Nunjucks macros.

Each component page on the GOV.UK Design System website has example Nunjucks macros and a table of macro options.

Add GOV.UK Frontend to your project

  1. Install GOV.UK Frontend using node package manager (npm).

    Do not install using precompiled files, or you will not be able to turn on ‘compatibility mode’.

  2. Turn on GOV.UK Frontend’s ‘compatibility mode’ so your service continues using the old colours and font until you finish migrating.

  3. Test your application to make sure it looks the same and behaves correctly.

Migrate your pages and components

After you install GOV.UK Frontend, you can either migrate:

  • one page at a time - if your service is small, for example a single service with 10 pages
  • one component at a time - if your service is big or complicated

Migrate one page at a time

We recommend creating a separate page layout based on our page template, so that you can make changes without affecting the pages you have not migrated yet.

You must:

  • include GOV.UK Frontend JavaScript and CSS files below our old frameworks’ JavaScript and CSS files
  • use GOV.UK Frontend markup for all the typography and layout in your service
  • include and initialise GOV.UK Frontend’s JavaScript for all the components that use it

You should also follow our guidance if you extend or modify GOV.UK Frontend components.

Migrate one component at a time

We recommend migrating in the following order:

We do not recommend the reverse order, because if you migrate the page template too early it might:

  • break CSS or JavaScript that relies on your old page template
  • apply layout features that are better applied at the end
  • make it harder to identify and cleanly remove old CSS and JavaScript

You must:

  • include GOV.UK Frontend JavaScript and CSS files below our old frameworks’ JavaScript and CSS files
  • use GOV.UK Frontend markup for all the typography and layout in your service
  • include and initialise GOV.UK Frontend’s JavaScript for all the components that use it

You should also follow our guidance if you extend or modify GOV.UK Frontend components.

To keep your design looking the same as it is now, you might need to add styles that temporarily override GOV.UK Frontend styles. For example, most GOV.UK Frontend components only have a bottom margin, so you might need to add temporary margins to the top, left or right.

Update your custom code

If you’ve created custom code that uses code from either GOV.UK Elements or GOV.UK Frontend Toolkit, you’ll need to:

Remove our old frameworks

Once you’ve completely migrated your service to GOV.UK Frontend, you can remove our old frameworks.

1. Uninstall

Uninstall GOV.UK Frontend Toolkit, GOV.UK Element and GOV.UK Template.

2. Turn off compatibility mode

Turn off ‘compatibility mode’ so your service stops using the old colours and font.

Replace the following old colour variables if you’re using Sass.

Old colour Suggested replacement
bright-red red
grey-1 dark-grey
grey-2 mid-grey
grey-3 light-grey
grey-4 light-grey

You should also remove any temporary overrides you added earlier.

3. Test your updated service

You should check your application looks the same and works correctly, and that it’s using:

You should also use the developer tools in your browser to check that your project:

  • is no longer using files from our old frameworks
  • is downloading only one version of the font
  • does not contain any unused stylesheets or JavaScript