EPIC: Explore rebuilding NHS.UK frontend directly from GOV

[sarawilcox]

A discovery to consider the costs and benefits of building the frontend from GOV.

The service manual team has been asked to consider the following proposal.

Proposal

Currently, nhsuk-frontend is a standalone frontend library that was created based on govuk-frontend using its own HTML, CSS and JavaScript.

By merging the two, we can build nhsuk-frontend directly from GOV.UK by pulling in their entire frontend as a package. This will mean we will not require any of our own code for basic things such as grid system and form fields within nhsuk-frontend.

Services would be using govuk-frontend for general service building, but nhsuk-frontend for our custom components such as care cards.

There would be initial work required to create the new version of nhsuk-frontend, but the work to maintain will be drastically reduced and will improve the overall quality of NHS products.

• Current version of the frontend library is very difficult to maintain
• Building NHS rrontend on top of govuk-frontend will allow us to get all of the govuk changes for free
• We will get their expertise, best practices, user research and coding done
• This will save our time, money and resources
• We will still have the option to build custom components or modify the gov ones slightly to meet our needs
• General upkeep will be much lower than the current frontend
• The service manual will require less information and will be easier to keep up to date
• This follows what HMRC and MOJ are doing

[frankieroberto]

Ooh, interesting idea! I can see some pros and cons, but a discovery would help spell these out.

This would also have an impact on the different implementations (ie ruby, react, python, .net, etc) so might be worth reaching out do those teams as part of the discovery work?

[paulrobertlloyd]

It might be worth reaching out to the team at MOD. They built a design system that is essentially a wrapper around the GOV.UK Design System, and very impressive it is too.

Internal requirements dictated their approach, but what’s interesting is that their Nunjucks macros use the moduk namespace while still outputting govuk-* classes in HTML. That might be an option here where, in most cases, teams could continue using the existing Nunjucks macros, but have govuk-* generated in HTML, thus helping with any transition. The transition story for teams using other frontend templating systems might be trickier, however.

Secondly, as part of the discovery, I’d be interested to see how far you could go by configuring GOV.UK Frontend’s global SCSS settings; there’s a high degree of configurability, and my suspicion is that you could get 90% of the way styling common components by changing these default settings.

[peteryates]

This would also have an impact on the different implementations (ie ruby, react, python, .net, etc) so might be worth reaching out do those teams as part of the discovery work?

From the Ruby side both the components and form builder gems have a brand setting which is intended exactly for this purpose.

My original attempt at supporting the NHS Design System demonstrates how close they were back in early 2020 - only the JavaScript functionality (character counts and appearing fields) didn't work.

[wa-rren-dev]

Hi @sarawilcox, looking forward to seeing how this shakes out based on the conversations we had about it when I was on the service manual!

[Tosin-Balogun]

This is a great development based off the huddle where @Fenwick17 was showing off the possibilities of this approach. I suppose, the benefits are clear in the sense of maintenance and ingesting all the work GOVUK have done.

Hopefully, this investigation also highlights the need for better business structure around these so it can be much clear who is ingesting what and how things go back upstream. So the classic (user needs, business needs, technical needs)

[ahosgood]

When I was at HM Land Registry, I did the same thing and extended GOV.UK Frontend so we could make adjustments and add new components but still get updates from GOV.UK: https://github.com/LandRegistry/hmlr-frontend

[Fenwick17]

I created an initial proof of concept for this which shows a general idea of how it could work.

Not all components have been adapted, but it gives an idea of the flexibility:

• either taking a Gov component directly
• modifying a Gov component to fit the NHS style
• complete custom NHS components.

Very rough proof of concept, but it is handy for demo purposes. Updated to govuk v5.1 and got most of the JavaScript working.

https://github.com/Fenwick17/nhsuk-frontend-gov/

[edwardhorsford]

I agree this is something we should explore. It feels like a pragmatic solution given the limited resources at NHS and the much more frequently updated GOV.UK design system, whilst having such similar designs and aims.

My expectation is that we'd still maintain the NHS Service manual, but that under the hood some things can be govuk or at least sourced from there.

Some questions a spike / discovery might try to address:

• Can it be done?
• What's the likely initial and ongoing effort to maintain?
• What would be the impact to existing service teams / port owners? if there's different approaches, how might each approach impact our users?
• Would we inherit anything we don't want or don't agree with? - and if so, can we override?
• How easily can we add our own components on top? What about modifying the govuk components?
• Would we want to use the govuk- namespace, or could we otherwise easily swap the namespace?

[rowellx68]

https://github.com/rowellx68/spike-govuk-to-nhsuk-transformer

I've created a spike that uses some code transformers and good old string replace to patch the files. This repository pulls the govuk-frontend as a submodule.

The script does the following:

1. copy the files from govuk-frontend into nhsuk-frontend
2. patches any occurrences of govuk with nhsuk. this includes the file paths
3. uses postcss and custom plugins I wrote to patch certain files.

The resulting button looks something like this:

---

I've added a few more components as well as setting up the font-face. Hopefully somebody finds this useful.

[anandamaryon1]

Useful background, GOV.UK state in their vision:

We won’t support custom branding or build an alternate generic brand

https://team-playbook.design-system.service.gov.uk/what-we-do/future-of-the-govuk-design-system/#where-the-gov-uk-design-system-is-heading

[colinrotherham]

Hello all 👋

Just an update on this epic

I've finished a suite of changes to align our code style with GOV.UK Frontend:

• https://github.com/nhsuk/nhsuk-frontend/pull/1120
• https://github.com/nhsuk/nhsuk-frontend/pull/1132

But also to match our JavaScript build tooling in:

• https://github.com/nhsuk/nhsuk-frontend/pull/1135
• https://github.com/nhsuk/nhsuk-frontend/pull/1152

What next?

This paves the way for two moves:

JavaScript imports

Updating our JavaScript to valid ES modules with *.mjs file extensions would let us:

1. Import JavaScript (from GOV.UK Frontend) without conflict
2. Follow Building your own JavaScript components to share code with GOV.UK Frontend

Sass modules

Updating our Stylesheets to Sass modules via ~@import~ @use would similarly let us import GOV.UK Frontend functions and mixins without conflict and lets us rename namespaces where clashes occur

See this work progressing in:

• https://github.com/nhsuk/nhsuk-frontend/pull/1137
• https://github.com/nhsuk/nhsuk-frontend/pull/1154

[LauraJD]

Finding from the service manual survey (Spring 2025): Design system is “noticeably behind” and needs to be updated more frequently: “I guess I see the NHS thing as a bit stale, produced before the merger and not really updated.” AND More alignment with gov.uk design system, some patterns are available on gov.uk but not our version.

[anandamaryon1]

Frontend version 10 is now out, which lays the foundations for more closely following GOV.UK frontend.

Next will be a series of releases to align individual components one-by-one. And following that, switching over as much of our code as possible.