The GOV.UK Design System repository is the website, not the code services install

The first line of the README redirects you to another repository

Almost everything a newcomer needs to know is in the opening paragraph, and the first thing it says is that this repository contains the code for the GOV.UK Design System website, and that to find the code provided for reuse by services you should go to the govuk-frontend repository. That split is the single fact that shapes any decision about adopting this project. The design system as a published artefact is govuk-frontend, distributed to service teams as an npm package. What lives here is the site: the guidance, the examples, the documentation and the patterns that explain how a government service is supposed to look. The repository description puts it as one place for service teams to find styles, components and patterns for designing government services, and the homepage is the public design system site rather than a package page, which confirms the split. The primary language in the repository is listed as Nunjucks, which is the template language the site itself is written in.

The build is a set of custom Node tasks, not a framework

There is no Eleventy, no Jekyll and no static site generator in the stack, and that is worth understanding before you try to build it. The package.json scripts point at files in a tasks/ directory, and each one is a small Node program invoked with cross-env to set the environment. The build script runs the production task with NODE_ENV=production, the serve script runs a production server with DEBUG=build* enabled, and the start script runs the development task with NODE_ENV=development and the same debug flag. The source lives in src/ and the built output in build/, with a config/ directory for configuration, views/ for the templates, data/ for the content, lib/ for shared code and a __tests__/ directory for the test suite. The build tool for the npm package is Rollup, with rollup.config.js at the root, and the type checking runs through tsconfig.json with tsc --build. So the site is assembled by hand-written tasks, which is more code to read than a framework would be, and also more control over exactly what a build does.

Running it locally is clone, install, start

The local setup is documented in a way that leaves little ambiguity, which is unusual and welcome. You need Git and Node.js, and the README is explicit that the project requires the active LTS version of Node.js as specified in the .nvmrc file, with a note that the active LTS is a moving target. There is a .nvmrc file in the repository and a .npmrc file next to it, and if you work across several Node projects the README recommends nvm, with nvm install run in the project directory to pick up the version from .nvmrc. External contributors are asked to fork the repository first, and then the clone and install are two commands:

git clone [email protected]:alphagov/govuk-design-system.git # or clone your own fork

cd govuk-design-system

@@C1@@The install step is a plain npm install, and the dev server is npm start, which the README says builds the sources, serves the pages and watches for changes. By default it accepts connections only from the same machine, and to test from another device you set an environment variable:

ALLOW_EXTERNAL_CONNECTIONS=true npm start

@@C2@@That default is the right one for a site that serves previews of unreleased guidance, and the escape hatch is documented rather than hidden.

The lint command is six checks, and two of them rebuild the site

The lint script is the part of this repository that tells you how the team works, because it is unusually broad.

npm run lint

It chains lint:editorconfig, lint:prettier, lint:js, lint:types, lint:scss and lint:html with the ignore-scripts flag. EditorConfig and Prettier both run in check mode over matching file globs, ESLint runs with a cache and the .gitignore as its ignore path, stylelint runs with --max-warnings 0 over Sass and Markdown, and TypeScript is built rather than merely checked. The HTML validation is the interesting one: it runs html-validate against the built output, and it has a prelint:html hook that runs the build first, so validating the HTML means generating the site rather than linting a template in isolation. The same build-first pattern appears on the test side, where the pretest script runs npm run build before jest. The practical cost of that convention is that a full lint or test run is slower than a targeted one, and the benefit is that the checks run against the same artefacts a deployment would use.

Continuous integration runs the tests, the Sass lint and the build

The README describes what GitHub Actions does when changes are pushed, and the list is short enough to quote without distortion: it runs the tests, it lints the Sass stylesheets in source/stylesheets, and it runs the npm run build command to ensure that the site can be generated. If any of these fail, the result is reported in the GitHub status checks interface. There is no separate lint job for the other linters in that list, which suggests the Sass lint and the test run are the two gates that block a merge while the rest of the lint suite runs elsewhere or is advisory. The tests themselves are Jest, with a jest.config.mjs and a separate jest-puppeteer.config.js, so there is browser-level testing in the suite and not only unit tests. The __tests__/ directory at the root holds the JavaScript tests, and there is a package-lock.json.unit.test.mjs file, which is a separate test target for the lockfile itself. Deployment details, including how the site reaches production and how branch and pull request previews are deployed, live in docs/deployment.md rather than in the README.

The design system consumes GOV.UK Frontend from npm, not from a sibling directory

The dependency direction is the part that trips people up. The README says the Design System consumes the GOV.UK Frontend package via NPM, and that this is defined in the package.json file, with a link to the GOV.UK Frontend project. So the website builds against the published version of the component library rather than a checkout of it, which means a change to a component and a change to the documentation that describes it land in two repositories and are released independently. The package.json reinforces the point with a postinstall script of npm ls --depth=0, which prints the resolved dependency tree after install, which is a cheap way to see exactly which build of GOV.UK Frontend a local site is using. There is a link-checking script too, check-links, running hyperlink with a canonical root, and a .htmlvalidate.js and .htmlvalidateignore pair for the HTML rules, so the link and markup checks are as much a part of the build as the tests.

MIT for the site code, and a different repository for the components

The licence question has two halves and the one that matters for most adopters is the other repository. This repository is MIT licensed, with the LICENSE file at the root and the licence recorded in package.json under Government Digital Service developers as the author, and the package itself marked private. The private flag matters: this is not published to npm, it is a website build, and the design system consumes GOV.UK Frontend instead. The repository also carries a CODEOWNERS file, a .husky/ directory and a .lintstagedrc.js, which together describe a commit-hook and review-ownership setup, plus a netlify.toml and a .browserslistrc. The README asks for responsible vulnerability disclosure through the security policy, and states that the team monitors the repository during office hours of 10am to 4pm UK time, with abuse and spam reports going to GitHub. For contributors, the code of conduct is the Contributor Covenant, and contributors working within government are also expected to follow the Civil Service code. The repository publishes no GitHub releases, and the last push was on 2026-10-20, so the deployed site is the artefact rather than a tagged version.

Editorial conclusion

alphagov/govuk-design-system suits a contributor who wants to change the guidance, examples and documentation published at gov.uk/design-system, and it suits a team that wants to see how a design system is maintained rather than just consumed. It does not suit a service team looking for the components themselves, because the README says to go to the govuk-frontend repository for reusable code, and the design system consumes that package from npm rather than vendoring it. Before starting, read the .nvmrc file and install the active LTS Node.js version it names, because the project requires it, and note that the last push to the repository was on 2026-10-20 with no GitHub releases published, so the build itself is the release.

Frequently asked questions

Official sources

1. alphagov/govuk-design-system on GitHub
2. Issues
3. License: MIT
4. Project website
5. README