Deprecation

🚨 Assets Frontend has been deprecated in favour of the Play Frontend. 🚨

If you do decide to use Assets Frontend anyway you need to be aware of the vulnerabilities including but not limited to the ones listed here ]https://github.com/hmrc/assets-frontend/security/dependabot](https://github.com/hmrc/assets-frontend/security/dependabot). There are also known accessibility issues when using Assets Frontend which will cause delays with going live. As of 13th October 2021, we won't be making updates to Assets Frontend so we recommend moving over to the latest Play Frontend Libraries

assets-frontend

This repository contains the source files and documentation for the Components & Design Patterns used to design and build digital services for the HMRC Tax Platform.

It provides additional styles on top of the GOV.UK styles.

Quick Start

Requirements

• Node.js == 4.8.4
• npm >= 2.11.3

To install multiple versions of Node.js, you may find it easier to use a node version manager:

• nvm
• n

Installation

Clone this repository and install its dependencies:

$ git clone https://github.com/hmrc/assets-frontend.git
$ cd assets-frontend
$ npm install

Running

The Component Library microsite

1. Clone the repo locally: git clone https://github.com/hmrc/assets-frontend.git
2. In your file system, navigate to the assets-frontend directory: cd assets-frontend
3. Checkout the gh-pages branch: git checkout gh-pages
4. In your file system, navigate one directory level above the assets-frontend folder: cd ../
5. Start a local server for serving the pages: python3 -m http.server --cgi 8888
6. In the browser, navigate to to http://localhost:8888/assets-frontend

The Design System:

1. Run npm start
2. The Design System is available at http://localhost:9034/
3. Latest V4 Assets are then available at http://localhost:9032/assets/v4-SNAPSHOT/...
4. Latest V3 Assets are then available at http://localhost:9032/assets/v3-SNAPSHOT/...

To access both the Design System and the Component Library [DEPRECATED]

1. Run npm run dev:all or ./server.sh dev
2. The Design System is available at http://localhost:9034/
3. The Component Library is available at http://localhost:9033/

To run a specific version of Assets Frontend locally

1. Run ./server.sh
2. V4 Assets are then available at http://localhost:9032/assets/4.11.0/...
3. V3 Assets are then available at http://localhost:9032/assets/3.11.0/...

Usage

Using assets locally

Prototypes

For now, the quickest and simplest way to add assets-frontend to your prototype is to grab the built CSS and JS from production.

Just replace <VERSION> in the links below with the released version you want to use (we recommend using the latest).

If your prototype is based on the GOV.UK prototype kit then do the following:

CSS

Save the file found at https://www.tax.service.gov.uk/assets/<VERSION>/stylesheets/application.min.css to /app/assets/sass/assets-frontend.css.

And add the following to app/views/includes/head.html:

<link href="/public/stylesheets/assets-frontend.css" rel="stylesheet" type="text/css" />

JavaScript

Save the file found at https://www.tax.service.gov.uk/assets/<VERSION>/javascripts/application.min.js to /app/assets/javascripts/assets-frontend.js

And add the following to app/views/includes/head.html

<script src="/public/javascripts/assets-frontend.js"></script>

Frontends

If your frontend is based on init-service, then you just need to make sure the configuration for assets in the application.conf file has the line version = ${?ASSETS_FRONTEND_VERSION} after declaring the actual version.

Once it has, you just need to set an environment variable before running your frontend:

$ ASSETS_FRONTEND_VERSION=999-SNAPSHOT sbt run

If you’re using service-manager, please read the service manager guidance in the Wiki.

Using assets in production

Running npm run release calls the release gulp task and this happens on our internal Jenkins instances.

The final step of our internal release pipeline is to version and deploy the compiled assets to https://www.tax.service.gov.uk/assets/.

Releasing assets for use in production is currently a process owned by the Service Design Tools team.

If you’d like a new version of assets-frontend released, please get in touch with us in the #team-sdt Slack channel.

HMRC Design System

The HMRC Design System can be viewed here.

For detailed information on how the HMRC Design System works, please read the Design System page in the Wiki.

Component Library - [DEPRECATED]

🚨 The Component Library has been deprecated in favour of the HMRC Design System.🚨

If your service relies on a component or pattern that doesn’t appear in the HMRC Design System then please follow the Design System contribution guidelines.

For detailed information on how the Component Library works, please read the Component Library guidance in the Wiki.

Contributing

Design Patterns

For details on how to contribute Design Patterns, please take a few minutes to review our Design Pattern standards and contribution process before you submit your request, otherwise it may be rejected.

Features and issues

If you’ve spotted an issue or thought of a feature that you’d like to contribute to assets-frontend, please take a few minutes to review our contribution process and guidelines for Assets Frontend before you submit your request, otherwise it may be rejected.

License

This code is open source software licensed under the Apache 2.0 License.