Upgrading UX Forms’ GOV.UK theme

Government Digital Service (GDS) are a government department who, amongst other things, maintain GOV.UK, the UK government’s websites. One of their biggest and most visible achievements is the creation of a government-wide set of standards and styles for how webpages should look. In short, if a department wants to put information online, it must do it using GDS’s style guide.

This is brilliant for users as every site benefits from the extensive user research that GDS continue to invest in their designs as well as providing a consistent and trusted user experience across all departments. It is more tricky for tool providers though as we need to provide ways for our customers to tailor their html and css appropriately. Just letting a form designer pick what colours they want, and maybe upload a logo or two, isn’t going to cut it.

GOV.UK homepage

One of the most powerful features of UX Forms is that it gives customers complete control over the entire html, css and javascript delivered to the browser. This means our forms can implement literally any site’s design, even GDS’s extremely detailed html and css requirements for GOV.UK. In fact, we provide a theme for GOV.UK sites out of the box. As a result a government department can go from nothing to running a live GOV.UK-compatible form in minutes.

Of course, nothing stays still for long — GDS continue to update and evolve their style guide and we last updated our GOV.UK theme back in June 2016. So it is high time we brought our theme up to date. This article will walk through how we did it.


What is a theme?

A theme in UX Forms is nothing more than a zip file. You deploy a zip file to UX Forms and we extract it and serve its contents online. That’s it.

Abridged contents of UX Forms’ GOV.UK theme

A theme can contain anything you want but most commonly it contains javascript, css and images to be used by your form, as well as templates used to generate all of your form’s html.

The image inset left shows the (abridged) contents of our GOV.UK theme. It contains all the images, stylesheets and javascript provided by GDS, as well as a set of mustache templates used by UX Forms to generate the form’s html.

And this is what our theme looked like when used by UX Forms’ Pattern Library form:

UX Forms’ Pattern Library form using our old GOV.UK theme

Theme building

Whilst all you need to give to UX Forms is a zip file, how you create that zip file is entirely down to you.

GDS helpfully publish a frontend toolkit containing images and javascript for use on GOV.UK sites, an elements guide and associated sass files that define what markup should be used, as well as a template containing the GOV.UK header and footer and associated assets. So, to make best use of these assets, we’ve chosen to use gulp in our GOV.UK theme to bundle everything up, process our sass files and create our zip file.


Upgrading to the latest and greatest

We are upgrading from govuk-elements-sass version 1.2.1 to 3.1.2 and from govuk_frontend_toolkit version 4.12.0 to 7.1.0, so we can expect a significant number of changes. There are a few moving parts to this so let’s take them in turn.

Bumping versions

Our dependencies are declared in package.json so it’s just a matter of changing the version numbers for govuk-elements-sass and govuk_frontend_toolkit and re-running npm install.

Our gulp build already pulls in all javascript and images from the govuk_frontend_toolkit so there’s nothing we need to change there.

Then the only thing left to do is to copy all javascript, images and css from GDS’s template artifact into the equivalent folders in our theme. This means we’re sure to have all the dependencies we need.

Using styles

Whilst GDS’s html template references enough css to make that page work, it is missing the rest of their css, e.g. form element styles. So, we also have our own main.scss whose chief role is just to include govuk-elements.scss, and then include a reference to that in our layout.mustache.

It also turns out some css class names have changed, as well as their usage. We’ll get on to these next.

Changing our html

Whilst the overall layout template has changed significantly there are some other, more subtle, changes elsewhere in GDS’s elements guide. We’re not going to list them all here but it is worth highlighting some of the more interesting changes that demonstrate UX Forms’ flexibility.

Radio buttons perhaps were changed most significantly, so let’s take a look at what that meant for our theme.

diff of our theme’s mustache template that renders a radio group’s fields (old on the left, new on the right)

What’s shown above is a comparison of our theme’s mustache template for rendering a radio group’s fieldset. The old version is on the left and the new on the right. We can see that the class name to be used when there’s a validation error has changed, but also the html inside the legend is markedly different. In fact we have an entirely new legend property that has been added to the template and, if present, rendered with its own style.

As this template is used for both radio buttons and checkboxes, it includes another mustache template called widget to render its members. The template used when rendering radio buttons is shown below.

diff of our theme’s mustache template that renders each input in a radio group (old on the left, new on the right)

This template shows perhaps an even more interesting change, in that the order of the input element and its label has been changed. Before, the radio input was rendered inside its accompanying label, and after the upgrade we separate the input-label pair and wrap them in their own div. This sort of change simply cannot be done if you don’t have complete control over the resultant html in your form.


Our upgraded theme in action

UX Forms’ Pattern Library form using our upgraded GOV.UK theme

So here it is, UX Forms’ Pattern Library form running on the latest GDS styles for GOV.UK. Check it out to see the rest of our common widgets rendered using our updated theme.

If you’re interested in the minutiae of every last detail, then the full set of changes is available in our theme’s public repository.


As you can see, even seemingly small changes like this require absolute control over the final html that’s delivered to the browser. To support GOV.UK’s design properly we’ve had to allow all html output, everywhere, to be under your control. Not only does this mean we can fully support GOV.UK’s earlier theme and this upgrade, but we can also be confident of supporting whatever changes GDS make in the future as well as any other style by anybody else. Whether you’re Global Megacorp ‘Я’ Us needing absolute adherance to your centrally managed corporate design language, or a back bedroom startup that’s outsourced your web design, UX Forms can deliver.


Want to know more?

Come have a look around https://uxforms.com, follow UX Forms on twitter, or email us at hello@uxforms.com and see how we can make your forms better, together.

One clap, two clap, three clap, forty?

By clapping more or less, you can signal to us which stories really stand out.