GOV.UK Frontend ships the design system code, not just the documentation

Four browser grades, and grade X gets no JavaScript

The most consequential decision in the README is the browser support policy, because it determines what code you are allowed to ship.

Rather than listing versions that rot, GOV.UK Frontend groups browsers into four grades. Grade A is the most recent stable versions of Chrome, Firefox, Edge, Samsung Internet and Safari. Grade B is all stable versions of Chrome, Firefox and Edge released in the last six months, plus the last four major stable Safari releases not already in grade A. Grade C is everything that supports `<script type="module">`, which the README pins to Chrome 61+, Edge 16-18 and 79+, Firefox 60+ and Safari 11+. Grade X is everything else, named explicitly as including IE11 and older.

The rule that follows is stated as a note and should be read as a hard boundary: only browsers in grades A, B and C run the JavaScript enhancements, and the project will not support its JavaScript enhancements for grade X.

That has an architectural consequence. If your service depends on an enhanced component for a core interaction, grade X users get an unenhanced page rather than a broken one. That is a deliberate progressive-enhancement design, and it means the unenhanced path has to remain usable. For a public sector service that is the point; for a marketing site where a component's behaviour is the value, it is a constraint you would have to design around.

Beyond browsers, the README lists support for recommended assistive technologies, following the GOV.UK service manual's list, and notes that users overriding colours in Windows, Firefox and Chrome is a supported scenario. There is further detail in `docs/contributing/browser-support.md` inside the repository.

Two installation routes and a mandatory upgrade plan

There are two ways in, and the README recommends the first: installing with npm using the Node.js package manager, or copying the precompiled CSS, JavaScript and asset files into your project directly.

The distinction matters more than it first appears. The file-copy route gives you no package to track, which removes a dependency but also removes every upgrade path. The npm route lets you pin a version and take patch releases on your own schedule. Either way, once installed you can use the code from the examples in the GOV.UK Design System site.

The line that most adopters skim past is this: you should also have a plan to stay up to date with changes. The project links dedicated guidance on staying current, and that expectation is the real commitment of using a centrally maintained design system. Your service's look and behaviour are coupled to a version published by a team in a government department, and that team publishes minor versions roughly monthly, as the recent tags show with v6.6.0 on 2026-10-15, v6.5.1 on 2026-09-14 and v6.5.0 on 2026-08-27.

The repository is an npm workspaces monorepo. The root `package.json` is marked private and named `@govuk-frontend/repository`, with a description that says it is used only for development and points to `packages/govuk-frontend/package.json` for the published manifest. Workspaces cover the published package, a review app, shared tooling, tests and documentation examples. Toolchain requirements are declared as Node `^24.11.0` and npm `^11.16.0`, which is a meaningful constraint if your build environment is older.

Accessibility is a starting point, not a certificate

The README is unusually direct about this, and the phrasing is the point.

Using GOV.UK Frontend will help your service meet level AA of WCAG 2.2. But you must still check that your service meets accessibility requirements, especially if you extend or modify components. Two further instructions follow: you should also use the JavaScript from GOV.UK Frontend, and read the accessibility statement for the GOV.UK Design System.

The emphasis on extending or modifying components is doing real work. The most common way a compliant design system becomes a non-compliant service is a team adding a wrapper div, a custom validation message or a required-field marker to a component without re-testing contrast, focus order and announced labels. The design system gives you a tested baseline for the component as shipped, and nothing beyond that.

The README also names recommended assistive technologies through the GOV.UK service manual, which is a hint about how testing is expected to be carried out rather than a claim that every combination has been verified.

For teams that want the reasoning rather than the assertion, the design system's accessibility statement is the place to look. The GDS design team says it works hard to ensure GOV.UK Frontend is accessible, which is a statement about effort, not about your service after you have changed it.

The list of validator complaints that are not your fault

Every design system with opinionated markup gets false positives from automated tooling, and GOV.UK Frontend publishes the list rather than leaving you to argue with your own CI.

