HMRC Frontend contains the code and documentation for patterns specifically designed for HMRC.
GOV.UK Frontend and the GOV.UK Design System contains the code and documentation for design patterns designed to be used by all government departments.
The two sets of code and documentation are separate but used together.
See HMRC Design Patterns for examples of what the design patterns look like and guidance on how to use them in your service.
To install more than one version of Node.js, it may be easier to use a node version manager like nvm or n.
Clone this repository and install its dependencies.
git clone https://github.com/hmrc/hmrc-frontend.git
cd hmrc-frontend
npm install- Run
npm start - Components are available at http://localhost:3000
npm install hmrc-frontend
For use in frontend microservices running on MDTP, please refer to the README in play-frontend-hmrc.
Our SASS needs to be compilable in three different contexts:
- Within the library itself
- Within the node_modules folder of prototypes
- Within the folder that webjar assets get extracted to in tax services
SASS load paths are folders that SASS will look in for
paths you try to @import SASS files from.
The govuk-frontend dependency will be located in the node_modules directory, so it will not exist
at ../../govuk-frontend relative to the SASS files in the src/ directory.
However, because we are doing the compilation ourselves, we can modify the SASS load paths - and so we
add node_modules folder (where govuk-frontend will be located) via the "includePaths" option of the SASS library we
use.
Then, to resolve @import "../../govuk-frontend";, the SASS compiler will first try to find the file
at ../../govuk-frontend relative to the file doing the @import. Which won't be found, so then it will discard the
relative parts of the path and try to locate it within any of the folders in the configured SASS load paths - which in
this case will just be node_modules, and it will be found in node_modules/govuk-frontend.
Which means you could (though only theoretically, as you will be prevented by automated tests) have any relative path
prefix at the start of your @imports as long as the rest of the path is something that exists in the node_modules
folder.
In this case, we aren't able to add to the SASS load paths, so the relative parts at the start of our @import paths
matter.
So src/all-govuk-and-hmrc.scss will be installed
to node_modules/hmrc-frontend/hmrc/all-govuk-and-hmrc.scss and @imports of external dependencies from this file will
need to traverse up two levels to get to the node_modules folder, so @import "../../govuk-frontend"; will resolve
to node_modules/govuk-frontend.
We have an automated test to ensure that we don't use an invalid relative path that would break this use case.
The sbt-sassify plugin used by most tax services to compile SASS also has no way to add to the SASS load paths. Luckily, the subfolder structure that assets from webjars are extracted into matches what you'd find in node_modules, so the relative import paths that work for node_modules for prototypes will also work here (so long as you've got the govuk-frontend webjar in your project.)
If you need a pattern that does not appear in the HMRC Design Patterns, you can contribute a new one.
If you would like to propose a feature or raise an issue with HMRC Frontend, create an issue.
You can also create a pull request to contribute to HMRC Frontend. See our contribution process and guidelines for HMRC Frontend before you create a pull request.
This code is open source software licensed under the Apache 2.0 License.
