NHS.UK frontend: the design system behind every NHS service interface

What this codebase is for, and who maintains it

The README states the purpose in one line: NHS.UK frontend contains the code you need to start building user interfaces for NHS websites and services. It is maintained by NHS England, and the README gives the contact routes, an email address, a GitHub issue link and a Slack workspace on the NHS digital service manual. The topics list is narrow and telling, with css, css-framework, frontend-library, html, nhs, nhs-websites, nhsuk and scss. There is no framework here in the React sense. This is the layer of styles, markup patterns and progressive JavaScript that sits under the pages of a public health service, and the primary language of the repository is JavaScript with the styling authored in SCSS. The licence is MIT for the codebase, and the documentation is separately owned by NHS England under the Open Government 3.0 licence, which the README spells out for the sample code included in it.

Two installation routes, and why the choice matters

The quick start gives two ways to start using the library, and the difference is about how much of the build you want to own. The recommended route is using the Node.js package manager, npm, which is documented separately. The alternative is copying the CSS, JavaScript and asset files into your project, which is documented under installing compiled. The copy route is the older style of consuming a design system, and it has an obvious appeal for a team that does not want a Node build step in its deployment pipeline, and an obvious cost, which is that you now have to keep those copied files in step with the upstream releases yourself. The npm route keeps the dependency declared, so upgrades go through your normal dependency tooling, at the cost of a build step and a node_modules footprint in your service. The README is explicit that whichever you pick, you should have a plan to stay up to date with changes, and that the release notes on GitHub document both the technical and the design changes in every release.

The monorepo behind the published package

The root package.json is marked private and describes itself as used only for the development of NHS.UK frontend, with a pointer to packages/nhsuk-frontend/package.json for the published package. That distinction is worth noting, because it means the repository you clone is a development workspace rather than the artifact you install. The workspaces array shows the shape: packages/nhsuk-frontend, packages/nhsuk-frontend-review, and four shared packages named shared/config, shared/helpers, shared/lib and shared/tasks. A review package alongside the main one is a pattern worth understanding, since it implies the design system is rendered somewhere in a review context, most likely so that changes to components can be inspected visually rather than only through unit tests.

The scripts: how the codebase is built, linted and watched

The scripts section of the root package.json is the clearest statement of the toolchain, and three of those entries show the shape of it.

    "build": "npm run build --if-present --workspaces",
    "lint": "npm run lint:types && npm run lint:js && npm run lint:css && npm run lint:prettier",
    "start": "npm run watch",

The build runs across all workspaces with the if-present flag, and the clean target chains through preclean and postclean to remove dist output and then clean the TypeScript build info with tsc --build --clean. The watch target runs the per-workspace watchers concurrently with kill-others, and there are separate watch tasks for the review app and the package. Linting is split into four passes, types, js, css and prettier, and there is a matching lint:fix target. Two browser automation dependencies stand out: a script that installs Playwright's chromium with its dependencies and the shell only, and a separate one for Puppeteer browsers. The repository also carries a backstop.config.js for visual regression testing, a jest-puppeteer.config.js, a wait-on.config.js for waiting on services during tests, a babel.config.js, and eslint and stylelint configurations in their modern flat config format.

Visual regression and browser support, as first class concerns

The presence of backstop.config.js in the root, alongside the Playwright and Puppeteer install scripts, says that this design system treats pixel differences as a defect worth catching. That is the norm for a design system used across many services, because a small CSS change in a shared package propagates to every consuming site at once. The browser support question is handled with the same seriousness. The README points to a support for browsers and assistive technology document for details on operating systems and software, and the repository carries a .browserslistrc file that declares the target browsers for the build tooling. There is also a .nvmrc pinning the Node version, an .npmrc for npm configuration, a .prettierrc.js and .prettierignore, an .editorconfig, a .stylelintignore, a sonar-project.properties file for code analysis, a Procfile for deployment, and a .gitpod.yml so the environment can be opened ready to code in a browser.

Design guidance lives in the service manual, not the repo

The division of responsibility is stated plainly in the README's guidance section. The NHS digital service manual is where you find examples of components and guidance for when to use them, and if guidance for the component you want has not been published yet, the README asks you to email the team or get in touch on the Slack workspace. The manual is also where the component examples live, and the README says that once you have installed the library you will be able to use the code from those design system examples in your service. That is a deliberate split: the repository carries the implementation, the manual carries the design decisions, and the two are versioned separately. It also means the guidance can lag the code, which is the practical reason to check the service manual before you rely on a component you have not used before. For a service migrating from version 9, the README points to a specific updating to version 10 guide in the manual.

The limits, and the alternative to weigh

Three things to weigh. The first is that this is a public sector design system, and adopting it means adopting NHS visual and interaction conventions. For a team outside the NHS or the UK public sector, that is a cost rather than a benefit, and there is no theme layer described anywhere in the README to make the styles your own. The second is the copying route, which quietly hands you the job of tracking upstream releases by hand, and the README's insistence that you have a plan to stay up to date is a warning about exactly this. The third is scope: this is the frontend layer, and the accessibility and content standards that NHS services are held to are only half the requirement, since a design system cannot make unclear content clear. The alternative to weigh is a general purpose CSS framework with your own tokens and components, which gives you full control and no upstream dependency, at the cost of the accessibility baseline, the tested patterns and the fact that the service manual examples and code match each other.

Editorial conclusion

Adopt NHS.UK frontend if you are building a public-facing UK health or government service and you need to meet the accessibility and consistency expectations that come with the NHS brand, since this is the codebase those services are meant to use. Do not adopt it for an internal or commercial product that has no NHS connection, because the design language and the accessibility baseline are tied to a specific public sector context. Before you start, read the installing-with-npm guide, check the browser and assistive technology support matrix for your audience, and plan how you will track release notes, because the README is explicit that you should have a plan to stay up to date with changes.

Frequently asked questions

Official sources

1. License: MIT
2. nhsuk/nhsuk-frontend on GitHub
3. Project website
4. README
5. Releases