The README points to a project board of known issues that may be reported by HTML validators or automated testing tools. This is the kind of document that saves hours: a markup pattern chosen deliberately for a reason, an automated rule that objects to it anyway, and a written confirmation that the objection is known.

That is not an excuse to disable validators. It is a separation between two different tools. An HTML validator tells you about syntax; an automated accessibility checker tells you about probable issues, and both produce findings that overlap with design decisions a service has already made. Knowing which findings are expected is what lets you keep both in your pipeline instead of switching one off.

The same reasoning applies to the test setup visible in the repository. There are separate Jest projects for build tasks, with `postbuild:package` running the package build tests and `postbuild:release` running the release build tests, plus `jest-puppeteer.config.js`, `jest-dev-server.config.js` and `puppeteer.config.js`. The repository includes Jest build-task tests and separate Puppeteer and development-server configuration files.

Licensing splits the code from the documentation

The licence position has two parts and they differ.

Unless stated otherwise, the codebase is released under the MIT License, and the README says this covers both the codebase and any sample code in the documentation. The `LICENSE.txt` file is at the repository root.

The documentation itself is Crown copyright and available under the terms of the Open Government 3.0 licence. In practice that means the prose guidance is reusable with attribution under OGL, while the code is reusable under MIT, which is more permissive for embedding in a product. If you fork this into a commercial design system, the code must retain the MIT licence notices and the written guidance carries an attribution requirement.

For governance, contributions are governed by the Contributor Covenant Code of Conduct for the alphagov organisation, and contributors working within government are also expected to follow the Civil Service code. That second clause is unusual outside a government context and is a reasonable signal about how decisions get made here: the maintainers are a team at the Government Digital Service, not a foundation or a company.

Contact routes are a government email address for the Design System team and a Slack channel, and the README states plainly that the repository cannot be monitored outside office hours of 10am to 4pm UK time, directing abuse and spam reports to GitHub instead. That is a real operational constraint if you are depending on rapid responses to a security issue.

On security, GDS describes itself as an advocate of responsible vulnerability disclosure and points to the repository's own security policy for the disclosure process.

When not to use it

Three cases argue against GOV.UK Frontend, and none of them are about quality.

Visual identity. The design system is deliberately distinctive and deliberately not neutral. If your product needs to look like nothing else, adopting it means fighting the components, and if you override enough of it you have reimplemented it with an extra dependency. This is not a criticism; it is a design system doing its job.

JavaScript-dependent interactivity. Grade X receives no enhancements, so any interaction that only works with the JavaScript is unavailable to those browsers. In a government service that trade is made deliberately, and the unenhanced path is designed to be usable. In a booking flow or an editor, you are choosing between supporting legacy browsers and keeping the design system.

Upgrade appetite. A central team publishing minor versions monthly, with documented expectations that you plan for updates, means an ongoing maintenance commitment. If your team cannot absorb a design system upgrade twice a quarter, a smaller set of components you own entirely may serve you better.

The comparison worth making against alternatives is not against other government design systems, of which there are few worth naming as substitutes. It is against a component library you own and a bespoke build. GOV.UK Frontend wins when your users include people using assistive technology, older browsers, or Windows high contrast, because the testing against those cases is documented work that nobody on a product team would otherwise do. If your user population is narrow on all three counts, you are paying for coverage you will not use.

Editorial conclusion

GOV.UK Frontend is the right choice for a UK government service that has to satisfy the design system team's accessibility and browser support expectations, and it is a defensible choice for any team that values documented, tested accessibility defaults over visual novelty. Do not adopt it for a consumer product wanting a distinctive look, and do not treat installing it as an accessibility pass, because the README states you must still check your own service. Verify first which browser grades your user base actually falls into, since grade X receives no JavaScript enhancements at all, and read the staying-up-to-date guidance before you commit to the upgrade route.

Frequently asked questions

Official sources

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